repo-knowledge-graph 0.0.0-stage → 0.5.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,13 @@
-# 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.
+Early alpha CLI and npm library. Node.js 20+. **Not published to npm.**
+
+```sh
+npm install github:naubadnithin7/repo-knowledge-graph
+repo-graph index
+repo-graph search authentication
+repo-graph context authentication
+repo-graph savings authentication
+```
+
+Incremental symbol parsing reuses unchanged file metadata; files are still read and hashed. Optional TypeScript AST extraction requires `typescript` and `REPO_GRAPH_PARSER=typescript`. Graphify-compatible `toGraphify(graph,{createGraph})` requires a graph object exposing `addNode`/`addEdge`; integration with a specific Graphify release is not verified. Laya-compatible local decision adapter is available but no model is bundled. Token savings are estimates, not billing measurements. See SECURITY.md.

package/SECURITY.md

@@ -0,0 +1,3 @@
+# 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/`.

package/bin/repo-graph.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import {scan,save,load,searchFiles,context} from '../src/index.js';
+const [cmd,...args]=process.argv.slice(2),root=process.cwd();
+try{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> [query]');if(cmd)process.exitCode=1;}}catch(e){console.error(e.message);process.exitCode=1;}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "repo-knowledge-graph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "type": "module",
+  "description": "Repository knowledge graph and CLI",
+  "bin": {
+    "repo-graph": "bin/repo-graph.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./adapters": "./src/adapters.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js && node --check src/adapters.js && node --check bin/repo-graph.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,36 @@
+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','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/).filter(x=>x&&!x.startsWith('#'));}catch{return [];}}
+function ignored(rel,ps){return ps.some(p=>{p=p.replace(/^\//,'');if(p.endsWith('/'))return rel.startsWith(p)||rel.includes('/'+p);return rel===p||rel.endsWith('/'+p)||(p.startsWith('*.')&&rel.endsWith(p.slice(1)));});}
+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))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');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(),score=terms.reduce((n,t)=>n+(name.includes(t)?5: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,baseline=0;const selected=[];for(const f of graph.files)baseline+=estimateTokens(await readContextFile(graph,f.path));for(const f of await searchFiles(graph,query,{limit:graph.files.length})){if(selected.length>=limit)break;const content=await readContextFile(graph,f.path),cost=estimateTokens(content);if(used+cost>maxTokens)continue;selected.push({path:f.path,content,estimatedTokens:cost});used+=cost;}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 heuristic'};}
+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)};}