project-graph-mcp 2.3.2 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-graph-mcp",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "type": "module",
   "description": "MCP server for AI agents — project graph, code quality analysis, visual web explorer. JS, TS, Python, Go.",
   "main": "src/network/server.js",
@@ -12,7 +12,8 @@
   },
   "scripts": {
     "start": "node src/network/server.js",
-    "test": "node --test tests/*.test.js"
+    "test": "node --test tests/*.test.js",
+    "test:consumer": "node scripts/consumer-test.mjs"
   },
   "keywords": [
     "mcp",

package/src/analysis/analysis-cache.ctx

@@ -0,0 +1,9 @@
+--- src/analysis/analysis-cache.js ---
+@sig 3e2247a9
+export computeContentHash(content:string)→i|compute full source code hash|for body-dependent metrics
+export getCachePath(rootDir:string,key:string)→e.replace,c|get cache file path for source file|.context/.cache/path.json
+export readCache(rootDir:string,key:string)→getCachePath,r,t,JSON.parse|read cached analysis file|returns CacheEntry or null
+export writeCache(rootDir:string,key:string,data:Object)→getCachePath,a,n,JSON.stringify,e|write analysis cache entry|includes timestamp
+export isCacheValid(rootDir:string,key:string,sourceFile:string,maxAge:number=)|check if cache is valid|supports interface or content hash level
+PATTERNS: dual-hashing (sig vs content)|persistent file-based cache
+EDGE_CASES: ignores read/write cache errors|handles missing directories

package/src/analysis/analysis-cache.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/analysis-cache.ctx
+// @ctx analysis-cache.ctx
 import{readFileSync as t,writeFileSync as e,mkdirSync as n,existsSync as r}from"fs";
 import{join as c,dirname as a}from"path";
 import{createHash as i}from"crypto";

package/src/analysis/complexity.ctx

@@ -0,0 +1,6 @@
+--- src/analysis/complexity.js ---
+@sig 9df5918d
+export analyzeComplexityFile(filePath:string,code:string)→a,u,h,o.push,l.simple|analyze complexity for all functions in a single file
+export getComplexity(path:string,options:Object=)→i,p,f,l.push,l.filter,l.sort|scan directory, filter and sort complexity results
+PATTERNS: AST tree walking via Acorn|cyclomatic complexity counting
+EDGE_CASES: parses arrow functions with blocks|ignores unparseable files

package/src/analysis/complexity.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/complexity.ctx
+// @ctx complexity.ctx
 import{readFileSync as t,readdirSync as e,statSync as o}from"fs";import{join as n,relative as r,resolve as i}from"path";import{parse as a}from"../../vendor/acorn.mjs";
 import*as l from"../../vendor/walk.mjs";
 import{shouldExcludeDir as s,shouldExcludeFile as c,parseGitignore as m}from"../core/filters.js";

package/src/analysis/custom-rules.ctx

@@ -0,0 +1,14 @@
+--- src/analysis/custom-rules.js ---
+@sig 683d58c0
+b(t,s,n)→s.replace,e.endsWith,e,c,e.exec,j|(internal utility)
+export getCustomRules()→x,Object.entries,rules.map|load and return summary of all custom rules
+export setCustomRule(ruleSet:string,rule:Object)→x,rules.findIndex,rules.push,v|add or update a single rule in a ruleset
+export deleteCustomRule(ruleSet:string,ruleId:string)→x,rules.findIndex,rules.splice,v|remove a rule from a ruleset by ID
+export detectProjectRuleSets(path:string)→x,o,n,e,JSON.parse,Object.keys|auto-detect applicable rulesets from package.json and imports
+export checkCustomRules(path:string,options:Object=)→l,x,detectProjectRuleSets,r.push,Object.entries,detected.includes|run relevant custom rules against project directory
+PATTERNS: auto-detection via dependencies and imports|regex code scanning
+EDGE_CASES: state machine ignores matches inside strings/comments
+y(a)|parseGraphignore — internal helper
+g(a)|isGraphignored — internal helper
+$(a,b,c)|findFiles — internal helper
+S(a,b,c)|isInStringOrComment — internal helper

package/src/analysis/custom-rules.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/custom-rules.ctx
+// @ctx custom-rules.ctx
 import{readFileSync as e,writeFileSync as t,readdirSync as s,existsSync as n,statSync as r}from"fs";import{join as o,relative as c,dirname as i,resolve as l}from"path";import{fileURLToPath as u}from"url";import{shouldExcludeDir as f,shouldExcludeFile as a,parseGitignore as d}from"../core/filters.js";
 const p=i(u(import.meta.url)),h=o(p,"..","..","rules");
 let m=[];

package/src/analysis/db-analysis.ctx

@@ -0,0 +1,7 @@
+--- src/analysis/db-analysis.js ---
+@sig 5ff5551d
+export getDBSchema(path:string)→e,a.map,a.reduce|read parsed project to list all defined SQL tables and columns
+export getTableUsage(path:string,table:string)→e,t,readers.some,readers.push,writers.some,writers.push|find readers and writers for tables using parsed graph edges
+export getDBDeadTables(path:string)→e,t,r.add,r.has,o.filter,t.add|find schema tables not referenced by any read/write in code
+PATTERNS: dependency graph analysis|heuristic DB column extraction
+EDGE_CASES: hardcoded standard columns prevent false positive dead tables

package/src/analysis/db-analysis.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/db-analysis.ctx
+// @ctx db-analysis.ctx
 import{parseProject as e}from"../core/parser.js";import{buildGraph as t}from"../core/graph-builder.js";
 export async function getDBSchema(t){const a=(await e(t)).tables||[];return{tables:a.map(e=>({name:e.name,columns:e.columns,file:e.file,line:e.line})),totalTables:a.length,totalColumns:a.reduce((e,t)=>e+t.columns.length,0)}}
 export async function getTableUsage(a,s){const n=await e(a),o=t(n),r={};for(const[e,t,a]of o.edges){if("R→"!==t&&"W→"!==t)continue;const n=a;if(s&&n!==s)continue;r[n]||(r[n]={readers:[],writers:[]});const l=o.reverseLegend[e]||e,d=o.nodes[e],i={name:l,file:d?.f||"?"};"R→"===t?r[n].readers.some(e=>e.name===l)||r[n].readers.push(i):r[n].writers.some(e=>e.name===l)||r[n].writers.push(i)}const l=Object.entries(r).map(([e,t])=>({table:e,readers:t.readers,writers:t.writers,totalReaders:t.readers.length,totalWriters:t.writers.length})).sort((e,t)=>t.totalReaders+t.totalWriters-(e.totalReaders+e.totalWriters));return{tables:l,totalTables:l.length,totalQueries:l.reduce((e,t)=>e+t.totalReaders+t.totalWriters,0)}}

package/src/analysis/dead-code.ctx

@@ -0,0 +1,6 @@
+--- src/analysis/dead-code.js ---
+@sig 36cbbeca
+export getDeadCode(path:string)→i,m,u,e,a,h|scans dir for unused fns, classes, exports, vars, imports
+PATTERNS: AST traversal|cross-file dep tracking|heuristic usage regex
+EDGE_CASES: syntax err→skip file|test/css/tpl files→ignored
+y(a)|analyzeFileLocals — internal helper

package/src/analysis/dead-code.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/dead-code.ctx
+// @ctx dead-code.ctx
 import{readFileSync as e,readdirSync as t,statSync as n,existsSync as s}from"fs";import{join as o,relative as a,resolve as i,dirname as r}from"path";import{parse as c}from"../../vendor/acorn.mjs";
 import*as l from"../../vendor/walk.mjs";
 import{shouldExcludeDir as d,shouldExcludeFile as f,parseGitignore as p}from"../core/filters.js";

package/src/analysis/full-analysis.ctx

@@ -0,0 +1,9 @@
+--- src/analysis/full-analysis.js ---
+@sig df2774af
+M(t)→t.filter,t.slice|(internal utility)
+export getFullAnalysis(path:string,options:Object=)→n,C,a,S,D,M|run full code health analysis|combines cached and dynamic cross-file metrics
+export getAnalysisSummaryOnly(path:string)→C,a,S,D,M,P|get partial fast health score skipping cross-file analyses
+PATTERNS: incremental caching for per-file metrics|score aggregation with clamping
+EDGE_CASES: cross-file metrics always dynamic|handles missing cache gracefully
+w(a)|calculateHealthScore — internal helper
+F(a,b)|findJSFiles — internal helper

package/src/analysis/full-analysis.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/full-analysis.ctx
+// @ctx full-analysis.ctx
 import{readFileSync as t,readdirSync as e,statSync as s}from"fs";import{join as a,relative as o,resolve as n}from"path";import{getDeadCode as i}from"./dead-code.js";import{checkUndocumentedFile as r}from"./undocumented.js";import{getSimilarFunctions as l}from"./similar-functions.js";import{analyzeComplexityFile as c}from"./complexity.js";import{getLargeFiles as d}from"./large-files.js";import{getOutdatedPatterns as u}from"./outdated-patterns.js";import{getTableUsage as m}from"./db-analysis.js";import{checkJSDocFile as h}from"./jsdoc-checker.js";import{readCache as p,writeCache as y,computeContentHash as g,isCacheValid as f}from"./analysis-cache.js";import{shouldExcludeDir as j,shouldExcludeFile as x,parseGitignore as b}from"../core/filters.js";import{getWorkspaceRoot as C}from"../core/workspace.js";
 function w(t){let e=100;const s=[];e-=Math.min(2*t.deadCode.total,20),t.deadCode.total>0&&s.push(`${t.deadCode.total} unused functions/classes`),e-=Math.min(.5*t.undocumented.total,15),t.undocumented.total>10&&s.push(`${t.undocumented.total} undocumented items`),e-=Math.min(3*t.similar.total,15),t.similar.total>0&&s.push(`${t.similar.total} similar function pairs`);const a=t.complexity.stats?.critical||0,o=t.complexity.stats?.high||0;e-=Math.min(5*a+2*o,20),a>0&&s.push(`${a} critical complexity functions`);const n=t.largeFiles.stats?.critical||0,i=t.largeFiles.stats?.warning||0;e-=Math.min(4*n+1*i,10),n>0&&s.push(`${n} files need splitting`);const r=t.outdated.stats?.bySeverity?.error||0,l=t.outdated.stats?.bySeverity?.warning||0;if(e-=Math.min(3*r+1*l,10),t.outdated.redundantDeps?.length>0&&s.push(`${t.outdated.redundantDeps.length} redundant npm dependencies`),t.jsdocConsistency){const a=t.jsdocConsistency.errors||0,o=t.jsdocConsistency.warnings||0;e-=Math.min(2*a+1*o,15),a>0&&s.push(`${a} JSDoc consistency errors`)}let c;return e=Math.max(0,Math.min(100,Math.round(e))),c=e>=90?"excellent":e>=70?"good":e>=50?"warning":"critical",{score:e,rating:c,topIssues:s.slice(0,5)}}
 function F(t,n=t){t===n&&b(n);const i=[];try{for(const r of e(t)){const e=a(t,r),l=o(n,e);s(e).isDirectory()?j(r,l)||i.push(...F(e,n)):!r.endsWith(".js")||r.endsWith(".css.js")||r.endsWith(".tpl.js")||x(r,l)||i.push(e)}}catch(t){}return i}

package/src/analysis/jsdoc-checker.ctx

@@ -0,0 +1,10 @@
+--- src/analysis/jsdoc-checker.js ---
+@sig f91e4d5d
+export checkJSDocFile(filePath:string,code:string)→o,n.exec,e.slice,o.exec,n.slice,o.startsWith|check JSDoc consistency in single file
+export checkJSDocConsistency(path:string)→i,f,e,r,checkJSDocFile,o.push|check JSDoc consistency in directory|aggregates errors and warnings
+PATTERNS: AST parsing|regex for initial JSDoc extraction|AST type inference
+EDGE_CASES: handles optional param [] syntax|handles union types in JSDoc
+m(a,b)|extractJSDocComments — internal helper
+p(a)|findJSDocBefore — internal helper
+h(a)|extractParamName — internal helper
+y(a)|inferTypeFromDefault — internal helper

package/src/analysis/jsdoc-checker.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/jsdoc-checker.ctx
+// @ctx jsdoc-checker.ctx
 import{readFileSync as e,readdirSync as t,statSync as n}from"fs";import{join as s,relative as r,resolve as i}from"path";import{parse as o}from"../../vendor/acorn.mjs";
 import*as a from"../../vendor/walk.mjs";
 import{shouldExcludeDir as c,shouldExcludeFile as l,parseGitignore as u}from"../core/filters.js";

package/src/analysis/jsdoc-generator.ctx

@@ -0,0 +1,9 @@
+--- src/analysis/jsdoc-generator.js ---
+@sig 1f2fddef
+export generateJSDoc(filePath:string,options:Object=)→t,a,e,n,f.split,Math.max|(internal utility)
+s(t)|(internal utility)
+export generateJSDocFor(filePath:string,functionName:string,options:Object=)→generateJSDoc,name.endsWith|null→generateJSDoc,name.endsWith,results.find|null→generateJSDoc,name.endsWith,results.find|null→generateJSDoc,name.endsWith,results.find|generate JSDoc for a specific named function
+PATTERNS: AST tree walking via Acorn|reverse line scanning for existing JSDoc
+EDGE_CASES: skips getters/setters/constructors|infers types from AST defaults
+i(a)|buildJSDoc — internal helper
+o|buildJSDoc — internal helper

package/src/analysis/jsdoc-generator.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/jsdoc-generator.ctx
+// @ctx jsdoc-generator.ctx
 import{readFileSync as t}from"fs";import{relative as e}from"path";import{parse as n}from"../../vendor/acorn.mjs";
 import*as r from"../../vendor/walk.mjs";
 import{getWorkspaceRoot as a}from"../core/workspace.js";

package/src/analysis/large-files.ctx

@@ -0,0 +1,6 @@
+--- src/analysis/large-files.js ---
+@sig 8675b153
+analyzeFile(e,t)→s,i,n.split,o,l.simple,h.push|parse file, count structures, and assign size rating
+export getLargeFiles(path:string,options:Object=)→r,findJSFiles,analyzeFile,i.map,o.filter,o.sort|analyze directory to find overly large and complex files
+PATTERNS: AST visitor via Acorn|threshold-based scoring
+EDGE_CASES: ignores parse errors gracefully

package/src/analysis/large-files.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/large-files.ctx
+// @ctx large-files.ctx
 import{readFileSync as s,readdirSync as e,statSync as t}from"fs";import{join as n,relative as i,resolve as r}from"path";import{parse as o}from"../../vendor/acorn.mjs";import*as l from"../../vendor/walk.mjs";import{shouldExcludeDir as a,shouldExcludeFile as c,parseGitignore as u}from"../core/filters.js";function findJSFiles(s,r=s){s===r&&u(r);
 const o=[];try{for(const l of e(s)){const e=n(s,l),u=i(r,e);t(e).isDirectory()?a(l,u)||o.push(...findJSFiles(e,r)):!l.endsWith(".js")||l.endsWith(".css.js")||l.endsWith(".tpl.js")||c(l,u)||o.push(e)}}catch(s){}return o}
 function analyzeFile(e,t){const n=s(e,"utf-8"),r=i(t,e),a=n.split("\n").length;

package/src/analysis/outdated-patterns.ctx

@@ -0,0 +1,7 @@
+--- src/analysis/outdated-patterns.js ---
+@sig db82899a
+analyzeFilePatterns(r,t)→e,o,c,a.simple,r.check,i.push|scan AST against code patterns array, track async context
+analyzePackageJson(r)→s,n,e,JSON.parse,Object.keys,o.push|check package.json dependencies against redundant deps list
+export getOutdatedPatterns(path:string,options:Object=)→i,findJSFiles,analyzeFilePatterns,o.push,o.sort,analyzePackageJson|aggregate outdated code patterns and redundant package deps
+PATTERNS: AST ancestor traversal|declarative pattern rules list
+EDGE_CASES: tracks async context to detect sync operations in async functions

package/src/analysis/outdated-patterns.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/outdated-patterns.ctx
+// @ctx outdated-patterns.ctx
 import{readFileSync as e,readdirSync as r,statSync as t,existsSync as n}from"fs";import{join as s,relative as o,resolve as i}from"path";import{parse as c}from"../../vendor/acorn.mjs";import*as a from"../../vendor/walk.mjs";import{shouldExcludeDir as l,shouldExcludeFile as p,parseGitignore as d}from"../core/filters.js";
 const f={"node-fetch":{replacement:"fetch()",since:"Node 18"},"cross-fetch":{replacement:"fetch()",since:"Node 18"},"isomorphic-fetch":{replacement:"fetch()",since:"Node 18"},uuid:{replacement:"crypto.randomUUID()",since:"Node 19"},"deep-clone":{replacement:"structuredClone()",since:"Node 17"},"lodash.clonedeep":{replacement:"structuredClone()",since:"Node 17"},"abort-controller":{replacement:"AbortController (global)",since:"Node 15"},"form-data":{replacement:"FormData (global)",since:"Node 18"},"web-streams-polyfill":{replacement:"ReadableStream (global)",since:"Node 18"},"url-parse":{replacement:"URL (global)",since:"Node 10"},querystring:{replacement:"URLSearchParams",since:"Node 10"},rimraf:{replacement:"fs.rm({ recursive: true })",since:"Node 14"},mkdirp:{replacement:"fs.mkdir({ recursive: true })",since:"Node 10"},"recursive-readdir":{replacement:"fs.readdir({ recursive: true })",since:"Node 20"},glob:{replacement:"fs.glob()",since:"Node 22"}},m=[{name:"var-usage",description:"Use const/let instead of var",check:e=>"VariableDeclaration"===e.type&&"var"===e.kind,severity:"warning",replacement:"const/let"},{name:"require-usage",description:"Use ESM import instead of require()",check:e=>"CallExpression"===e.type&&"Identifier"===e.callee.type&&"require"===e.callee.name,severity:"info",replacement:"import ... from"},{name:"module-exports",description:"Use ESM export instead of module.exports",check:e=>"AssignmentExpression"===e.type&&"MemberExpression"===e.left.type&&"Identifier"===e.left.object.type&&"module"===e.left.object.name&&"Identifier"===e.left.property.type&&"exports"===e.left.property.name,severity:"info",replacement:"export default/export"},{name:"buffer-constructor",description:"new Buffer() is deprecated",check:e=>"NewExpression"===e.type&&"Identifier"===e.callee.type&&"Buffer"===e.callee.name,severity:"error",replacement:"Buffer.from() / Buffer.alloc()"},{name:"arguments-usage",description:"Use rest parameters instead of arguments",check:e=>"Identifier"===e.type&&"arguments"===e.name,severity:"warning",replacement:"...args"},{name:"promisify-usage",description:"Use fs/promises instead of util.promisify",check:e=>"CallExpression"===e.type&&"MemberExpression"===e.callee.type&&"Identifier"===e.callee.object.type&&"util"===e.callee.object.name&&"Identifier"===e.callee.property.type&&"promisify"===e.callee.property.name,severity:"info",replacement:"fs/promises module"},{name:"sync-in-async",description:"Avoid sync methods in async context (readFileSync, etc.)",check:(e,r)=>{if("CallExpression"!==e.type)return!1;
 const t=e.callee;return"MemberExpression"===t.type&&"Identifier"===t.property.type&&t.property.name.endsWith("Sync")&&r.inAsync},severity:"warning",replacement:"async fs/promises methods"}];function findJSFiles(e,n=e){e===n&&d(n);

package/src/analysis/similar-functions.ctx

@@ -0,0 +1,6 @@
+--- src/analysis/similar-functions.js ---
+@sig 73623fb2
+export getSimilarFunctions(path:string,options:Object=)→r,m,p,l.push,f,o.push|extract and compare signatures across directory for similar pairs
+PATTERNS: structural hashing of control flow|pair-wise comparison scoring
+EDGE_CASES: skips very small functions|ignores overloads (same name/file)
+u(a,b,c)|buildSignature — internal helper

package/src/analysis/similar-functions.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/similar-functions.ctx
+// @ctx similar-functions.ctx
 import{readFileSync as t,readdirSync as e,statSync as n}from"fs";import{join as s,relative as a,resolve as r}from"path";import{parse as l}from"../../vendor/acorn.mjs";
 import*as o from"../../vendor/walk.mjs";
 import{shouldExcludeDir as i,shouldExcludeFile as h,parseGitignore as c}from"../core/filters.js";

package/src/analysis/test-annotations.ctx

@@ -0,0 +1,11 @@
+--- src/analysis/test-annotations.js ---
+@sig b2010e5d
+export parseAnnotations(content:string,filePath:string)→t.split,t.startsWith,i,n.push,t.match,f.split|parse checklist lines into test feature objects
+export getAllFeatures(dir:string)→c,o,a,t,parseAnnotations,n.push|read and parse all test features from context dir
+export getPendingTests(dir:string)→c,getAllFeatures,r,n.push|return list of pending tests with file paths
+export markTestPassed(testId:string)→t.split,f|mark specific test id as passed [x]
+export markTestFailed(testId:string,reason:string)→t.split,f|mark specific test id as failed [!] with reason
+export getTestSummary(dir:string)→getAllFeatures,c.push,Math.round|compute total, passed, failed, pending counts
+export resetTestState()→process.cwd,o,a,t,e.replace,n|reset all test states to pending [ ]
+PATTERNS: regex markdown checklist parsing|file rewriting for state
+EDGE_CASES: handles unreadable files gracefully|handles missing failure reasons

package/src/analysis/test-annotations.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/test-annotations.ctx
+// @ctx test-annotations.ctx
 import{readFileSync as t,readdirSync as s,statSync as e,writeFileSync as n}from"fs";
 import{join as o,relative as r,resolve as c}from"path";
 function a(t){const n=[];try{for(const r of s(t)){const s=o(t,r);e(s).isDirectory()&&!r.startsWith(".")?n.push(...a(s)):r.endsWith(".ctx.md")&&n.push(s)}}catch(t){}return n}

package/src/analysis/type-checker.ctx

@@ -0,0 +1,6 @@
+--- src/analysis/type-checker.js ---
+@sig 5e85e31c
+export checkTypes(path:string,options:Object=)→n,o,l,path.includes,e,stdout.on|null, diagnostics: TypeDiagnostic[], summary: Object, hint: string|null →resolve,detectTsc,buildArgs,path.includes,spawn,stdout.on|null, diagnostics: TypeDiagnostic[], summary: Object, hint: string|null →resolve,detectTsc,buildArgs,path.includes,spawn,stdout.on|null, diagnostics: TypeDiagnostic[], summary: Object, hint: string|null →resolve,detectTsc,buildArgs,path.includes,spawn,stdout.on|spawn tsc process, collect and parse type diagnostics
+PATTERNS: subprocess spawning|regex CLI output parsing
+EDGE_CASES: falls back to npx if global tsc missing|auto-generates config args
+i(a,b)|parseDiagnosticLine — internal helper

package/src/analysis/type-checker.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/type-checker.ctx
+// @ctx type-checker.ctx
 import{execSync as t,spawn as e}from"child_process";import{existsSync as s}from"fs";import{resolve as n,join as r}from"path";
 function o(){try{return{available:!0,version:t("tsc --version",{encoding:"utf-8",timeout:5e3}).trim(),path:t("which tsc",{encoding:"utf-8",timeout:5e3}).trim()}}catch(e){try{return{available:!0,version:t("npx tsc --version",{encoding:"utf-8",timeout:15e3}).trim(),path:"npx tsc"}}catch(t){return{available:!1,version:null,path:null}}}}
 function i(t,e){const s=t.match(/^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.+)$/);return s?{file:s[1],line:parseInt(s[2]),column:parseInt(s[3]),severity:s[4],message:s[6],code:s[5]}:null}

package/src/analysis/undocumented.ctx

@@ -0,0 +1,8 @@
+--- src/analysis/undocumented.js ---
+@sig 898e8f30
+export checkUndocumentedFile(filePath:string,code:string,level:string)→c,n.exec,t.slice,e.push,f,s.push|analyze single file for undocumented classes, functions, methods
+export getUndocumented(path:string,options:Object=)→r,d,t,o,checkUndocumentedFile,i.push|scan directory for all undocumented items
+export getUndocumentedSummary(path:string,options:Object=)→getUndocumented,n.filter,n.slice|scan directory and return aggregated undocumented summary
+PATTERNS: AST traversal|regex JSDoc extraction
+EDGE_CASES: skips lifecycle methods|skips private prefixed methods
+p(a,b)|findJSDocBefore — internal helper

package/src/analysis/undocumented.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/analysis/undocumented.ctx
+// @ctx undocumented.ctx
 import{readFileSync as t,readdirSync as e,statSync as n}from"fs";import{join as s,relative as o,resolve as r}from"path";import{parse as c}from"../../vendor/acorn.mjs";
 import*as i from"../../vendor/walk.mjs";
 import{shouldExcludeDir as l,shouldExcludeFile as a,parseGitignore as u}from"../core/filters.js";

package/src/cli/cli-handlers.ctx

@@ -0,0 +1,7 @@
+--- src/cli/cli-handlers.js ---
+@sig 0737c704
+R(r)→r.startsWith,r.find,q|(internal utility)
+PATTERNS: command definition map|lazy execution
+EDGE_CASES: falls back to cwd if no path given|validates required args
+O(a,b)|getArg — internal helper
+export CLI_HANDLERS|map of CLI command handlers

package/src/cli/cli-handlers.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/cli/cli-handlers.ctx
+// @ctx cli-handlers.ctx
 import{getSkeleton as r,expand as e,deps as s,usages as a}from"../mcp/tools.js";import{getPendingTests as t,getTestSummary as n}from"../analysis/test-annotations.js";import{getFilters as o}from"../core/filters.js";import{getInstructions as c}from"../compact/instructions.js";import{getUndocumentedSummary as i}from"../analysis/undocumented.js";import{getDeadCode as d}from"../analysis/dead-code.js";import{generateJSDoc as l}from"../analysis/jsdoc-generator.js";import{getSimilarFunctions as m}from"../analysis/similar-functions.js";import{getComplexity as u}from"../analysis/complexity.js";import{getLargeFiles as p}from"../analysis/large-files.js";import{getOutdatedPatterns as g}from"../analysis/outdated-patterns.js";import{getFullAnalysis as y}from"../analysis/full-analysis.js";import{compressFile as h}from"../compact/compress.js";import{getProjectDocs as f,generateContextFiles as j}from"../compact/doc-dialect.js";import{getGraph as b}from"../mcp/tools.js";import{parseProject as x}from"../core/parser.js";import{resolvePath as q}from"../core/workspace.js";import{checkJSDocConsistency as A}from"../analysis/jsdoc-checker.js";import{checkTypes as w}from"../analysis/type-checker.js";import{compactProject as E,expandProject as S}from"../compact/compact.js";import{injectJSDoc as U,stripJSDoc as P,validateCtxContracts as k}from"../compact/ctx-to-jsdoc.js";import{getConfig as v,setConfig as C,getModeDescription as D,getModeWorkflow as I}from"../compact/mode-config.js";import{compactMigrate as F}from"../compact/compact-migrate.js";
 function O(r,e){const s=r.find(r=>r.startsWith(`--${e}=`));return s?s.split("=")[1]:void 0}
 function R(r){const e=r.find(r=>!r.startsWith("--"))||".";return q(e)}

package/src/cli/cli.ctx

@@ -0,0 +1,6 @@
+--- src/cli/cli.js ---
+@sig daa9547d
+export printHelp()→console.log|log usage instructions and available commands to stdout
+export runCLI(command:string,args:string[])→printHelp,console.error,process.exit,o.handler,console.log,JSON.stringify|parse args, validate, and route to corresponding cli handler
+PATTERNS: generic command router|table help text
+EDGE_CASES: handles unknown commands gracefully|validates required args

package/src/cli/cli.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/cli/cli.ctx
+// @ctx cli.ctx
 import{CLI_HANDLERS as e}from"./cli-handlers.js";
 export function printHelp(){console.log("\nproject-graph-mcp - MCP server for AI agents\n\nUsage:\n  npx project-graph-mcp                  Start MCP stdio server\n  npx project-graph-mcp <command> [args] Run CLI command\n\nCommands:\n  config                 Generate MCP config with correct paths\n  skeleton <path>        Get compact project overview\n  expand <symbol>        Expand minified symbol (e.g., SN, SN.togglePin)\n  deps <symbol>          Get dependency tree\n  usages <symbol>        Find all usages\n  pending <path>         List pending .ctx.md test checklists\n  summary <path>         Get test progress summary\n  undocumented <path>    Find missing JSDoc (--level=tests|params|all)\n  deadcode <path>        Find unused functions/classes\n  jsdoc <file>           Generate JSDoc for file\n  similar <path>         Find similar functions (--threshold=60)\n  complexity <path>      Analyze cyclomatic complexity (--min=1)\n  largefiles <path>      Find files needing split (--problematic)\n  outdated <path>        Find legacy patterns & redundant deps\n  analyze <path>         Run ALL checks with Health Score\n  jsdoc-check <path>     Validate JSDoc vs function signatures\n  types <path>           Run tsc type checking (--max=50)\n  compress <file>        Compress JS file for AI (--no-beautify, --no-legend)\n  compact <path>         Compact all JS files (--dry-run)\n  beautify <path>        Beautify/expand all JS files (--dry-run)\n  inject-jsdoc <path>    Generate JSDoc from .ctx files and inject into source\n  strip-jsdoc <path>     Strip all JSDoc blocks from source files\n  docs <path>            Get project docs in doc-dialect format (--file=<name>)\n  generate-ctx <path>    Generate .context/ docs (--overwrite --scope=focus)\n  validate-ctx <path>    Validate .ctx contracts against source AST (--strict)\n  mode <path>            Show current compact code mode and workflow\n  compact-migrate <path> Migrate formatted source to compact mode (git must be clean)\n  set-mode <path> <1|2>  Set mode (1=compact*, 2=full)\n  serve <path>           Start web dashboard (--port=N)\n  filters                Show current filter configuration\n  instructions           Show agent guidelines (JSDoc, Arch)\n  help                   Show this help\n\nQuick Start:\n  npx project-graph-mcp config            # Get MCP config for your IDE\n\nWeb Dashboard:\n  npx project-graph-mcp serve .          # Start at auto-assigned port\n  npx project-graph-mcp serve . --port 3000\n  # Then open http://localhost:{port}/ or http://project-graph.local/{name}/\n\nExamples:\n  npx project-graph-mcp skeleton src/components\n  npx project-graph-mcp expand SN\n  npx project-graph-mcp compact src/ --dry-run\n")}
 export async function runCLI(n,t){if(!n||"help"===n||"--help"===n||"-h"===n)return void printHelp();

package/src/compact/ai-context.ctx

@@ -0,0 +1,6 @@
+--- src/compact/ai-context.js ---
+@sig 8aed2da2
+estimateTokens(e)→JSON.stringify,Math.ceil|(internal utility)
+export getAiContext(path:string,options:Object=)→e,s,estimateTokens,o,n,r|get project context including skeleton, docs, and optionally compressed files
+PATTERNS: token estimation heuristic|parallel generation
+EDGE_CASES: gracefully skips unreadable files|handles missing files

package/src/compact/ai-context.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/ai-context.ctx
+// @ctx ai-context.ctx
 import{estimateTokens}from"../core/utils.js";import{resolve as e,extname as t,relative as _rel,join as _join,basename as _base}from"path";import{getSkeleton as s,getGraph as o}from"../mcp/tools.js";import{getProjectDocs as n}from"./doc-dialect.js";import{compressFile as i}from"./compress.js";import{findJSFiles as r}from"../core/parser.js";import{readFileSync as _rf,existsSync as _ex,writeFileSync as _wf}from"fs";
 const c=new Set([".js",".mjs",".ts",".tsx"]);
 const IGNORE_FILE=".contextignore";

package/src/compact/compact-migrate.ctx

@@ -0,0 +1,8 @@
+--- src/compact/compact-migrate.js ---
+@sig b7ae75d3
+export compactMigrate(path:string,options:Object=)→m,message.includes,h,r,y,e|(internal utility)
+PATTERNS: (internal utility)
+EDGE_CASES: (internal utility)
+w(a,b)|extractNames — internal helper
+S(a,b,c)|buildNamesDirective — internal helper
+x(a)|updateCtxNames — internal helper

package/src/compact/compact-migrate.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/compact-migrate.ctx
+// @ctx compact-migrate.ctx
 import{walkJSFiles}from"../core/file-walker.js";import{readFileSync as e,writeFileSync as t,existsSync as s}from"fs";import{join as o,extname as i,relative as r,basename as c,dirname as l}from"path";import{execSync as m}from"child_process";import{compactProject as f}from"./compact.js";import{validatePipeline as d}from"./validate-pipeline.js";import{setConfig as u}from"./mode-config.js";
 const p=new Set([".js",".mjs"]),g=new Set(["node_modules",".git","vendor",".context","dev-docs",".agent",".agents",".expanded"]);
 

package/src/compact/compact.ctx

@@ -0,0 +1,11 @@
+--- src/compact/compact.js ---
+@sig 596f30f0
+walkJSFiles(e,t=)→n,a.startsWith,r,o,f.has,walkJSFiles|(internal utility)
+addTopLevelNewlines(e)→e.replace|insert newlines after minified semicolons to format top-level statements
+resolveCtxPath(e,t)→a,c,i,l,r,s|(internal utility)
+compactFile(n,o)→e,s.trim,u,addTopLevelNewlines,resolveCtxPath,a.startsWith|minify single JS file, prepend @ctx header if .ctx exists
+beautifyFile(n)→e,o.trim,u,t|format single JS file with proper indentation
+export compactProject(path:string,options:Object=)→walkJSFiles,a,e,u,addTopLevelNewlines,compactFile|compact all JS files in dir, per-file error handling, ret stats+savings%
+PATTERNS: Terser mangle:false preserves all names|per-file try/catch collects errors array|dryRun mode estimates without writing|skips node_modules,vendor,.git,.context
+EDGE_CASES: empty files return 0/0|syntax errors collected in errors[] not thrown|files with only comments become empty (correct behavior)
+expandProject(t,n=)|expandProject — internal helper

package/src/compact/compact.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/compact.ctx
+// @ctx compact.ctx
 import{resolveCtxRelPath as resolveCtxPath}from"./ctx-resolver.js";import{walkJSFiles}from"../core/file-walker.js";import{readFileSync as e,writeFileSync as t,existsSync as s}from"fs";import{join as r,extname as c,relative as a,basename as i,dirname as l}from"path";import{minify as u}from"../../vendor/terser.mjs";
 
 function addTopLevelNewlines(e){return e.replace(/;(import )/g,";\n$1").replace(/;(export )/g,";\n$1").replace(/\}(export )/g,"}\n$1").replace(/\}(function )/g,"}\n$1").replace(/\}(async function )/g,"}\n$1").replace(/\}(class )/g,"}\n$1").replace(/;(const |let |var )/g,";\n$1")}

