Create Class Hierarchy YAML #7246

Author: tobiu

.github/ISSUE/ticket-create-class-hierarchy-yaml.md

@@ -0,0 +1,22 @@
+# Ticket: Create Class Hierarchy YAML
+
+GH ticket id: #7246
+
+**Assignee:** Gemini
+**Status:** Done
+
+## Description
+
+The current `docs/output/structure.json` file is too large and inefficient for AI agent consumption. To provide a lean but effective overview of the project's class structure, we will create a new build artifact.
+
+## Goal
+
+Modify the `buildScripts/docs/jsdocx.mjs` script to generate a new file at `docs/output/class-hierarchy.yaml`.
+
+### Requirements:
+
+1.  **Format:** The file must be in YAML.
+2.  **Content:** It will contain a simple key-value mapping of `className: parentClassName`.
+3.  **Sorting:** The entries must be sorted alphabetically by the `className` (the key).
+4.  **Implementation:** This will be done within the existing `jsdocx.mjs` script, leveraging the already-parsed documentation data.
+5.  **Agent Integration:** Update `AGENTS.md` to instruct the agent to parse `docs/output/class-hierarchy.yaml` instead of the old `structure.json` file.

AGENTS.md

@@ -15,8 +15,8 @@ about the framework. The **ONLY** source of truth is the content within this rep
 
 At the beginning of every new session, you **MUST** perform the following steps to ground your understanding of the framework:
 
-1.  **Read the Codebase Structure:** Parse the file `docs/output/structure.json`. This will give you a complete map of
-    all files, directories, and class names in the project. If this file is missing, you can generate it by running
+1.  **Read the Codebase Structure:** Parse the file `docs/output/class-hierarchy.yaml`. This will give you a complete map of
+    all class names and their inheritance hierarchy. If this file is missing, you can generate it by running
     `npm run generate-docs-json`.
 
 2.  **Read the Core Concepts (`src/Neo.mjs`):** When reading this file, focus on understanding:

buildScripts/docs/jsdocx.mjs

@@ -397,6 +397,26 @@ jsdocx.parse(options)
             generateStructure(key + 'Empty', 2, docs);
         });
 
+        const classHierarchy = {};
+
+        docs.forEach(item => {
+            if (item.$kind === 'class' && item.neoClassName && item.neoClassName !== 'Neo') {
+                const parentClass = item.augments && item.augments.length > 0 ? item.augments[0] : null;
+                classHierarchy[item.neoClassName] = parentClass;
+            }
+        });
+
+        const sortedKeys = Object.keys(classHierarchy).sort();
+
+        let yamlString = '# This file is automatically generated. Do not edit.\n\n';
+        sortedKeys.forEach(key => {
+            yamlString += `${key}: ${classHierarchy[key] || 'null'}\n`;
+        });
+
+                fs.writeFileSync('./docs/output/class-hierarchy.yaml', yamlString);
+
+        console.log('Generated docs/output/class-hierarchy.yaml');
+
         neoStructure.sort(function (a, b) {
             if (a.name[0] === a.name[0].toLocaleLowerCase() && b.name[0] === b.name[0].toLocaleLowerCase() ||
                 a.name[0] === a.name[0].toLocaleUpperCase() && b.name[0] === b.name[0].toLocaleUpperCase()) {