repo-knowledge-graph 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nithin Naubad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# repo-knowledge-graph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/repo-knowledge-graph?label=npm)](https://www.npmjs.com/package/repo-knowledge-graph)
+[![npm alpha](https://img.shields.io/npm/v/repo-knowledge-graph/alpha?label=alpha)](https://www.npmjs.com/package/repo-knowledge-graph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Turn a source-code repository into a searchable knowledge graph — directly from your terminal.**
+
+A lightweight Node.js CLI and library for indexing repository files and code symbols, finding relevant code, assembling focused context, and estimating potential token savings. No hosted service or LLM key required for the core workflow.
+
+> **Alpha:** APIs, graph format, and commands may change. Token savings are estimates, not measured API billing reductions.
+
+## Quick start
+
+**Requirements:** Node.js 20+.
+
+From the root of the repository you want to analyze:
+
+```bash
+npm install --save-dev repo-knowledge-graph@alpha
+npx repo-graph --help
+npx repo-graph index
+```
+
+The CLI stores its generated graph in `.repo-graph/graph.json` in the current working directory. To try unreleased v0.6.0 source before npm publication, clone this repository and run `npm link` locally.
+
+## CLI showcase
+
+| Command | What it does |
+| --- | --- |
+| `npx repo-graph --help` | Show available commands |
+| `npx repo-graph index` | Scan the current repository and build/update the graph |
+| `npx repo-graph stats` | Display counts of indexed files, nodes, and edges |
+| `npx repo-graph search "embedding"` | Find repository files relevant to a query |
+| `npx repo-graph context "embedding"` | Retrieve focused context for a query |
+| `npx repo-graph savings "embedding"` | Estimate token savings for a query |
+| `npx repo-graph index` | Run again to reuse unchanged file metadata |
+
+**Try the complete workflow:**
+
+```bash
+# 1. Generate or refresh the knowledge graph
+npx repo-graph index
+
+# 2. Inspect the graph
+npx repo-graph stats
+
+# 3. Search for a concept in your code
+npx repo-graph search "authentication"
+
+# 4. Collect context for that concept
+npx repo-graph context "authentication"
+
+# 5. Inspect approximate token savings
+npx repo-graph savings "authentication"
+
+# 6. Re-index after making changes
+npx repo-graph index
+```
+
+**Important:** `search`, `context`, and `savings` each require a query. Run `index` before using them. Commands operate on the **current working directory**, so run them from the project you want to analyze.
+
+### Example: indexing a real repository
+
+The following is an **example from an initial run** on a separate development repository, not a performance benchmark or guaranteed result:
+
+```text
+$ npx repo-graph index
+{
+  "file": "/path/to/llm_engineering/.repo-graph/graph.json",
+  "files": 2173,
+  "nodes": 11192,
+  "edges": 9025,
+  "reusedFiles": 0
+}
+```
+
+`reusedFiles: 0` is expected on a first scan. Re-running `index` can reuse unchanged file metadata; files are still read and hashed for change detection.
+
+### Understanding the commands
+
+- **Index:** Collects repository file and symbol information and creates graph relationships.
+- **Stats:** Reports graph size; it does not measure graph quality.
+- **Search:** Finds relevant files using the package's current non-LLM search implementation.
+- **Context:** Builds a focused context response around the supplied query.
+- **Savings:** Reports *estimated* token savings associated with focused context. This is not a measured reduction in actual model usage or cost.
+
+## Using it in CI or scripts
+
+Install it as a project dependency and invoke the binary from the repository root:
+
+```bash
+npm install --save-dev repo-knowledge-graph@alpha
+npx repo-graph index
+npx repo-graph stats
+```
+
+To run it without adding a dependency:
+
+```bash
+npm exec --yes --package=repo-knowledge-graph@alpha -- repo-graph index
+```
+
+The **npm package name** is `repo-knowledge-graph`; the **CLI executable** is `repo-graph`. `alpha` is a release tag, not part of the package name.
+
+## Local MCP integration (v0.6.0 alpha source)
+
+After indexing the project, launch the stdio MCP server:
+
+```bash
+npx repo-graph index
+npx repo-graph serve --mcp
+```
+
+Register the command with an MCP-compatible coding assistant, setting its working directory to the repository root. The server uses newline-delimited JSON-RPC over stdio; it does **not** print a startup banner to stdout. Tools: `repo_search`, `repo_context` (with `maxTokens`), `repo_stats`, and `repo_refresh`. The server automatically checks for repository changes before each tool call and refreshes the saved graph when files change. `repo_refresh` also forces a refresh. Automatic freshness currently re-reads and hashes eligible files, so very large repositories may see added latency.
+
+Example generic MCP client configuration (adapt to your assistant's configuration format):
+
+```json
+{
+  "mcpServers": {
+    "repo-knowledge-graph": {
+      "command": "npx",
+      "args": ["repo-graph", "serve", "--mcp"]
+    }
+  }
+}
+```
+
+`repo_context` returns line-numbered snippets with a configurable approximate token budget. Snippet extraction is keyword-oriented and may omit relevant code. The server uses the working directory as the repository root; configure your MCP client accordingly.
+
+**Note:** The assistant must actually invoke these tools for them to influence context usage. This is not an automatic prompt interceptor. The `savings` command compares against an all-files baseline and does **not** establish actual model-token savings.
+
+## Retrieval benchmark
+
+Create a `repo-graph-benchmark.json` file containing labeled questions and relevant file paths:
+
+```json
+[
+  {"query": "Where is authentication implemented?", "relevantPaths": ["src/auth.js"]}
+]
+```
+
+Replace `src/auth.js` with an actual indexed path. Then run:
+
+```bash
+npx repo-graph benchmark repo-graph-benchmark.json
+```
+
+This measures retrieval precision, recall, selected-context token estimates and latency. The benchmark requires ground-truth file labels; it does **not** measure live model billing or guarantee reduced tokens in an assistant.
+
+## Advanced / experimental integrations
+
+- **Incremental indexing:** Reuses metadata for unchanged files on subsequent scans.
+- **Optional TypeScript AST extraction:** Install the optional `typescript` peer dependency and set `REPO_GRAPH_PARSER=typescript` when indexing.
+- **Graphify-compatible adapter:** `toGraphify(graph, { createGraph })` expects a graph object with `addNode` and `addEdge`. Compatibility with a particular Graphify release has not been verified.
+- **Decision-model integration:** A Laya-compatible local adapter is included as an experimental extension point; no model is bundled.
+
+## Safety and limitations
+
+Review [SECURITY.md](SECURITY.md) before scanning sensitive repositories. Keep `.repo-graph/` out of version control if the generated graph may contain internal repository details:
+
+```gitignore
+.repo-graph/
+```
+
+The scanner supports common `.gitignore` glob patterns and negations, but it is not a complete implementation of Git's nested ignore semantics. Source files are never executed by the scanner. Generated context includes source snippets and may expose sensitive code to the connected AI assistant; review its privacy policy before use.
+
+The CLI runs locally, but graph outputs may reflect private code structure. The current release is an alpha and should be evaluated on representative repositories before production adoption.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,8 @@
+# Security review (alpha)
+
+The scanner does not execute source or persist source content. It excludes common secret filenames and recognizable credential patterns; this is not comprehensive secret detection. Context reads reject symlinks and path escapes. External embedding/model adapters may transmit source. Known limitations include partial gitignore support, TOCTOU race, incomplete secret detection, and no independent penetration test. Never commit `.repo-graph/`.
+
+
+## MCP security boundaries
+
+The MCP server is local and uses stdio, not a network listener. It reads repository files to answer queries and refreshes the on-disk index when files change. Context responses include source snippets; connecting an AI assistant may cause those snippets to be sent to the assistant's model provider. Restrict the working directory to the intended repository, and avoid indexing sensitive source. The server does not execute repository code. Gitignore parsing covers common patterns but is not fully equivalent to Git's nested ignore behavior. Changes between scan and context read are rejected by a content-hash check; this is not a substitute for OS-level access controls.

package/bin/repo-graph.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import {scan,save,load,searchFiles,context} from '../src/index.js';
+import {startMcp} from '../src/mcp.js';
+import {benchmark} from '../src/benchmark.js';
+import {readFile} from 'node:fs/promises';
+const [cmd,...args]=process.argv.slice(2),root=process.cwd();
+try{if(cmd==='serve'&&args.includes('--mcp')){startMcp(root);}else if(cmd==='benchmark'){const cases=JSON.parse(await readFile(args[0]||'repo-graph-benchmark.json','utf8'));const g=await load(root);const r=await benchmark(g,cases,{retrieve:(graph,query,{limit})=>context(graph,query,{limit})});console.log(JSON.stringify(r,null,2));}else if(cmd==='index'){let previous;try{previous=await load(root);}catch{}const g=await scan(root,{previous,parser:process.env.REPO_GRAPH_PARSER||'regex'});console.log(JSON.stringify({file:await save(g),files:g.files.length,nodes:g.nodes.length,edges:g.edges.length,reusedFiles:g.reusedFiles},null,2));}else if(['stats','search','context','savings'].includes(cmd)){const g=await load(root),query=args.join(' ');if(cmd==='stats')console.log(JSON.stringify({files:g.files.length,nodes:g.nodes.length,edges:g.edges.length}));else{if(!query)throw Error('Query required');const r=cmd==='search'?await searchFiles(g,query):await context(g,query);console.log(JSON.stringify(cmd==='savings'?{estimatedTokensSaved:r.estimatedTokensSaved,estimatedSavingsPercent:r.estimatedSavingsPercent,method:r.method}:r,null,2));}}else{console.log('Usage: repo-graph <index|stats|search|context|savings|benchmark [cases.json]|serve --mcp> [query]');if(cmd)process.exitCode=1;}}catch(e){console.error(e.message);process.exitCode=1;}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "repo-knowledge-graph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "type": "module",
+  "description": "Repository knowledge graph and CLI",
+  "bin": {
+    "repo-graph": "bin/repo-graph.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./adapters": "./src/adapters.js",
+    "./mcp": "./src/mcp.js",
+    "./benchmark": "./src/benchmark.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js && node --check src/adapters.js && node --check bin/repo-graph.js && node --check src/mcp.js",
+    "prepublishOnly": "npm test && npm run check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naubadnithin7/repo-knowledge-graph.git"
+  }
+}

package/src/adapters.js

@@ -0,0 +1,5 @@
+export async function extractTypeScript(source,filename='source.ts'){let ts;try{ts=await import('typescript');}catch{throw Error('Install typescript to use AST parsing');}const ast=ts.createSourceFile(filename,source,ts.ScriptTarget.Latest,true),symbols=[],imports=[];function visit(n){if(ts.isImportDeclaration(n)&&ts.isStringLiteral(n.moduleSpecifier))imports.push(n.moduleSpecifier.text);if((ts.isFunctionDeclaration(n)||ts.isClassDeclaration(n)||ts.isInterfaceDeclaration(n)||ts.isTypeAliasDeclaration(n))&&n.name)symbols.push({name:n.name.text,line:ast.getLineAndCharacterOfPosition(n.getStart(ast)).line+1});ts.forEachChild(n,visit);}visit(ast);return {symbols,imports};}
+export function createDecisionAdapter({endpoint,model='laya',fetchImpl=fetch,allowedHosts=['localhost','127.0.0.1','::1']}={}){const url=new URL(endpoint);if(!['http:','https:'].includes(url.protocol)||!allowedHosts.includes(url.hostname))throw Error('Endpoint not allowlisted');return async input=>{const controller=new AbortController(),timer=setTimeout(()=>controller.abort(),10000);try{const response=await fetchImpl(url,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({model,messages:[{role:'system',content:'Return JSON {"kind":"model"|"agent","name":"target"}'},{role:'user',content:String(input).slice(0,4000)}],temperature:0}),signal:controller.signal});if(!response.ok)throw Error('Decision HTTP '+response.status);const content=(await response.json())?.choices?.[0]?.message?.content;if(typeof content!=='string'||content.length>2000)throw Error('Invalid decision');const d=JSON.parse(content);if(!['model','agent'].includes(d.kind)||typeof d.name!=='string'||!/^[-\w.]{1,80}$/.test(d.name))throw Error('Invalid route');return d;}finally{clearTimeout(timer);}};}
+export function toGraphify(graph,{createGraph,graphInstance}={}){const target=graphInstance??createGraph?.();if(!target||typeof target.addNode!=='function'||typeof target.addEdge!=='function')throw Error('Graphify adapter requires addNode/addEdge');for(const n of graph.nodes)target.addNode(n.id,{...n});for(const e of graph.edges)target.addEdge(e.from,e.to,{type:e.type});return target;}
+export function toGraphData(graph){return {nodes:graph.nodes.map(({id,...attributes})=>({id,attributes})),edges:graph.edges.map(({from,to,...attributes})=>({source:from,target:to,attributes}))};}
+export async function transformGraph(graph,{transform}={}){if(typeof transform!=='function')throw Error('Provide transform function');return transform(graph);}

package/src/benchmark.js

@@ -0,0 +1,14 @@
+import {performance} from 'node:perf_hooks';
+/** Retrieval quality benchmark with optional model tokenizer. */
+export async function benchmark(graph,cases,{retrieve,tokenizer,limit=5}={}){
+ if(!Array.isArray(cases)||!cases.length||typeof retrieve!=='function')throw Error('Provide cases and retrieve function');
+ const count=tokenizer||((s)=>Math.ceil(String(s).length/4)),results=[];
+ for(const entry of cases){if(typeof entry.query!=='string'||!Array.isArray(entry.relevantPaths))throw Error('Invalid benchmark case');
+ const start=performance.now(),r=await retrieve(graph,entry.query,{limit}),latencyMs=performance.now()-start;
+ const selected=Array.isArray(r)?r:r?.selected;if(!Array.isArray(selected))throw Error('Invalid retrieval result');
+ const relevant=new Set(entry.relevantPaths),hits=selected.filter(f=>relevant.has(f.path)).length;
+ results.push({query:entry.query,precisionAtK:selected.length?hits/selected.length:0,recallAtK:relevant.size?hits/relevant.size:1,selectedTokens:selected.reduce((n,f)=>n+count(f.content||''),0),latencyMs,selectedPaths:selected.map(f=>f.path)});
+ }
+ const mean=k=>results.reduce((n,r)=>n+r[k],0)/results.length;
+ return {cases:results.length,meanPrecisionAtK:mean('precisionAtK'),meanRecallAtK:mean('recallAtK'),meanSelectedTokens:mean('selectedTokens'),meanLatencyMs:mean('latencyMs'),tokenCounting:tokenizer?'supplied tokenizer':'characters/4 estimate',results};
+}

package/src/index.js

@@ -0,0 +1,66 @@
+import {readdir,readFile,mkdir,writeFile,lstat,realpath} from 'node:fs/promises';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {extractTypeScript} from './adapters.js';
+const skip=new Set(['.git','node_modules','dist','build','.repo-graph','coverage','.venv','.venv312','.tox','.mypy_cache','.pytest_cache','__pycache__','.next','vendor']);
+const ext=new Set(['.js','.jsx','.ts','.tsx','.mjs','.cjs','.py','.go','.java','.rs','.md','.json']);
+const sensitive=/(^|\/)(\.env(?:\..*)?|id_rsa|id_ed25519|[^/]*\.(?:pem|key|p12)|credentials(?:\..*)?|secrets?(?:\..*)?)$/i;
+const norm=p=>p.split(path.sep).join('/');
+const secretPattern=/(?:-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|(?:ghp_|github_pat_|sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}))/;
+export const estimateTokens=s=>Math.ceil(String(s).length/4);
+async function patterns(root){try{return (await readFile(path.join(root,'.gitignore'),'utf8')).split(/\r?\n/).map(p=>p.trim()).filter(p=>p&&!p.startsWith('#'));}catch{return [];}}
+function globRegex(glob){let out='';for(let i=0;i<glob.length;i++){const c=glob[i];if(c==='*'){if(glob[i+1]==='*'){i++;if(glob[i+1]==='/'){i++;out+='(?:.*/)?';}else out+='.*';}else out+='[^/]*';}else if(c==='?')out+='[^/]';else out+=('.+^$()[]{}|\\'.includes(c)?'\\':'')+c;}return out;}
+function ignored(rel,ps){let matched=false;for(let p of ps){const negate=p.startsWith('!');if(negate)p=p.slice(1);const anchored=p.startsWith('/');if(anchored)p=p.slice(1);const directory=p.endsWith('/');if(directory)p=p.slice(0,-1);const pattern=globRegex(p);const prefix=anchored||p.includes('/')?'^':'^(?:.*/)?';const regex=new RegExp(prefix+pattern+'(?:/.*)?'+String.fromCharCode(36));if(regex.test(rel))matched=!negate;}return matched;}
+function resolve(spec,rel,known){if(!spec.startsWith('.'))return 'module:'+spec;const base=norm(path.posix.normalize(path.posix.join(path.posix.dirname(rel),spec)));return 'file:'+([base,base+'.js',base+'.ts',base+'.tsx',base+'.jsx',base+'/index.js',base+'/index.ts'].find(p=>known.has(p))||'__missing__')==='file:__missing__'?'module:'+spec:'file:'+([base,base+'.js',base+'.ts',base+'.tsx',base+'.jsx',base+'/index.js',base+'/index.ts'].find(p=>known.has(p)));}
+export async function scan(root,{maxBytes=256000,previous=null,parser='regex'}={}){
+ if(!['regex','typescript'].includes(parser))throw Error('Unknown parser');
+ root=path.resolve(root);const ps=await patterns(root),files=[],nodes=[],edges=[],contents=new Map(),prior=new Map((previous?.files||[]).map(f=>[f.path,f]));let reusedFiles=0;
+ async function walk(dir){for(const ent of await readdir(dir,{withFileTypes:true})){if(ent.isSymbolicLink()||skip.has(ent.name)||ent.name.startsWith('.venv'))continue;const full=path.join(dir,ent.name),rel=norm(path.relative(root,full));if(ignored(rel,ps)||sensitive.test(rel))continue;if(ent.isDirectory()){await walk(full);continue;}if(!ent.isFile()||!ext.has(path.extname(ent.name)))continue;let content;try{content=await readFile(full,'utf8');}catch{continue;}const bytes=Buffer.byteLength(content);if(bytes>maxBytes||content.includes('\0')||secretPattern.test(content))continue;const hash=createHash('sha256').update(content).digest('hex');if(prior.get(rel)?.hash===hash)reusedFiles++;files.push({path:rel,hash,bytes});contents.set(rel,content);}}
+ await walk(root);files.sort((a,b)=>a.path.localeCompare(b.path));const known=new Set(files.map(f=>f.path));
+ for(const f of files){const content=contents.get(f.path),id='file:'+f.path;nodes.push({id,type:'file',name:f.path,hash:f.hash});let symbols=[],imports=[];const old=prior.get(f.path);
+ if(old?.hash===f.hash&&previous?.parser===parser&&Array.isArray(old.symbols)&&Array.isArray(old.imports)){symbols=old.symbols;imports=old.imports;}
+ else if(parser==='typescript'&&/\.[cm]?[jt]sx?$/.test(f.path)){const ast=await extractTypeScript(content,f.path);symbols=ast.symbols;imports=ast.imports;}
+ else{symbols=[...content.matchAll(/\b(?:export\s+)?(?:async\s+)?(?:function|class|interface|type|def)\s+([A-Za-z_$][\w$]*)/g)].map(m=>({name:m[1]}));imports=[...content.matchAll(/(?:import\s+(?:[^'"]+?\s+from\s+)?|require\s*\(|from\s+)['"]([^'"]+)['"]/g)].map(m=>m[1]);}
+ f.symbols=symbols;f.imports=imports;
+ for(const s of symbols){const sid='symbol:'+f.path+':'+s.name;nodes.push({id:sid,type:'symbol',name:s.name,file:f.path,...(s.line?{line:s.line}:{})});edges.push({from:id,to:sid,type:'contains'});}
+ for(const spec of imports)edges.push({from:id,to:resolve(spec,f.path,known),type:'imports'});
+ }
+ for(const e of edges.filter(e=>e.to.startsWith('module:')))if(!nodes.some(n=>n.id===e.to))nodes.push({id:e.to,type:'module',name:e.to.slice(7)});
+ return {schemaVersion:4,root,generatedAt:new Date().toISOString(),nodes,edges,files,reusedFiles,parser};
+}
+export async function readContextFile(graph,rel){const root=path.resolve(graph.root),file=path.resolve(root,rel);if(!file.startsWith(root+path.sep)||!graph.files.some(f=>f.path===rel))throw Error('Unsafe or unindexed file');const info=await lstat(file);if(!info.isFile()||info.isSymbolicLink())throw Error('Unsafe file type');const actual=await realpath(file),realRoot=await realpath(root);if(!actual.startsWith(realRoot+path.sep))throw Error('File escaped repository');const content=await readFile(actual,'utf8');if(secretPattern.test(content))throw Error('Potential secret detected');const expected=graph.files.find(f=>f.path===rel)?.hash;if(expected!==createHash('sha256').update(content).digest('hex'))throw Error('Index stale: refresh required');return content;}
+export async function searchFiles(graph,query,{limit=10}={}){const terms=String(query).toLowerCase().split(/\s+/).filter(Boolean);if(!terms.length)return [];const found=[];for(const f of graph.files){const body=(await readContextFile(graph,f.path)).toLowerCase(),name=f.path.toLowerCase(),symbols=(f.symbols||[]).map(s=>s.name.toLowerCase()),score=terms.reduce((n,t)=>n+(name.includes(t)?5:0)+(symbols.some(s=>s.includes(t))?8:0)+(body.includes(t)?1:0),0);if(score)found.push({path:f.path,score});}return found.sort((a,b)=>b.score-a.score||a.path.localeCompare(b.path)).slice(0,limit);}
+export async function context(graph,query,{limit=5,maxTokens=4000}={}){
+ let used=0;const selected=[];
+ const baseline=graph.files.reduce((sum,f)=>sum+Math.ceil(f.bytes/4),0);
+ const terms=String(query).toLowerCase().split(/\s+/).filter(Boolean);
+ for(const f of await searchFiles(graph,query,{limit:graph.files.length})){
+  if(selected.length>=limit||used>=maxTokens)break;
+  const lines=(await readContextFile(graph,f.path)).split(/\r?\n/);
+  const hits=[];for(let i=0;i<lines.length;i++)if(terms.some(t=>lines[i].toLowerCase().includes(t)))hits.push(i);
+  if(!hits.length)hits.push(0);
+  const windows=[];
+  for(const i of hits.slice(0,12)){
+   const a=Math.max(0,i-2),b=Math.min(lines.length,i+3);
+   if(windows.length&&a<=windows[windows.length-1][1])windows[windows.length-1][1]=Math.max(b,windows[windows.length-1][1]);
+   else windows.push([a,b]);
+  }
+  const snippets=[];
+  for(const [a,b] of windows){
+   let content=lines.slice(a,b).map((line,j)=>(a+j+1)+': '+line).join('\n');
+   const available=maxTokens-used;
+   if(available<=0)break;
+   if(estimateTokens(content)>available)content=content.slice(0,available*4);
+   if(!content)continue;
+   const cost=estimateTokens(content);
+   snippets.push({startLine:a+1,endLine:b,content,estimatedTokens:cost});
+   used+=cost;
+  }
+  if(snippets.length)selected.push({path:f.path,snippets,content:snippets.map(s=>s.content).join('\n'),estimatedTokens:snippets.reduce((n,s)=>n+s.estimatedTokens,0)});
+ }
+ return {query,selected,estimatedContextTokens:used,estimatedBaselineTokens:baseline,estimatedTokensSaved:Math.max(0,baseline-used),estimatedSavingsPercent:baseline?Math.round(100*(baseline-used)/baseline):0,method:'characters/4 estimate; full repository theoretical baseline, not actual LLM savings'};
+}
+export async function save(graph,root=graph.root){const dir=path.join(root,'.repo-graph');await mkdir(dir,{recursive:true});const target=path.join(dir,'graph.json');await writeFile(target,JSON.stringify(graph,null,2));return target;}
+export async function load(root){const g=JSON.parse(await readFile(path.join(path.resolve(root),'.repo-graph','graph.json'),'utf8'));if(g.schemaVersion!==4)throw Error('Re-index required');return g;}
+export async function semanticSearch(graph,query,{embed,limit=5}={}){if(typeof embed!=='function')throw Error('Provide embed(text)');const q=await embed(query),norm=v=>Math.sqrt(v.reduce((n,x)=>n+x*x,0)),qn=norm(q),rows=[];for(const f of graph.files){const v=await embed(await readContextFile(graph,f.path));if(v.length!==q.length)throw Error('Embedding dimension mismatch');const vn=norm(v);rows.push({path:f.path,score:qn&&vn?v.reduce((n,x,i)=>n+x*q[i],0)/(qn*vn):0});}return rows.sort((a,b)=>b.score-a.score).slice(0,limit);}
+export async function routeTask(input,{decide,models={},agents={},fallback='default'}={}){if(typeof decide!=='function')throw Error('Provide decide(input)');const decision=await decide(input),kind=decision?.kind==='agent'?'agent':'model',name=decision?.name||fallback,registry=kind==='agent'?agents:models;if(!Object.hasOwn(registry,name))throw Error('Unregistered '+kind+': '+name);return {kind,name,decision,execute:(...args)=>registry[name](input,...args)};}

package/src/mcp.js

@@ -0,0 +1,42 @@
+import {stdin,stdout,stderr} from 'node:process';
+import {scan,save,load,searchFiles,context} from './index.js';
+
+const definitions=[
+ {name:'repo_search',description:'Find relevant repository files',inputSchema:{type:'object',properties:{query:{type:'string'},limit:{type:'integer',minimum:1,maximum:30}},required:['query']}},
+ {name:'repo_context',description:'Retrieve focused repository context within a token budget',inputSchema:{type:'object',properties:{query:{type:'string'},limit:{type:'integer',minimum:1,maximum:20},maxTokens:{type:'integer',minimum:1,maximum:16000}},required:['query']}},
+ {name:'repo_stats',description:'Show indexed repository graph statistics',inputSchema:{type:'object',properties:{}}},
+ {name:'repo_refresh',description:'Refresh the repository knowledge graph',inputSchema:{type:'object',properties:{}}}
+];
+const result=(value)=>({content:[{type:'text',text:JSON.stringify(value)}]});
+export async function callTool(root,name,args={}){
+ if(name==='repo_refresh'){let previous;try{previous=await load(root);}catch{}const g=await scan(root,{previous,parser:previous?.parser||'regex'});await save(g);return result({files:g.files.length,nodes:g.nodes.length,edges:g.edges.length,reusedFiles:g.reusedFiles});}
+ let previous;try{previous=await load(root);}catch{}
+ const g=await scan(root,{previous,parser:previous?.parser||'regex'});
+ if(!previous||g.files.length!==previous.files.length||g.files.some((f,i)=>f.path!==previous.files[i]?.path||f.hash!==previous.files[i]?.hash))await save(g);
+ if(name==='repo_stats')return result({files:g.files.length,nodes:g.nodes.length,edges:g.edges.length});
+ if(name==='repo_search')return result(await searchFiles(g,requireQuery(args),{limit:integer(args.limit,10,30)}));
+ if(name==='repo_context')return result(await context(g,requireQuery(args),{limit:integer(args.limit,5,20),maxTokens:integer(args.maxTokens,4000,16000)}));
+ throw Error('Unknown tool: '+name);
+}
+function integer(value,fallback,max){if(value===undefined)return fallback;if(!Number.isInteger(value)||value<1||value>max)throw Error('Invalid integer argument');return value;}
+function requireQuery(args){if(typeof args.query!=='string'||!args.query.trim()||args.query.length>1000)throw Error('Nonempty query required (max 1000 characters)');return args.query;}
+export function startMcp(root=process.cwd(),{input=stdin,output=stdout}={}){
+ let buffer='',queue=Promise.resolve();
+ const send=msg=>output.write(JSON.stringify(msg)+'\n');
+ const handle=async msg=>{
+  if(!msg||msg.jsonrpc!=='2.0'||typeof msg.method!=='string')return;
+  if(msg.id===undefined)return;
+  try{
+   let value;
+   if(msg.method==='initialize')value={protocolVersion:'2024-11-05',capabilities:{tools:{}},serverInfo:{name:'repo-knowledge-graph',version:'0.6.0'}};
+   else if(msg.method==='ping')value={};
+   else if(msg.method==='tools/list')value={tools:definitions};
+   else if(msg.method==='tools/call')value=await callTool(root,msg.params?.name,msg.params?.arguments??{});
+   else {send({jsonrpc:'2.0',id:msg.id,error:{code:-32601,message:'Method not found'}});return;}
+   send({jsonrpc:'2.0',id:msg.id,result:value});
+  }catch(e){send({jsonrpc:'2.0',id:msg.id,error:{code:-32603,message:e.message}});}
+ };
+ input.setEncoding('utf8');
+ input.on('data',chunk=>{buffer+=chunk;if(buffer.length>1048576){buffer='';stderr.write('MCP message too large\n');return;}let pos;while((pos=buffer.indexOf('\n'))>=0){const line=buffer.slice(0,pos).trim();buffer=buffer.slice(pos+1);if(!line)continue;queue=queue.then(()=>handle(JSON.parse(line))).catch(e=>stderr.write('MCP invalid message: '+e.message+'\n'));}});
+ return {close:()=>input.removeAllListeners('data')};
+}