package/src/compact/compress.ctx

@@ -0,0 +1,7 @@
+--- src/compact/compress.js ---
+@sig 094fad9d
+export compressFile(filePath:string,options:Object=)→n,o.has,e,i,d.trim,a|minifies JS/TS via Terser, prepends JSDoc legend
+export editCompressed(rootPath:string,filePath:string,symbolName:string,newCode:string=)→e,s,l,m.slice,a|find symbol in file and replace its code safely
+PATTERNS: AST traversal|regex JSDoc extraction|Terser minification
+EDGE_CASES: validates syntax before writing|handles empty files
+c(a,b)|extractLegend — internal helper

package/src/compact/compress.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/compress.ctx
+// @ctx compress.ctx
 import{estimateTokens as i}from"../core/utils.js";import{readFileSync as e}from"fs";import{basename as t,extname as n}from"path";import{minify as a}from"../../vendor/terser.mjs";import{parse as s}from"../../vendor/acorn.mjs";import{simple as r}from"../../vendor/walk.mjs";
 const o=new Set([".js",".mjs",".ts",".tsx"]);
 

package/src/compact/ctx-resolver.ctx

@@ -0,0 +1,2 @@
+export resolveCtxPath(rootDir:string,filePath:string)|find .ctx file for a source file|checks .context/ then co-located
+export readCtxFile(rootDir:string,filePath:string)|read .ctx content for a source file|returns null if not found

