code-graph-llm 1.3.0 → 1.4.1

package/README.md

@@ -3,14 +3,14 @@
 A language-agnostic, ultra-compact codebase mapper designed specifically for LLM agents to optimize context and token usage. It doesn't just list files; it provides a high-signal "map" of your project's architecture, including descriptions and signatures.
 
 ## Features
-- **Smart Context Extraction:** Captures JSDoc, Python docstrings, and preceding comments for files and symbols.
-- **Signature Fallback:** Automatically extracts function signatures (parameters/types) if documentation is missing.
-- **Recursive .gitignore Support:** Deeply respects both root and nested `.gitignore` files across the entire project structure.
-- **Smart Flutter/Dart Support:** Optimized to reduce noise by filtering out common widget instantiations while capturing real functional declarations.
-- **Compact & Dense:** Optimized for LLM token efficiency, replacing expensive recursive file scans.
-- **Language-Agnostic:** Optimized regex support for JS/TS, Python, Go, Rust, Java, C#, C/C++, Swift, PHP, Ruby, Dart, and more.
-- **Recursive Ignore Logic:** Deeply respects `.gitignore` and standard excludes (`node_modules`, `.git`).
-- **Live Sync:** Continuous background updates or Git pre-commit hooks.
+- **Structural Knowledge Graph:** Captures relationships between files and classes:
+  - **Dependencies:** Tracks `imports`, `requires`, and `includes` across files.
+  - **Inheritance:** Maps `extends`, `implements`, and class hierarchies.
+- **Smart Context Extraction:** Captures JSDoc, Python docstrings, and preceding comments.
+- **Signature Fallback:** Extracts function signatures (parameters/types) if documentation is missing.
+- **Recursive .gitignore Support:** Deeply respects both root and nested `.gitignore` files.
+- **Compact & Dense:** Optimized for LLM token efficiency with a dedicated `## GRAPH EDGES` section.
+- **Language-Agnostic:** Support for JS/TS, Python, Go, Rust, Java, C#, C/C++, Swift, PHP, Ruby, Dart, and more.
 
 ## Installation
 
@@ -38,12 +38,16 @@ code-graph install-hook
 ## LLM Usage & Token Efficiency
 
 ### The "Read First" Strategy
-Instruct your LLM agent to read `llm-code-graph.md` as its first step. The file uses a dense format that provides immediate architectural context:
+Instruct your LLM agent to read `llm-code-graph.md` as its first step. The file provides a high-level map and a structural graph for relational reasoning:
 
 **Example Map Entry:**
 ```markdown
-- src/auth.js | desc: Handles user authentication and JWT validation.
+- src/auth.js | desc: Handles user authentication.
   - syms: [login [ (username, password) ], validateToken [ (token: string) ]]
+
+## GRAPH EDGES
+[src/auth.js] -> [imports] -> [jwt-library]
+[AdminUser] -> [inherits] -> [BaseUser]
 ```
 
 **Example System Prompt:**
