Refactor Knowledge Base Schema to Fix Type Regression #7300

Author: tobiu

.github/ISSUE/ticket-refactor-kb-schema-for-type-regression.md

@@ -0,0 +1,22 @@
+# Ticket: Refactor Knowledge Base Schema to Fix Type Regression
+
+GH ticket id: #7300
+
+**Assignee:** tobiu
+**Labels:** `bug`, `regression`, `refactoring`, `ai-tools`
+
+## Description
+
+The AI query tool (`npm run ai:query`) fails for `--type example` because the knowledge base creation script does not correctly assign a high-level `type` to items originating from the `/examples` directory. The current implementation uses `type` to store the specific code construct (`class`, `method`), creating a conflict.
+
+This ticket refactors the knowledge base schema to solve this regression and make the data model more robust.
+
+### Tasks:
+
+1.  **Modify `buildScripts/ai/createKnowledgeBase.mjs`:**
+    -   For each chunk generated from the JSDoc output (`all.json`), add a `type` property (`src`, `example`, etc.) based on its source file path.
+    -   Rename the existing `type` property (which currently holds `class`, `method`, etc.) to `kind` to avoid conflicts.
+    -   For non-JSDoc chunks (guides, releases, tickets), ensure they also have both a `type` and a `kind` property (where both can have the same value, e.g., `type: 'guide'`, `kind: 'guide'`).
+
+2.  **Verify `buildScripts/ai/queryKnowledgeBase.mjs`:**
+    -   Confirm that the existing query logic, which filters on the `type` property, works correctly with the new schema without modification.

buildScripts/ai/createKnowledgeBase.mjs

@@ -4,9 +4,8 @@ import path   from 'path';
 import dotenv from 'dotenv';
 
 const
-    cwd         = process.cwd(),
-    insideNeo   = process.env.npm_package_name.includes('neo.mjs'),
-    neoPath     = path.resolve(insideNeo ? './' : './node_modules/neo.mjs/');
+    cwd       = process.cwd(),
+    insideNeo = process.env.npm_package_name.includes('neo.mjs');
 
 dotenv.config({
     path: insideNeo ? path.resolve(cwd, '.env') : path.resolve(cwd, '../../.env')
@@ -69,19 +68,25 @@ class CreateKnowledgeBase {
 
         apiData.forEach(item => {
             const sourceFile = item.meta ? path.join(item.meta.path, item.meta.filename) : 'unknown';
-            let chunk;
+            let chunk, type = 'src';
+
+            if (sourceFile.includes('/examples/')) {
+                type = 'example';
+            }
 
             if (item.kind === 'class') {
                 chunk = {
-                    type       : 'class',
+                    type,
+                    kind       : 'class',
                     name       : item.longname,
                     description: item.comment,
                     extends    : item.augments?.[0], // Capture the parent class
                     source     : sourceFile
                 };
             } else if (item.kind === 'member' && item.memberof) {
                 chunk = {
-                    type       : 'config',
+                    type,
+                    kind       : 'config',
                     className  : item.memberof,
                     name       : item.name,
                     description: item.description,
@@ -90,7 +95,8 @@ class CreateKnowledgeBase {
                 };
             } else if (item.kind === 'function' && item.memberof) {
                 chunk = {
-                    type       : 'method',
+                    type,
+                    kind       : 'method',
                     className  : item.memberof,
                     name       : item.name,
                     description: item.description,
@@ -138,6 +144,7 @@ class CreateKnowledgeBase {
                                 chunkName    = `${item.name} - ${heading}`,
                                 chunk        = {
                                     type   : 'guide',
+                                    kind   : 'guide',
                                     name   : chunkName,
                                     id     : item.id,
                                     isBlog : item.parentId === 'Blog',
@@ -153,6 +160,7 @@ class CreateKnowledgeBase {
                         // If no headings, add the whole file as one chunk
                         const chunk = {
                             type   : 'guide',
+                            kind   : 'guide',
                             name   : item.name,
                             id     : item.id,
                             isBlog : item.parentId === 'Blog',
@@ -183,6 +191,7 @@ class CreateKnowledgeBase {
 
                 const chunk = {
                     type   : 'release',
+                    kind   : 'release',
                     name   : chunkName,
                     content: content,
                     source : filePath
@@ -217,6 +226,7 @@ class CreateKnowledgeBase {
 
                             const chunk = {
                                 type   : 'ticket',
+                                kind   : 'ticket',
                                 name   : chunkName,
                                 content: content,
                                 source : filePath