code-graph-llm 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# CODE-GRAPH
+
+A language-agnostic, ultra-compact codebase mapper designed specifically for LLM agents to optimize context and token usage.
+
+## Installation
+
+### 1. Install via NPM (Recommended)
+You can install **Code-Graph** globally or as a project-specific dependency without cloning the repository.
+
+**Global Installation:**
+```bash
+npm install -g code-graph-llm
+```
+
+**Local Project Dependency:**
+```bash
+npm install --save-dev code-graph-llm
+```
+
+### 2. Direct Usage
+Once installed, you can run it from any project directory:
+```bash
+# Generate the map
+code-graph generate
+
+# Start the live watcher
+code-graph watch
+```
+
+## Usage in Different Workflows
+
+### 1. Node.js (package.json)
+If installed as a dependency, add it to your scripts:
+```json
+"scripts": {
+  "postinstall": "code-graph generate",
+  "pretest": "code-graph generate"
+}
+```
+
+### 2. Git Integration
+Automatically update and stage `llm-code-graph.md` on every commit:
+```bash
+code-graph install-hook
+```
+
+---
+
+## LLM Usage & Token Efficiency
+
+To achieve the best performance and minimize token consumption, follow these guidelines:
+
+### 1. The "Read First" Rule
+Always instruct the LLM agent to read `llm-code-graph.md` as its first step. It provides an immediate, high-level map without scanning every directory.
+
+**Example System Prompt:**
+> "Before performing any tasks, read `llm-code-graph.md` to understand the project structure. Use this map to target specific files rather than scanning the entire codebase."
+
+### 2. Targeted File Reads
+The `|syms:[...]` metadata allows the LLM to identify exactly which file contains a specific function or class. It can jump directly to the relevant file.
+
+---
+
+## Language Examples & Build Phase Integration
+
+### 1. Rust (build.rs)
+```rust
+use std::process::Command;
+fn main() {
+    Command::new("code-graph").arg("generate").status().unwrap();
+}
+```
+
+### 2. Java/Kotlin (Maven/Gradle)
+
+#### Maven (pom.xml)
+```xml
+<plugin>
+  <groupId>org.codehaus.mojo</groupId>
+  <artifactId>exec-maven-plugin</artifactId>
+  <executions>
+    <execution>
+      <phase>compile</phase>
+      <goals><goal>exec</goal></goals>
+      <configuration>
+        <executable>code-graph</executable>
+        <arguments><argument>generate</argument></arguments>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+```
+
+#### Gradle (Groovy DSL)
+```groovy
+task generateCodeGraph(type: Exec) {
+    commandLine 'code-graph', 'generate'
+}
+compileJava.dependsOn generateCodeGraph
+```
+
+### 3. Python Integration
+Add this to your `Makefile`:
+```makefile
+map:
+	code-graph generate
+```
+
+---
+
+## How it works
+The tool scans your project directory (respecting `.gitignore`), extracts classes, functions, and exports using optimized regular expressions, and compiles them into a dense, machine-readable `llm-code-graph.md` file.
+
+## Publishing as a Package (For Developers)
+To publish this to the NPM registry:
+1. Log in: `npm login`
+2. Publish: `npm publish --access public` (Ensure the name in `package.json` is unique, e.g., `code-graph-llm`).

package/index.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chokidar from 'chokidar';
+import ignore from 'ignore';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const IGNORE_FILE = '.gitignore';
+const DEFAULT_MAP_FILE = 'llm-code-graph.md';
+
+const SYMBOL_REGEXES = [
+  /\b(?:class|interface|type|struct|enum)\s+([a-zA-Z_]\w*)/g,
+  /\b(?:function|def|fn|func|void|fun)\s+([a-zA-Z_]\w*)/g,
+  /\bconst\s+([a-zA-Z_]\w*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>/g, // Arrow functions
+  /\bexport\s+(?:const|let|var|function|class|type|interface|enum)\s+([a-zA-Z_]\w*)/g
+];
+
+function getIgnores(cwd) {
+  const ig = ignore().add(['.git', 'node_modules', DEFAULT_MAP_FILE]);
+  const ignorePath = path.join(cwd, IGNORE_FILE);
+  if (fs.existsSync(ignorePath)) {
+    ig.add(fs.readFileSync(ignorePath, 'utf8'));
+  }
+  return ig;
+}
+
+function extractSymbols(content) {
+  const symbols = new Set();
+  for (const regex of SYMBOL_REGEXES) {
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      if (match[1]) symbols.add(match[1]);
+    }
+  }
+  return Array.from(symbols).sort();
+}
+
+async function generate(cwd = process.cwd()) {
+  const ig = getIgnores(cwd);
+  const files = [];
+
+  function walk(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.relative(cwd, fullPath);
+
+      if (ig.ignores(relativePath)) continue;
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name);
+        if (['.js', '.ts', '.py', '.go', '.rs', '.java', '.cpp', '.c', '.h', '.rb', '.php', '.swift', '.kt'].includes(ext)) {
+          const content = fs.readFileSync(fullPath, 'utf8');
+          const symbols = extractSymbols(content);
+          files.push({ path: relativePath, symbols });
+        } else {
+           files.push({ path: relativePath, symbols: [] });
+        }
+      }
+    }
+  }
+
+  walk(cwd);
+
+  const output = files.map(f => {
+    const symStr = f.symbols.length > 0 ? `|syms:[${f.symbols.join(',')}]` : '';
+    return `- ${f.path}${symStr}`;
+  }).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);
+  console.log(`[Code-Graph] Updated ${DEFAULT_MAP_FILE}`);
+}
+
+function watch(cwd = process.cwd()) {
+  console.log(`[Code-Graph] Watching for changes in ${cwd}...`);
+  const ig = getIgnores(cwd);
+  
+  const watcher = chokidar.watch(cwd, {
+    ignored: (p) => {
+        const rel = path.relative(cwd, p);
+        return rel && ig.ignores(rel);
+    },
+    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()) {
+  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]');
+}

package/llm-code-graph.md

@@ -0,0 +1,8 @@
+# CODE_GRAPH_MAP
+> LLM_ONLY: DO NOT EDIT. COMPACT PROJECT MAP.
+
+- .gitignore
+- index.js|syms:[debouncedGenerate,extractSymbols,generate,getIgnores,installHook,walk,watch]
+- package-lock.json
+- package.json
+- README.md

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "code-graph-llm",
+  "version": "1.0.0",
+  "description": "Compact, language-agnostic codebase mapper for LLM token efficiency.",
+  "main": "index.js",
+  "bin": {
+    "code-graph": "./index.js"
+  },
+  "keywords": [
+    "llm",
+    "context",
+    "token-efficiency",
+    "codebase-map",
+    "ai-agent",
+    "documentation"
+  ],
+  "author": "Code-Graph Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/youruser/code-graph.git"
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "ignore": "^5.3.1"
+  },
+  "type": "module"
+}