@@ -78,13 +82,9 @@ fn main() {
 ```
 
 ## How it works
-1. **File Scanning:** Recursively walks the directory, ignoring patterns in `.gitignore`.
-2. **Context Extraction:** Scans for classes, functions, and variables.
-3. **Docstring Capture:** If a symbol has a preceding comment (`//`, `/**`, `#`, `"""`), it's captured as a description.
-4. **Signature Capture:** If no comment is found, it captures the declaration signature (parameters) as a fallback.
-5. **Compilation:** Writes a single, minified `llm-code-graph.md` file designed for machine consumption.
-
-## Publishing as a Package
-To share your own version:
-1. `npm login`
-2. `npm publish --access public`
+1. **File Scanning:** Recursively walks the directory, ignoring patterns in `.gitignore` (recursive).
+2. **Context Extraction:** Scans for classes, functions, and variables while ignoring matches in comments.
+3. **Graph Extraction:** Identifies `imports`, `requires`, `extends`, and `implements` to build a structural skeleton.
+4. **Docstring Capture:** Captures preceding comments as descriptions.
+5. **Signature Capture:** Fallback to declaration signatures (parameters) if docs are missing.
+6. **Compilation:** Writes a single, minified `llm-code-graph.md` file with a dedicated `## GRAPH EDGES` section.

package/index.js

@@ -13,20 +13,27 @@ const IGNORE_FILE = '.gitignore';
 const DEFAULT_MAP_FILE = 'llm-code-graph.md';
 
 const SYMBOL_REGEXES = [
-  // Types, Classes, Interfaces (Universal)
-  /\b(?:class|interface|type|struct|enum|protocol|extension|trait|module|namespace|object)\s+([a-zA-Z_]\w*)/g,
+  // Types, Classes, Interfaces (Universal) with Inheritance support
+  // Captures: class Name extends Parent, interface Name implements Base
+  /\b(?:class|interface|type|struct|enum|protocol|extension|trait|module|namespace|object)\s+([a-zA-Z_]\w*)(?:\s+(?:extends|implements|:)\s+([a-zA-Z_]\w*(?:\s*,\s*[a-zA-Z_]\w*)*))?/g,
   
   // Explicit Function Keywords
   /\b(?:function|def|fn|func|fun|method|procedure|sub|routine)\s+([a-zA-Z_]\w*)/g,
   
   // Method/Var Declarations (C-style, Java, C#, TS, Dart)
-  // Refined to require a variable/function name followed by a declaration signal
   /\b(?:void|async|public|private|protected|static|virtual|override|readonly|int|float|double|char|bool|string|val|var|let|final)\s+([a-zA-Z_]\w*)(?=\s*(?:\([^)]*\)|[a-zA-Z_]\w*)\s*(?:\{|=>|;|=))/g,
   
   // Exported symbols
   /\bexport\s+(?:default\s+)?(?:const|let|var|function|class|type|interface|enum|async|val)\s+([a-zA-Z_]\w*)/g
 ];
 
+const EDGE_REGEXES = [
+  // Imports/Includes (JS, TS, Python, Go, Rust, C++, Java, Dart)
+  /\b(?:import|from|include|require|using)\s*(?:[\(\s])\s*['"]?([@\w\.\/\-]+)['"]?/g,
+  // C-style includes
+  /#include\s+[<"]([\w\.\/\-]+)[>"]/g
+];
+
 export const SUPPORTED_EXTENSIONS = [
   '.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java', 
   '.cpp', '.c', '.h', '.hpp', '.cc', '.rb', '.php', '.swift', 
@@ -48,31 +55,51 @@ export function getIgnores(cwd, additionalLines = []) {
   return ig;
 }
 
-export function extractSymbols(content) {
+export function extractSymbolsAndInheritance(content) {
   const symbols = [];
+  const inheritance = [];
+  
+  // Create a version of content without comments to find symbols accurately
+  const noComments = content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, '');
+
   for (const regex of SYMBOL_REGEXES) {
     let match;
     regex.lastIndex = 0;
-    while ((match = regex.exec(content)) !== null) {
+    while ((match = regex.exec(noComments)) !== null) {
       if (match[1]) {
         const symbolName = match[1];
-        if (['if', 'for', 'while', 'switch', 'return', 'await', 'yield', 'const', 'new'].includes(symbolName)) continue;
+        if (['if', 'for', 'while', 'switch', 'return', 'await', 'yield', 'const', 'new', 'let', 'var'].includes(symbolName)) continue;
+
+        // Capture inheritance if present (match[2])
+        if (match[2]) {
+          const parents = match[2].split(',').map(p => p.trim());
+          parents.forEach(parent => {
+            inheritance.push({ child: symbolName, parent });
+          });
+        }
+
+        // To find the comment, we need to find the position in the ORIGINAL content
+        const escapedName = symbolName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const posRegex = new RegExp(`\\b${escapedName}\\b`, 'g');
+        let posMatch = posRegex.exec(content);
+        if (!posMatch) continue;
 
-        const linesBefore = content.substring(0, match.index).split('\n');
+        const linesBefore = content.substring(0, posMatch.index).split('\n');
         let comment = '';
-        for (let i = linesBefore.length - 1; i >= 0; i--) {
+        // Skip the current line where the symbol is defined
+        for (let i = linesBefore.length - 2; i >= 0; i--) {
           const line = linesBefore[i].trim();
-          if (line.startsWith('//') || line.startsWith('*') || line.startsWith('"""') || line.startsWith('#')) {
+          if (line.startsWith('//') || line.startsWith('*') || line.startsWith('"""') || line.startsWith('#') || line.startsWith('/*')) {
             const clean = line.replace(/[\/*#"]/g, '').trim();
             if (clean) comment = clean + (comment ? ' ' + comment : '');
-            if (comment.length > 80) break; 
+            if (comment.length > 100) break; 
           } else if (line === '' && comment === '') continue;
           else break;
         }
 
         let context = comment;
         if (!context) {
-          const remainingLine = content.substring(match.index + match[0].length);
+          const remainingLine = content.substring(posMatch.index + symbolName.length);
           const sigMatch = remainingLine.match(/^\s*(\([^)]*\)|[^\n{;]*)/);
           if (sigMatch && sigMatch[1].trim()) {
             context = sigMatch[1].trim();
@@ -83,14 +110,35 @@ export function extractSymbols(content) {
       }
     }
   }
-  return Array.from(new Set(symbols)).sort();
+  return { 
+    symbols: Array.from(new Set(symbols)).sort(),
+    inheritance: Array.from(new Set(inheritance.map(JSON.stringify))).map(JSON.parse)
+  };
+}
+
+export function extractEdges(content) {
+  const dependencies = new Set();
+  const noComments = content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, '');
+  for (const regex of EDGE_REGEXES) {
+    let match;
+    regex.lastIndex = 0;
+    while ((match = regex.exec(noComments)) !== null) {
+      if (match[1]) {
+        const dep = match[1];
+        if (dep.length > 1 && !['style', 'react', 'vue', 'flutter'].includes(dep.toLowerCase())) {
+          dependencies.add(dep);
+        }
+      }
+    }
+  }
+  return Array.from(dependencies).sort();
 }
 
 async function generate(cwd = process.cwd()) {
   const files = [];
+  const allEdges = [];
 
   function walk(dir, ig) {
-    // Check for local .gitignore and create a new scoped ignore object if found
     let localIg = ig;
     const localIgnorePath = path.join(dir, IGNORE_FILE);
     if (fs.existsSync(localIgnorePath) && dir !== cwd) {
@@ -98,7 +146,6 @@ async function generate(cwd = process.cwd()) {
       const lines = content.split('\n').map(line => {
           line = line.trim();
           if (!line || line.startsWith('#')) return null;
-          // Rules in sub-gitignore are relative to that directory
           const relDir = path.relative(cwd, dir).replace(/\\/g, '/');
           return relDir ? `${relDir}/${line}` : line;
       }).filter(Boolean);
@@ -121,17 +168,34 @@ async function generate(cwd = process.cwd()) {
         const ext = path.extname(entry.name);
         if (SUPPORTED_EXTENSIONS.includes(ext)) {
           const content = fs.readFileSync(fullPath, 'utf8');
-          const firstLines = content.split('\n').slice(0, 5);
+          
+          // Extract file-level description
+          const lines = content.split('\n');
           let fileDesc = '';
-          for (const line of firstLines) {
-            const trimmed = line.trim();
-            if (trimmed.startsWith('//') || trimmed.startsWith('#') || trimmed.startsWith('/*')) {
-              fileDesc += trimmed.replace(/[\/*#]/g, '').trim() + ' ';
+          for (let i = 0; i < Math.min(10, lines.length); i++) {
+            const line = lines[i].trim();
+            if (line.startsWith('#!') || line === '') continue;
+            if (line.startsWith('//') || line.startsWith('#') || line.startsWith('/*')) {
+              fileDesc += line.replace(/[\/*#]/g, '').trim() + ' ';
+            } else {
+              break; 
             }
           }
-          const symbols = extractSymbols(content);
+
+          const { symbols, inheritance } = extractSymbolsAndInheritance(content);
+          const dependencies = extractEdges(content);
+          
           if (!fileDesc.trim() && symbols.length > 0) fileDesc = `Contains ${symbols.length} symbols.`;
+          
           files.push({ path: normalizedPath, desc: fileDesc.trim(), symbols });
+          
+          // Collect Edges
+          dependencies.forEach(dep => {
+            allEdges.push(`[${normalizedPath}] -> [imports] -> [${dep}]`);
+          });
+          inheritance.forEach(inh => {
+            allEdges.push(`[${inh.child}] -> [inherits] -> [${inh.parent}]`);
+          });
         }
       }
     }
@@ -139,14 +203,18 @@ async function generate(cwd = process.cwd()) {
 
   walk(cwd, getIgnores(cwd));
 
-  const output = files.map(f => {
+  const nodesOutput = files.map(f => {
     const descStr = f.desc ? ` | desc: ${f.desc.substring(0, 100)}` : '';
     const symStr = f.symbols.length > 0 ? `\n  - syms: [${f.symbols.join(', ')}]` : '';
     return `- ${f.path}${descStr}${symStr}`;
   }).join('\n');
 
+  const edgesOutput = allEdges.length > 0 
+    ? `\n\n## GRAPH EDGES\n${Array.from(new Set(allEdges)).sort().join('\n')}` 
+    : '';
+
   const header = `# CODE_GRAPH_MAP\n> LLM_ONLY: DO NOT EDIT. COMPACT PROJECT MAP.\n\n`;
-  fs.writeFileSync(path.join(cwd, DEFAULT_MAP_FILE), header + output);
+  fs.writeFileSync(path.join(cwd, DEFAULT_MAP_FILE), header + nodesOutput + edgesOutput);
   console.log(`[Code-Graph] Updated ${DEFAULT_MAP_FILE}`);
 }
 

package/llm-code-graph.md

@@ -1,10 +1,29 @@
 # CODE_GRAPH_MAP
 > LLM_ONLY: DO NOT EDIT. COMPACT PROJECT MAP.
 
-- .gitignore
-- index.js | desc: !usrbinenv node
-  - syms: [Name [Dart:], Name [PHP: class Name, interface Name, trait Name,], Name [PHP: class Name, interface Name,], Name [PHP: class Name,], Name [PHP:], Name [Ruby: def name, class Name,], Name [Ruby: def name,], Name [Swift: func name, class Name, struct Name, protocol Name,], Name [Swift: func name, class Name, struct Name,], Name [Swift: func name, class Name,], Name [Swift: func name,], SUPPORTED_EXTENSIONS [= [], extractSymbols [(content)], function [generate(cwd = process.cwd())], generate [(cwd = process.cwd()], getIgnores [(cwd)], installHook [(cwd = process.cwd()], is [We must check if p is a directory to append the trailing slash Since chokidar's ignore], name [Dart: class Name, void name,], name [Ruby:], name [Swift:], walk [(dir)], watch [(cwd = process.cwd()]]
-- package.json
-- README.md
-- test/index.test.js | desc: Contains 5 symbols.
-  - syms: [noDocFunc [(arg1: string, arg2: number)], py_func [(x)], py_func [Note: Current regex captures '], py_func_2 [This is a python comment], testFunc [This is a test function]]
+- index.js | desc: Contains 7 symbols.
+  - syms: [SUPPORTED_EXTENSIONS [= [], extractSymbolsAndInheritance [(content)], generate [(cwd = process.cwd()], getIgnores [(cwd, additionalLines = [])], installHook [(cwd = process.cwd()], walk [(dir, ig)], watch [(cwd = process.cwd()]]
+- test/index.test.js | desc: Contains 8 symbols.
+  - syms: [AdminUser [extends BaseUser], IRepository [implements IBase], MyWidget [: StatelessWidget], ignored [by subdir/.gitignore], included [.js'), 'function included()], noDocFunc [(arg1: string, arg2: number)], realFunction [()], testFunc [This is a test function]]
+
+## GRAPH EDGES
+[AdminUser] -> [inherits] -> [BaseUser]
+[IRepository] -> [inherits] -> [IBase]
+[MyWidget] -> [inherits] -> [StatelessWidget]
+[index.js] -> [imports] -> [chokidar]
+[index.js] -> [imports] -> [dependencies]
+[index.js] -> [imports] -> [fs]
+[index.js] -> [imports] -> [ignore]
+[index.js] -> [imports] -> [new]
+[index.js] -> [imports] -> [path]
+[index.js] -> [imports] -> [url]
+[test/index.test.js] -> [imports] -> [../index.js]
+[test/index.test.js] -> [imports] -> [./local-file]
+[test/index.test.js] -> [imports] -> [assert]
+[test/index.test.js] -> [imports] -> [fs]
+[test/index.test.js] -> [imports] -> [header.h]
+[test/index.test.js] -> [imports] -> [node]
+[test/index.test.js] -> [imports] -> [other-module]
+[test/index.test.js] -> [imports] -> [path]
+[test/index.test.js] -> [imports] -> [test]
+[test/index.test.js] -> [imports] -> [url]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-llm",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Compact, language-agnostic codebase mapper for LLM token efficiency.",
   "main": "index.js",
   "bin": {

package/test/index.test.js

@@ -4,7 +4,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'url';
 import { 
-  extractSymbols, 
+  extractSymbolsAndInheritance,
+  extractEdges,
   getIgnores, 
   SUPPORTED_EXTENSIONS,
   generate
@@ -17,7 +18,7 @@ test('extractSymbols - JS/TS Docstrings', () => {
      */
     function testFunc(a, b) {}
   `;
-  const symbols = extractSymbols(code);
+  const { symbols } = extractSymbolsAndInheritance(code);
   assert.ok(symbols.some(s => s.includes('testFunc') && s.includes('This is a test function')));
 });
 
@@ -27,8 +28,8 @@ test('extractSymbols - Signature Fallback', () => {
       return true;
     }
   `;
-  const symbols = extractSymbols(code);
-  // Matches "noDocFunc [(arg1: string, arg2: number)]"
+  const { symbols } = extractSymbolsAndInheritance(code);
+  // Matches "noDocFunc [ (arg1: string, arg2: number)]"
   assert.ok(symbols.some(s => s.includes('noDocFunc') && s.includes('arg1: string, arg2: number')));
 });
 
@@ -37,11 +38,35 @@ test('extractSymbols - Flutter/Dart Noise Reduction', () => {
     const SizedBox(height: 10);
     void realFunction() {}
   `;
-  const symbols = extractSymbols(code);
+  const { symbols } = extractSymbolsAndInheritance(code);
   assert.ok(symbols.some(s => s.includes('realFunction')));
   assert.ok(!symbols.some(s => s.includes('SizedBox')));
 });
 
+test('extractInheritance - Class relationships', () => {
+  const code = `
+    class AdminUser extends BaseUser {}
+    interface IRepository implements IBase {}
+    class MyWidget : StatelessWidget {}
+  `;
+  const { inheritance } = extractSymbolsAndInheritance(code);
+  assert.ok(inheritance.some(i => i.child === 'AdminUser' && i.parent === 'BaseUser'));
+  assert.ok(inheritance.some(i => i.child === 'IRepository' && i.parent === 'IBase'));
+  assert.ok(inheritance.some(i => i.child === 'MyWidget' && i.parent === 'StatelessWidget'));
+});
+
+test('extractEdges - Imports and includes', () => {
+  const code = `
+    import { something } from './local-file';
+    const other = require('other-module');
+    #include "header.h"
+  `;
+  const edges = extractEdges(code);
+  assert.ok(edges.includes('./local-file'));
+  assert.ok(edges.includes('other-module'));
+  assert.ok(edges.includes('header.h'));
+});
+
 test('getIgnores - Default Patterns', () => {
   const ig = getIgnores(process.cwd());
   assert.strictEqual(ig.ignores('.git/'), true);