package/src/compact/ctx-resolver.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/ctx-resolver.ctx
+// @ctx ctx-resolver.ctx
 import{readFileSync as t,existsSync as s}from"fs";import{join as i,basename as a,extname as c,dirname as p,relative as l}from"path";
 export function resolveCtxPath(e,n){const o=a(n,c(n))+".ctx",r=p(n),d=i(e,".context",r,o);if(s(d))return d;const f=i(e,r,o);return s(f)?f:null}
 export function resolveCtxRelPath(e,n){const o=l(n,e),r=a(o,c(o))+".ctx",u=p(o),d=i(n,".context",u,r);if(s(d))return".context/"+u+"/"+r;const f=i(n,u,r);return s(f)?u+"/"+r:null}

package/src/compact/ctx-to-jsdoc.ctx

@@ -0,0 +1,11 @@
+--- src/compact/ctx-to-jsdoc.js ---
+@sig 174ef437
+m(t,e)→t.replace,r,o|(internal utility)
+F(t)|(internal utility)
+export parseCtxFile(ctxPath:string)→t.split,t.match,r.split,i.trim,functions.push|null, functions: Array<{name: string, params: string, exported: boolean, description: string→ctxContent.split,line.match,arrowParts.split,desc.trim,functions.push|null, functions: Array<{name: string, params: string, exported: boolean, description: string→ctxContent.split,line.match,arrowParts.split,desc.trim,functions.push|null, functions: Array<{name: string, params: string, exported: boolean, description: string→ctxContent.split,line.match,arrowParts.split,desc.trim,functions.push|parse .ctx file into structured fn signatures with params+types
+export injectJSDoc(filePath:string,options:Object=)→d,a,m,t,parseCtxFile,c|inject JSDoc from .ctx into source, skip if JSDoc exists, AST-located
+export stripJSDoc(filePath:string,options:Object=)→d,t,c,value.startsWith,f.filter,u.slice|strip all JSDoc via AST comments (safe—ignores strings), regex fallback
+export validateCtxContracts(rootPath:string,options:Object=)→d,a,m,t,parseCtxFile,c|validate if .ctx signatures match source AST signatures
+PATTERNS: AST-based comment detection via Acorn onComment array|reverse-order insertions preserve line numbers|export keyword detection for duplicate prevention
+EDGE_CASES: strings containing /** preserved by AST parser|blank lines between JSDoc and fn handled by trimEnd|unparseable files fall back to regex strip
+h(a)|splitTopLevelParams — internal helper

package/src/compact/ctx-to-jsdoc.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/ctx-to-jsdoc.ctx
+// @ctx ctx-to-jsdoc.ctx
 import{walkJSFiles}from"../core/file-walker.js";import{resolveCtxPath}from"./ctx-resolver.js";import{buildJSDocFromRaw as u}from"./jsdoc-builder.js";import{readFileSync as t,writeFileSync as e,readdirSync as n,statSync as s,existsSync as o}from"fs";
 import{join as r,extname as i,relative as a}from"path";
 import{parse as c}from"../../vendor/acorn.mjs";

package/src/compact/doc-dialect.ctx

@@ -0,0 +1,11 @@
+--- src/compact/doc-dialect.js ---
+@sig bccef7f4
+export generateDocDialect(graph:Object,rootPath:string)→r,s.push,c.push,c.join,edges.filter,h.push|generate compact doc-dialect string from graph|includes project/file/function levels
+export readContextDocs(rootPath:string)→i,x,t,n.set,relPath.startsWith,n.keys|read manual docs (mirror + colocated)|colocated overrides mirror
+export getProjectDocs(rootPath:string,parsed:Object,options:Object=)→readContextDocs,j,t,generateDocDialect,t.indexOf,t.slice|get project docs|merges manual .ctx and auto-generated dialect
+export checkStaleness(rootPath:string,parsed:Object)→i,x,t,e.match,E,o.push|check .ctx files staleness vs current AST
+export generateContextFiles(graph:Object,rootPath:string,parsed:Object,options:Object=)→i,s,n,r,c.push,c.join|generate .context/ templates|supports focus scope and overwrite merge
+PATTERNS: two-tier doc resolution (colocated > mirror)|AST signature hashing
+EDGE_CASES: preserves existing placeholders on overwrite|handles git diff for focus scope
+S(a,b)|resolveCtxMdPath — internal helper
+y(a,b,c,d,e,f,g)|buildFileTemplate — internal helper

package/src/compact/doc-dialect.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/doc-dialect.ctx
+// @ctx doc-dialect.ctx
 import{readFileSync as t,readdirSync as e,existsSync as s,mkdirSync as n,writeFileSync as o,statSync as c}from"fs";
 import{join as i,basename as r,extname as a,dirname as l,relative as h}from"path";
 import{execSync as f}from"child_process";
@@ -16,4 +16,4 @@ export function getProjectDocs(e,s,n={}){const{file:o}=n,c=readContextDocs(s);if
 function E(t,e){const s=[];for(const n of(e.functions||[]).filter(e=>e.file===t))s.push(`F:${n.exported?"e":""}:${n.name}(${n.params?.join(",")||""})`);for(const n of(e.classes||[]).filter(e=>e.file===t)){const t=n.methods?.sort().join(",")||"";s.push(`C:${n.name}:${n.extends||""}:${t}`)}return s.sort(),u("md5").update(s.join("|")).digest("hex").slice(0,8)}
 export function checkStaleness(e,s){const n=i(e,".context"),o=[];let c=0,r=0;for(const{relPath:e,absPath:i}of x(n,n))try{const e=t(i,"utf-8"),n=e.match(/@sig\s+(\w+)/),a=e.match(/^--- (.+) ---/m);if(!n||!a){r++;continue}E(a[1],s)!==n[1]?o.push(a[1]):c++}catch{}for(const{absPath:n}of x(e,e).filter(t=>!t.relPath.startsWith(".context")))try{const e=t(n,"utf-8"),i=e.match(/@sig\s+(\w+)/),a=e.match(/^--- (.+) ---/m);if(!i||!a){r++;continue}E(a[1],s)!==i[1]?o.push(a[1]):c++}catch{}return{stale:o,fresh:c,unknown:r}}
 export async function generateContextFiles(t,e,c,a={}){const{overwrite:l=!1,scope:h="all"}=a,u=i(e,".context"),p=[],m=[],d={};s(u)||n(u,{recursive:!0});const $=i(u,"project.ctx");if(!s($)||l){const s=r(e),{stats:n}=t,c=[];n.files>0&&c.push(`${n.files} files`),n.classes>0&&c.push(`${n.classes} classes`),n.functions>0&&c.push(`${n.functions} functions`);let i=[`=== PROJECT: ${s} ===`,"ARCH: {DESCRIBE}","FLOW: {DESCRIBE}",`STATS: ${c.join("|")}`].join("\n")+"\n";o($,i,"utf-8"),p.push("project.ctx"),d["project.ctx"]=i}else m.push("project.ctx");const g={};for(const[e,s]of Object.entries(t.nodes)){const t=s.f;t&&(g[t]||(g[t]=[]),g[t].push({shortName:e,...s}))}let x=null;if("focus"===h)try{const t=f("git diff --name-only HEAD~5",{cwd:e,encoding:"utf-8"});x=new Set(t.split("\n").filter(t=>t.endsWith(".js")||t.endsWith(".mjs")||t.endsWith(".ts")).map(t=>t.trim()).filter(Boolean))}catch{x=null}else Array.isArray(h)&&(x=new Set(h));const j=Object.entries(g).filter(([t])=>!x||x.has(t));for(let s=0;s<j.length;s+=5){const n=j.slice(s,s+5),o=await Promise.allSettled(n.map(([s,n])=>y(s,n,t,c,u,e,l)));for(const t of o)if("fulfilled"===t.status&&t.value){const{action:e,path:s,template:n}=t.value;"created"===e?(p.push(s),d[s]=n):m.push(s)}}const S={created:p,skipped:m};return p.length>0&&(S.templates=d),S}
-async function y(e,c,h,f,u,x,j){const S=r(e,a(e))+".ctx",y=l(e),D=i(u,y),C=i(D,S),b=i(y,S),R=i(x,y,S);if((s(C)||s(R))&&!j)return{action:"skipped",path:b};let W;s(D)||n(D,{recursive:!0});const P=s(R)?R:s(C)?C:null;if(P&&j)try{W=function(t){const e=new Map;for(const s of t.split("\n")){const t=s.trim();if(!t||t.startsWith("---")||t.startsWith("@sig")||t.startsWith("@enrich")||t.startsWith("Rules:")||t.startsWith("Save this")||t.startsWith("CALLS→")||t.startsWith("R→")||t.startsWith("W→"))continue;const n=t.match(/^(PATTERNS|EDGE_CASES):\s*(.+)/);if(n&&"{DESCRIBE}"!==n[2]){e.set(n[1],n[2]);continue}const o=t.match(/^(?:export\s+)?(?:class\s+)?\.?([\w]+)\([^)]*\)(?:[^|]*?)\|(.+)/);if(o&&"{DESCRIBE}"!==o[2]){e.set(o[1],o[2]);continue}const c=t.match(/^class\s+([\w]+)[^|]*\|[^|]*\|(.+)/);c&&"{DESCRIBE}"!==c[2]&&e.set(c[1],c[2])}return e}(t(P,"utf-8"))}catch{}let w=function(t,e,s,n,o){const c=[`--- ${t} ---`,`@sig ${E(t,n)}`],i=o||new Map,r={};for(const e of n.functions||[])e.file===t&&(r[e.name]=e);const a={};for(const e of n.classes||[])e.file===t&&(a[e.name]=e);for(const t of e){const e=s.reverseLegend[t.shortName]||t.shortName;if("C"===t.t){const n=a[e]||{},o=t.x?` extends ${t.x}`:"",r=t.m?.length||0,l=t.$?.length||0,h=[];r>0&&h.push(`${r}m`),l>0&&h.push(`${l}$`);const f=i.get(e)||"{DESCRIBE}";if(c.push(`class ${e}${o}|${h.join(",")}|${f}`),t.m)for(const e of t.m){const t=s.reverseLegend[e]||e,n=i.get(t)||"{DESCRIBE}";c.push(`  .${t}()|${n}`)}n.calls?.length>0&&c.push(`  CALLS→${n.calls.slice(0,8).join(",")}`),n.dbReads?.length>0&&c.push(`  R→${n.dbReads.join(",")}`),n.dbWrites?.length>0&&c.push(`  W→${n.dbWrites.join(",")}`)}else if("F"===t.t){const s=r[e]||{},n=t.e?"export ":"",o=s.params?.length>0?s.params.join(","):"",a=s.returns?`→${s.returns}`:"",l=s.calls?.slice(0,6)||[],h=l.length>0?`→${l.join(",")}`:"",f=i.get(e)||"{DESCRIBE}";c.push(`${n}${e}(${o})${a}${h}|${f}`),s.dbReads?.length>0&&c.push(`  R→${s.dbReads.join(",")}`),s.dbWrites?.length>0&&c.push(`  W→${s.dbWrites.join(",")}`)}}const l=i.get("PATTERNS")||"{DESCRIBE}",h=i.get("EDGE_CASES")||"{DESCRIBE}";return c.push(`PATTERNS: ${l}`),c.push(`EDGE_CASES: ${h}`),c.join("\n").includes("{DESCRIBE}")&&c.splice(2,0,`@enrich: Replace each {DESCRIBE} below. Read ${t} for context.`,"  Rules: max 80ch, pipe|separated, abbrev (fn/ret/cfg/init/auth/db/msg).","  Save this file after filling all markers. Remove @enrich lines when done."),c.join("\n")}(e,c,h,f,W);o(C,w+"\n","utf-8");try{const n=i(x,e);if(s(n)&&e.endsWith(".js")){const s=t(n,"utf-8"),o=m(s),c=d(s,e),i=$(s,e,"tests"),r=g(s,e);p(u,e,{sig:o,contentHash:o,complexity:c,undocumented:i,jsdocIssues:r})}}catch{}const A=r(e,a(e))+".ctx.md",L=i(D,A);if(!s(L)){const t=`# ${r(e)}\n\n## Notes\n\n## TODO\n\n## Decisions\n`;o(L,t,"utf-8")}return{action:"created",path:b,template:w}}
+async function y(e,c,h,f,u,x,j){const S=r(e,a(e))+".ctx",y=l(e),D=i(u,y),C=i(D,S),b=i(y,S),R=i(x,y,S);if((s(R)||s(C))&&!j)return{action:"skipped",path:b};let W;s(D)||n(D,{recursive:!0});const P=s(R)?R:s(C)?C:null;if(P&&j)try{W=function(t){const e=new Map;for(const s of t.split("\n")){const t=s.trim();if(!t||t.startsWith("---")||t.startsWith("@sig")||t.startsWith("@enrich")||t.startsWith("Rules:")||t.startsWith("Save this")||t.startsWith("CALLS→")||t.startsWith("R→")||t.startsWith("W→"))continue;const n=t.match(/^(PATTERNS|EDGE_CASES):\s*(.+)/);if(n&&"{DESCRIBE}"!==n[2]){e.set(n[1],n[2]);continue}const o=t.match(/^(?:export\s+)?(?:class\s+)?\.?([\w]+)\([^)]*\)(?:[^|]*?)\|(.+)/);if(o&&"{DESCRIBE}"!==o[2]){e.set(o[1],o[2]);continue}const c=t.match(/^class\s+([\w]+)[^|]*\|[^|]*\|(.+)/);c&&"{DESCRIBE}"!==c[2]&&e.set(c[1],c[2])}return e}(t(P,"utf-8"))}catch{}let w=function(t,e,s,n,o){const c=[`--- ${t} ---`,`@sig ${E(t,n)}`],i=o||new Map,r={};for(const e of n.functions||[])e.file===t&&(r[e.name]=e);const a={};for(const e of n.classes||[])e.file===t&&(a[e.name]=e);for(const t of e){const e=s.reverseLegend[t.shortName]||t.shortName;if("C"===t.t){const n=a[e]||{},o=t.x?` extends ${t.x}`:"",r=t.m?.length||0,l=t.$?.length||0,h=[];r>0&&h.push(`${r}m`),l>0&&h.push(`${l}$`);const f=i.get(e)||"{DESCRIBE}";if(c.push(`class ${e}${o}|${h.join(",")}|${f}`),t.m)for(const e of t.m){const t=s.reverseLegend[e]||e,n=i.get(t)||"{DESCRIBE}";c.push(`  .${t}()|${n}`)}n.calls?.length>0&&c.push(`  CALLS→${n.calls.slice(0,8).join(",")}`),n.dbReads?.length>0&&c.push(`  R→${n.dbReads.join(",")}`),n.dbWrites?.length>0&&c.push(`  W→${n.dbWrites.join(",")}`)}else if("F"===t.t){const s=r[e]||{},n=t.e?"export ":"",o=s.params?.length>0?s.params.join(","):"",a=s.returns?`→${s.returns}`:"",l=s.calls?.slice(0,6)||[],h=l.length>0?`→${l.join(",")}`:"",f=i.get(e)||"{DESCRIBE}";c.push(`${n}${e}(${o})${a}${h}|${f}`),s.dbReads?.length>0&&c.push(`  R→${s.dbReads.join(",")}`),s.dbWrites?.length>0&&c.push(`  W→${s.dbWrites.join(",")}`)}}const l=i.get("PATTERNS")||"{DESCRIBE}",h=i.get("EDGE_CASES")||"{DESCRIBE}";return c.push(`PATTERNS: ${l}`),c.push(`EDGE_CASES: ${h}`),c.join("\n").includes("{DESCRIBE}")&&c.splice(2,0,`@enrich: Replace each {DESCRIBE} below. Read ${t} for context.`,"  Rules: max 80ch, pipe|separated, abbrev (fn/ret/cfg/init/auth/db/msg).","  Save this file after filling all markers. Remove @enrich lines when done."),c.join("\n")}(e,c,h,f,W);const srcDir=i(x,y);s(srcDir)||n(srcDir,{recursive:!0});o(R,w+"\n","utf-8");try{const n=i(x,e);if(s(n)&&e.endsWith(".js")){const s=t(n,"utf-8"),o=m(s),c=d(s,e),i=$(s,e,"tests"),r=g(s,e);p(u,e,{sig:o,contentHash:o,complexity:c,undocumented:i,jsdocIssues:r})}}catch{}const A=r(e,a(e))+".ctx.md",L=i(D,A);if(!s(L)){const t=`# ${r(e)}\n\n## Notes\n\n## TODO\n\n## Decisions\n`;o(L,t,"utf-8")}return{action:"created",path:b,template:w}}

package/src/compact/expand.ctx

@@ -0,0 +1,14 @@
+--- src/compact/expand.js ---
+@sig a9cd25fe
+@enrich: Replace each (internal utility) below. Read src/compact/expand.js for context.
+  Rules: max 80ch, pipe|separated, abbrev (fn/ret/cfg/init/auth/db/msg).
+  Save this file after filling all markers. Remove @enrich lines when done.
+$(e,n)→c,a,p,i,s,t|(internal utility)
+export expandProject(rootPath:string,options:Object=)→i,s,S,l,$,expandFile|expand all src/ → .expanded/ with JSDoc injection
+export expandFile(filePath:string,ctxContent:string,options:Object=)→t,r.trim,m,i.split,s.trim,s.startsWith|beautify compact JS + inject JSDoc from .ctx|core hybrid mode expand
+PATTERNS: Terser beautify (no compress/mangle)|AST walk for injection points|reverse-order insertion|name-based symbol matching
+EDGE_CASES: */ in descriptions→sanitized|empty files→skip|parse errors→fallback to beautified|unmapped lines→null
+h(a)|parseCtxSignatures — internal helper
+y(a)|parseCtxParams — internal helper
+g(a)|extractReturnType — internal helper
+w(a,b,c,d,e)|sanitizeJSDocText — internal helper

package/src/compact/expand.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/expand.ctx
+// @ctx expand.ctx
 import{parseCtxParams as h,buildJSDocBlock as g}from"./jsdoc-builder.js";import{readCtxFile as $}from"./ctx-resolver.js";import{walkJSFiles}from"../core/file-walker.js";import{readFileSync as t,writeFileSync as e,mkdirSync as n,existsSync as s}from"fs";import{join as i,basename as a,extname as c,dirname as p,relative as l}from"path";import{minify as m}from"../../vendor/terser.mjs";import{parse as d}from"../../vendor/acorn.mjs";import{simple as f,ancestor as u}from"../../vendor/walk.mjs";
 
 function y(t){if(!t)return null;const e=t.match(/^→([A-Z][\w<>\[\]|]*)/);return e?e[1]:null}function w(t,e,n,s,o){const r=new Map;let i=[];for(const t of e.body)if("ImportDeclaration"===t.type)for(const e of t.specifiers)if("ImportSpecifier"===e.type&&e.imported.name!==e.local.name)r.set(e.local.name,e.imported.name),i.push({s:e.start,e:e.end,n:e.imported.name,k:e.local.name});else if("ImportDefaultSpecifier"===e.type){const n=t.source.value.replace(/^node:/,"").split("/").pop().replace(/\.\\w+$/,"").replace(/-(\w)/g,(t,e)=>e.toUpperCase());n&&/^[a-zA-Z_$][\w$]*$/.test(n)&&n!==e.local.name&&(r.set(e.local.name,n),i.push({s:e.start,e:e.end,n:n,k:e.local.name}))}else if("ImportNamespaceSpecifier"===e.type&&e.local.name.length<=2){const n=t.source.value.replace(/^node:/,"").split("/").pop().replace(/\.\\w+$/,"").replace(/-(\w)/g,(t,e)=>e.toUpperCase());n&&/^[a-zA-Z_$][\w$]*$/.test(n)&&n!==e.local.name&&(r.set(e.local.name,n),i.push({s:e.start,e:e.end,n:"* as "+n,k:e.local.name}))}for(const[t,e]of s)r.set(t,e);if(o.has("__top__"))for(const[t,e]of o.get("__top__"))r.set(t,e);const a=new Set(r.values());for(const[t]of[...r])a.has(t)&&r.delete(t);{const _u=new Set;for(const[k,v]of[...r])_u.has(v)?(r.delete(k),i=i.filter(x=>x.k!==k)):_u.add(v)}const c=[],p=[],l=[];const m=t=>{const e=t.params.map(t=>"Identifier"===t.type?t.name:"AssignmentPattern"===t.type&&"Identifier"===t.left?.type?t.left.name:"RestElement"===t.type&&"Identifier"===t.argument?.type?t.argument.name:null).filter(Boolean),s=new Map;if(t.id?.name){const r=n.get(t.id.name);if(r?.params)for(let t=0;t<Math.min(e.length,r.params.length);t++)e[t]!==r.params[t].name&&s.set(e[t],r.params[t].name);const i=o.get(t.id.name);if(i)for(const[t,e]of i)s.has(t)||s.set(t,e);if(s.size>0)for(const e of t.params){const t="Identifier"===e.type?e:"AssignmentPattern"===e.type&&"Identifier"===e.left?.type?e.left:null;t&&s.has(t.name)&&p.push({s:t.start,e:t.end,n:s.get(t.name)})}}const r=function(t){const e=new Set;return f(t,{VariableDeclarator(t){t.id&&"Identifier"===t.id.type&&e.add(t.id.name)},CatchClause(t){t.param&&"Identifier"===t.param.type&&e.add(t.param.name)}}),e}(t.body);for(const t of e)r.add(t);const _tgts=Array.from(s.values());for(const t of _tgts){if(r.has(t)&&!s.has(t)){let n=t+"_";while(r.has(n)||_tgts.includes(n))n+="_";s.set(t,n)}}const i=t.id?.name&&o.get(t.id.name);for(const e of function(t){const e=[];return f(t,{VariableDeclarator(t){t.id&&"Identifier"===t.id.type&&e.push(t.id)},CatchClause(t){t.param&&"Identifier"===t.param.type&&e.push(t.param)}}),e}(t.body)){const t=s.has(e.name)?s.get(e.name):i?.get(e.name);t&&l.push({s:e.start,e:e.end,n:t})}c.push({s:t.params.length>0?t.params[0].start:t.body.start,e:t.body.end,p:r,r:s})};f(e,{FunctionDeclaration:m,FunctionExpression:m,ArrowFunctionExpression:m});for(const t of e.body)if("VariableDeclaration"===t.type)for(const e of t.declarations)e.id&&"Identifier"===e.id.type&&r.has(e.id.name)&&l.push({s:e.id.start,e:e.id.end,n:r.get(e.id.name)});const d=[...i,...p,...l];u(e,{Identifier(t,e,n){const s=n[n.length-2];if("MemberExpression"===s?.type&&s.property===t&&!s.computed)return;if("Property"===s?.type&&s.key===t&&!s.computed&&s.value!==t)return;if("ExportSpecifier"===s?.type)return;const o=t.name;const scopes=c.filter(e=>t.start>=e.s&&t.end<=e.e).sort((a,b)=>(a.e-a.s)-(b.e-b.s));let mapped=!1,isLocal=!1;for(const e of scopes){if(e.r.has(o)){d.push({s:t.start,e:t.end,n:e.r.get(o)});mapped=!0;break}if(e.p.has(o)){isLocal=!0;break}}if(!mapped&&!isLocal&&r.has(o)){d.push({s:t.start,e:t.end,n:r.get(o)})}}});d.sort((t,e)=>e.s-t.s);let h=t;for(const t of d)h=h.slice(0,t.s)+t.n+h.slice(t.e);return h}

package/src/compact/framework-references.ctx

@@ -0,0 +1,7 @@
+--- src/compact/framework-references.js ---
+@sig 05360f4a
+fetchReference(t)→o,u.get,Date.now,AbortSignal.timeout,fetch,e.text|fetch remote markdown reference with caching and local fallback
+listAvailable()→Object.keys,r,t,r.endsWith,a,e.add|list available framework references from cache and local dir
+export getFrameworkReference(options:Object=)→listAvailable,t.includes,fetchReference,r.split,i,o.includes|get full reference docs for a framework or auto-detect
+PATTERNS: in-memory caching with TTL|fetch with AbortSignal timeout
+EDGE_CASES: gracefully handles fetch timeouts and write failures

package/src/compact/framework-references.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/framework-references.ctx
+// @ctx framework-references.ctx
 import{readFileSync as e,readdirSync as t,existsSync as r,writeFileSync as n}from"fs";import{join as o,basename as a,dirname as s}from"path";import{fileURLToPath as c}from"url";import{detectProjectRuleSets as i}from"../analysis/custom-rules.js";
 const f=s(c(import.meta.url)),m=o(f,"..","..","docs","references"),l={"symbiote-3x":"https://raw.githubusercontent.com/symbiotejs/symbiote.js/main/AI_REFERENCE.md"},u=new Map;async function fetchReference(t){const a=l[t],s=o(m,`${t}.md`),c=u.get(t);if(c&&Date.now()-c.fetchedAt<36e5)return{content:c.content,source:"cache"};if(a)try{const e=await fetch(a,{signal:AbortSignal.timeout(5e3)});if(e.ok){const r=await e.text();u.set(t,{content:r,fetchedAt:Date.now()});try{n(s,r,"utf-8")}catch(e){}return{content:r,source:`github (${a})`}}}catch(e){}if(r(s)){const r=e(s,"utf-8");return u.set(t,{content:r,fetchedAt:Date.now()}),{content:r,source:"local"}}return{content:"",source:"not_found"}}const d={"symbiote-3x":"symbiote-3x","symbiote-2x":"symbiote-3x"};function listAvailable(){const e=new Set(Object.keys(l));if(r(m))for(const r of t(m))r.endsWith(".md")&&e.add(a(r,".md"));return[...e]}
 export async function getFrameworkReference(e={}){const t=listAvailable();if(e.framework){if(!t.includes(e.framework))return{error:`Framework reference '${e.framework}' not found`,available:t};const{content:r,source:n}=await fetchReference(e.framework);return r?{framework:e.framework,source:n,lines:r.split("\n").length,content:r}:{error:`Failed to load reference '${e.framework}'`,available:t}}if(e.path){const{detected:r,reasons:n}=i(e.path),o=[];for(const e of r){const r=d[e];r&&t.includes(r)&&!o.includes(r)&&o.push(r)}if(0===o.length)return{error:"No framework references found for this project",detected:r,reasons:n,available:t};

package/src/compact/instructions.ctx

@@ -0,0 +1,6 @@
+--- src/compact/instructions.js ---
+@sig 7e055438
+export getInstructions()|return constant string containing AI agent guidelines
+PATTERNS: constant export
+EDGE_CASES: none
+export AGENT_INSTRUCTIONS|compact mode agent instructions text

package/src/compact/instructions.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/instructions.ctx
+// @ctx instructions.ctx
 import{readFileSync}from"fs";import{join,dirname}from"path";import{fileURLToPath}from"url";
 const __dir=dirname(fileURLToPath(import.meta.url));
 const _mdPath=join(__dir,"..","..","docs","AGENT_INSTRUCTIONS.md");

package/src/compact/jsdoc-builder.ctx

@@ -0,0 +1,4 @@
+export parseCtxParams(paramStr:string)|parse ctx param string into structured array|supports name:type, optional=, rest...
+export buildJSDocBlock(entry:Object)|generate JSDoc from parsed entry|skips @param for all-minified helpers
+export buildJSDocFromRaw(entry:Object)|generate JSDoc from raw ctx entry|params as unparsed string
+sanitize(text:string)|escape */ in JSDoc text

package/src/compact/jsdoc-builder.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/jsdoc-builder.ctx
+// @ctx jsdoc-builder.ctx
 export function parseCtxParams(t){return t&&t.trim()?t.split(",").map(t=>{const e=t.trim();if(!e)return null;const n=e.match(/^(\w+)(\?)?(?::(\w[\w<>\[\]|.]*))?(\=)?$/);if(n)return{name:n[1],type:n[3]||null,optional:!(!n[2]&&!n[4])};const s=e.match(/^(\w+)(=)?$/);return s?{name:s[1],type:null,optional:!!s[2]}:"..."===e?{name:"args",type:null,rest:!0}:{name:e.replace(/[=?:].*/g,""),type:null}}).filter(Boolean):[]}
 function sanitize(t){return t.replace(/\*\//g,"*\\/")}
 export function buildJSDocBlock(t){const e=["/**"];if(t.description&&"{DESCRIBE}"!==t.description&&e.push(` * ${sanitize(t.description)}`),t.params&&t.params.length>0&&!t.params.every(p=>!p.type&&p.name.length<=1))for(const n of t.params){const t=n.type||"*",s=n.optional?`[${n.name}]`:n.name;e.push(` * @param {${t}} ${s}`)}return t.returnType&&e.push(` * @returns {${t.returnType}}`),e.push(" */"),e.join("\n")}

package/src/compact/mode-config.ctx

@@ -0,0 +1,8 @@
+--- src/compact/mode-config.js ---
+@sig 84ca6758
+export getConfig(rootPath:string)→i,r,e,JSON.parse|read .context/config.json, merge with defaults
+export setConfig(rootPath:string,config:Object)→i,c,r,o,getConfig,JSON.stringify|save mode config|validates mode 1-4
+export getModeDescription(mode:number)|return human-readable desc for mode 1-4
+export getModeWorkflow(mode:number)|return read/edit/docs/validate workflow per mode
+PATTERNS: config merge with DEFAULTS|.context/config.json storage
+EDGE_CASES: missing config→defaults|invalid mode→throw error|missing dir→mkdirSync

package/src/compact/mode-config.js

@@ -1,4 +1,4 @@
-// @ctx .context/src/compact/mode-config.ctx
+// @ctx mode-config.ctx
 import{readFileSync as e,writeFileSync as t,existsSync as r,mkdirSync as o}from"fs";
 import{join as i,dirname as c}from"path";
 const n=".context/config.json",a={mode:2,beautify:!0,autoValidate:!1,stripJSDoc:!1};

package/src/compact/split-declarations.ctx

@@ -0,0 +1,6 @@
+--- src/compact/split-declarations.js ---
+@sig 66570947
+export splitDeclarations(code:string)→t,n.push,n.sort,r.slice,o.push,o.filter|split minified blob into one-declaration-per-line using AST
+export isSingleLineBlob(code:string)→r.split,t.startsWith,t|check if code has >3 declarations on ≤2 lines
+PATTERNS: Acorn AST node.start boundaries for splitting
+EDGE_CASES: (internal utility)