code-graph-llm 1.1.0 → 1.3.0

package/README.md

@@ -5,6 +5,8 @@ A language-agnostic, ultra-compact codebase mapper designed specifically for LLM
 ## 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`).

package/index.js

@@ -13,46 +13,42 @@ const IGNORE_FILE = '.gitignore';
 const DEFAULT_MAP_FILE = 'llm-code-graph.md';
 
 const SYMBOL_REGEXES = [
-  // Types, Classes, Interfaces, and Containers (Universal)
+  // Types, Classes, Interfaces (Universal)
   /\b(?:class|interface|type|struct|enum|protocol|extension|trait|module|namespace|object)\s+([a-zA-Z_]\w*)/g,
   
-  // Explicit Function Keywords (JS, Python, Go, Rust, Ruby, PHP, Swift, Kotlin, Dart)
+  // Explicit Function Keywords
   /\b(?:function|def|fn|func|fun|method|procedure|sub|routine)\s+([a-zA-Z_]\w*)/g,
   
-  // C-style / Java / C# / TypeScript Method Patterns
-  // Matches: ReturnType Name(...) or AccessModifier Name(...)
-  /\b(?:void|async|public|private|protected|static|virtual|override|readonly|int|float|double|char|bool|string|val|var|let|const|final)\s+([a-zA-Z_]\w*)(?=\s*\(|(?:\s*:\s*\w+)?\s*=>)/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 (JS/TS specific but captures named exports)
-  /\bexport\s+(?:default\s+)?(?:const|let|var|function|class|type|interface|enum|async|val)\s+([a-zA-Z_]\w*)/g,
-  
-  // Ruby: def name, class Name, module Name (defs covered by Explicit Function Keywords)
-  
-  // PHP: class Name, interface Name, trait Name, function Name
-  
-  // Swift: func name, class Name, struct Name, protocol Name, extension Name
-  
-  // Dart: class Name, void name, var name (void/var covered by C-style pattern)
+  // Exported symbols
+  /\bexport\s+(?:default\s+)?(?:const|let|var|function|class|type|interface|enum|async|val)\s+([a-zA-Z_]\w*)/g
 ];
 
-const SUPPORTED_EXTENSIONS = [
-  '.js', '.ts', '.jsx', '.tsx', 
-  '.py', '.go', '.rs', '.java', 
-  '.cpp', '.c', '.h', '.hpp', '.cc',
-  '.rb', '.php', '.swift', '.kt', 
-  '.cs', '.dart', '.scala', '.m', '.mm'
+export const SUPPORTED_EXTENSIONS = [
+  '.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java', 
+  '.cpp', '.c', '.h', '.hpp', '.cc', '.rb', '.php', '.swift', 
+  '.kt', '.cs', '.dart', '.scala', '.m', '.mm'
 ];
 
-function getIgnores(cwd) {
-  const ig = ignore().add(['.git', 'node_modules', DEFAULT_MAP_FILE, 'package-lock.json']);
+export function getIgnores(cwd, additionalLines = []) {
+  const ig = ignore().add([
+    '.git/', 'node_modules/', DEFAULT_MAP_FILE, 'package-lock.json', 
+    '.idea/', 'build/', 'dist/', 'bin/', 'obj/', '.dart_tool/', '.pub-cache/', '.pub/'
+  ]);
   const ignorePath = path.join(cwd, IGNORE_FILE);
   if (fs.existsSync(ignorePath)) {
     ig.add(fs.readFileSync(ignorePath, 'utf8'));
   }
+  if (additionalLines.length > 0) {
+    ig.add(additionalLines);
+  }
   return ig;
 }
 
-function extractSymbols(content) {
+export function extractSymbols(content) {
   const symbols = [];
   for (const regex of SYMBOL_REGEXES) {
     let match;
@@ -60,9 +56,8 @@ function extractSymbols(content) {
     while ((match = regex.exec(content)) !== null) {
       if (match[1]) {
         const symbolName = match[1];
-        if (['if', 'for', 'while', 'switch', 'return', 'await', 'yield'].includes(symbolName)) continue;
+        if (['if', 'for', 'while', 'switch', 'return', 'await', 'yield', 'const', 'new'].includes(symbolName)) continue;
 
-        // 1. Extract preceding comment/docstring
         const linesBefore = content.substring(0, match.index).split('\n');
         let comment = '';
         for (let i = linesBefore.length - 1; i >= 0; i--) {
@@ -71,20 +66,16 @@ function extractSymbols(content) {
             const clean = line.replace(/[\/*#"]/g, '').trim();
             if (clean) comment = clean + (comment ? ' ' + comment : '');
             if (comment.length > 80) break; 
-          } else if (line === '' && comment === '') {
-            continue;
-          } else {
-            break;
-          }
+          } else if (line === '' && comment === '') continue;
+          else break;
         }
 
-        // 2. Backup: Extract Signature (Parameters/Type) if no comment
         let context = comment;
         if (!context) {
-          const remainingLine = content.substring(match.index + match[0].length).split('\n')[0];
-          const sigMatch = remainingLine.match(/^[^:{;]*/);
-          if (sigMatch && sigMatch[0].trim()) {
-            context = sigMatch[0].trim();
+          const remainingLine = content.substring(match.index + match[0].length);
+          const sigMatch = remainingLine.match(/^\s*(\([^)]*\)|[^\n{;]*)/);
+          if (sigMatch && sigMatch[1].trim()) {
+            context = sigMatch[1].trim();
           }
         }
         
@@ -96,27 +87,40 @@ function extractSymbols(content) {
 }
 
 async function generate(cwd = process.cwd()) {
-  const ig = getIgnores(cwd);
   const files = [];
 
-  function walk(dir) {
+  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) {
+      const content = fs.readFileSync(localIgnorePath, 'utf8');
+      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);
+      localIg = ignore().add(ig).add(lines);
+    }
+
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name);
-      let relativePath = path.relative(cwd, fullPath);
+      const relativePath = path.relative(cwd, fullPath);
       const normalizedPath = relativePath.replace(/\\/g, '/');
-      const checkPath = entry.isDirectory() ? `${normalizedPath}/` : normalizedPath;
+      const isDirectory = entry.isDirectory();
+      const checkPath = isDirectory ? `${normalizedPath}/` : normalizedPath;
 
-      if (ig.ignores(checkPath)) continue;
+      if (localIg.ignores(checkPath)) continue;
 
-      if (entry.isDirectory()) {
-        walk(fullPath);
+      if (isDirectory) {
+        walk(fullPath, localIg);
       } else if (entry.isFile()) {
         const ext = path.extname(entry.name);
         if (SUPPORTED_EXTENSIONS.includes(ext)) {
           const content = fs.readFileSync(fullPath, 'utf8');
-          
-          // Extract file-level description
           const firstLines = content.split('\n').slice(0, 5);
           let fileDesc = '';
           for (const line of firstLines) {
@@ -125,23 +129,15 @@ async function generate(cwd = process.cwd()) {
               fileDesc += trimmed.replace(/[\/*#]/g, '').trim() + ' ';
             }
           }
-
           const symbols = extractSymbols(content);
-          
-          // Backup: If no file description, provide a summary
-          if (!fileDesc.trim() && symbols.length > 0) {
-            fileDesc = `Contains ${symbols.length} symbols.`;
-          }
-
+          if (!fileDesc.trim() && symbols.length > 0) fileDesc = `Contains ${symbols.length} symbols.`;
           files.push({ path: normalizedPath, desc: fileDesc.trim(), symbols });
-        } else {
-           files.push({ path: normalizedPath, desc: '', symbols: [] });
         }
       }
     }
   }
 
-  walk(cwd);
+  walk(cwd, getIgnores(cwd));
 
   const output = files.map(f => {
     const descStr = f.desc ? ` | desc: ${f.desc.substring(0, 100)}` : '';
@@ -154,54 +150,49 @@ async function generate(cwd = process.cwd()) {
   console.log(`[Code-Graph] Updated ${DEFAULT_MAP_FILE}`);
 }
 
-function watch(cwd = process.cwd()) {
+export { generate };
+
+export function watch(cwd = process.cwd()) {
   console.log(`[Code-Graph] Watching for changes in ${cwd}...`);
-  const ig = getIgnores(cwd);
-  
+  let timeout;
+  const debouncedGenerate = () => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => generate(cwd), 500);
+  };
+
   const watcher = chokidar.watch(cwd, {
     ignored: (p) => {
-        const rel = path.relative(cwd, p);
-        return rel && ig.ignores(rel);
+        if (p === cwd) return false;
+        // Watcher ignore is harder for recursive .gitignore without complexity
+        // We rely on the generate() call to skip them during walk
+        return false; 
     },
     persistent: true,
     ignoreInitial: true
   });
 
-  let timeout;
-  const debouncedGenerate = () => {
-    clearTimeout(timeout);
-    timeout = setTimeout(() => generate(cwd), 500);
-  };
-
   watcher.on('all', (event, path) => {
-    console.log(`[Code-Graph] Change detected: ${event} on ${path}`);
     debouncedGenerate();
   });
 }
 
-function installHook(cwd = process.cwd()) {
+export function installHook(cwd = process.cwd()) {
   const hooksDir = path.join(cwd, '.git', 'hooks');
   if (!fs.existsSync(hooksDir)) {
     console.error('[Code-Graph] No .git directory found. Cannot install hook.');
     return;
   }
-
   const hookPath = path.join(hooksDir, 'pre-commit');
   const hookContent = `#!/bin/sh\n# Code-Graph pre-commit hook\nnode "${__filename}" generate\ngit add "${DEFAULT_MAP_FILE}"\n`;
-
   fs.writeFileSync(hookPath, hookContent, { mode: 0o755 });
   console.log('[Code-Graph] Installed pre-commit hook.');
 }
 
-const args = process.argv.slice(2);
-const command = args[0] || 'generate';
-
-if (command === 'generate') {
-  generate();
-} else if (command === 'watch') {
-  watch();
-} else if (command === 'install-hook') {
-  installHook();
-} else {
-  console.log('Usage: code-graph [generate|watch|install-hook]');
+if (process.argv[1] && (process.argv[1] === fileURLToPath(import.meta.url) || process.argv[1].endsWith('index.js'))) {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'generate';
+  if (command === 'generate') generate();
+  else if (command === 'watch') watch();
+  else if (command === 'install-hook') installHook();
+  else console.log('Usage: code-graph [generate|watch|install-hook]');
 }

package/llm-code-graph.md

@@ -3,6 +3,8 @@
 
 - .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,], extractSymbols [(content)], generate [(cwd = process.cwd())], getIgnores [(cwd)], installHook [(cwd = process.cwd())], name [Dart: class Name, void name,], name [Ruby:], name [Swift:], walk [(dir)], watch [(cwd = process.cwd())]]
+  - 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
+- 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]]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-llm",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Compact, language-agnostic codebase mapper for LLM token efficiency.",
   "main": "index.js",
   "bin": {
@@ -24,5 +24,8 @@
     "chokidar": "^3.6.0",
     "ignore": "^5.3.1"
   },
-  "type": "module"
+  "type": "module",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
 }

package/test/index.test.js

@@ -0,0 +1,75 @@
+import assert from 'node:assert';
+import test from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'url';
+import { 
+  extractSymbols, 
+  getIgnores, 
+  SUPPORTED_EXTENSIONS,
+  generate
+} from '../index.js';
+
+test('extractSymbols - JS/TS Docstrings', () => {
+  const code = `
+    /**
+     * This is a test function
+     */
+    function testFunc(a, b) {}
+  `;
+  const symbols = extractSymbols(code);
+  assert.ok(symbols.some(s => s.includes('testFunc') && s.includes('This is a test function')));
+});
+
+test('extractSymbols - Signature Fallback', () => {
+  const code = `
+    function noDocFunc(arg1: string, arg2: number) {
+      return true;
+    }
+  `;
+  const symbols = extractSymbols(code);
+  // Matches "noDocFunc [(arg1: string, arg2: number)]"
+  assert.ok(symbols.some(s => s.includes('noDocFunc') && s.includes('arg1: string, arg2: number')));
+});
+
+test('extractSymbols - Flutter/Dart Noise Reduction', () => {
+  const code = `
+    const SizedBox(height: 10);
+    void realFunction() {}
+  `;
+  const symbols = extractSymbols(code);
+  assert.ok(symbols.some(s => s.includes('realFunction')));
+  assert.ok(!symbols.some(s => s.includes('SizedBox')));
+});
+
+test('getIgnores - Default Patterns', () => {
+  const ig = getIgnores(process.cwd());
+  assert.strictEqual(ig.ignores('.git/'), true);
+  assert.strictEqual(ig.ignores('node_modules/'), true);
+  assert.strictEqual(ig.ignores('.idea/'), true);
+  assert.strictEqual(ig.ignores('.dart_tool/'), true);
+});
+
+test('Recursive Ignore Simulation (Logic Check)', async () => {
+  const tempDir = path.join(process.cwd(), 'temp_test_dir');
+  if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true });
+  fs.mkdirSync(tempDir);
+  
+  const subDir = path.join(tempDir, 'subdir');
+  fs.mkdirSync(subDir);
+  
+  // Create a file that should be ignored by subdir/.gitignore
+  fs.writeFileSync(path.join(subDir, 'ignored.js'), 'function ignored() {}');
+  fs.writeFileSync(path.join(subDir, 'included.js'), 'function included() {}');
+  fs.writeFileSync(path.join(subDir, '.gitignore'), 'ignored.js');
+  
+  await generate(tempDir);
+  
+  const mapPath = path.join(tempDir, 'llm-code-graph.md');
+  const mapContent = fs.readFileSync(mapPath, 'utf8');
+  
+  assert.ok(mapContent.includes('included.js'));
+  assert.ok(!mapContent.includes('ignored.js'));
+  
+  fs.rmSync(tempDir, { recursive: true });
+});