@sagentlab/navarch-runtime 0.1.39 → 0.1.40

package/README.md

@@ -716,3 +716,26 @@ not match, making it a clean, zero-touch way to keep this package fully
 isolated. Vite/Vitest's default esbuild transform filter also excludes
 `.cts` by default — `vitest.config.cts` overrides it (`esbuild.include`) so
 tests are actually type-stripped and run.
+
+## Inspect code dependencies
+
+`navarch-runtime code-graph --query saveInvoice --mode impact --commit HEAD`
+returns JSON with the indexed commit, checkout HEAD, dirty-worktree warning,
+source paths and line numbers, and bounded dependency edges. Modes are `search`,
+`callers`, `callees`, and `impact`; impact accepts `--depth 1` through `5`.
+Use an exact node ID to disambiguate duplicate symbol names. A file query includes
+its functions and file import dependencies. `--repo` defaults to the current
+working directory. The CLI works without a Navarch login or network access.
+
+This first implementation analyzes committed JavaScript and TypeScript with the
+TypeScript compiler. It resolves static imports and named functions/methods,
+including imported aliases. It does not execute repository code, follow symlinks,
+load tsconfig plugins, or upload source. Root tsconfig path aliases are supported;
+extended configs, dynamic dispatch, external dependencies and other languages
+are not fully resolved. Warnings report omissions. No graph is an assurance that
+a change has no other effects: inspect the actual diff and run relevant tests.
+
+Each invocation rebuilds from Git blobs at the requested commit, avoiding stale
+persistent indexes. Bounds are 2,000 files, 10 MB total source, 500 KB per file,
+100 returned nodes and 300 edges. A later persistent index can optimize large
+repositories without changing the query format.

package/dist/cli.cjs

@@ -307,6 +307,7 @@ Usage:
   navarch-runtime start [--config-dir <path>] [--agent claude-code|codex|gemini|opencode]
   navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini|opencode]
   navarch-runtime doctor [--config-dir <path>]
+  navarch-runtime code-graph --query <symbol-or-file> [--mode search|callers|callees|impact] [--commit HEAD] [--depth 1..5] [--repo <path>]
 
 Use a different --config-dir (or NAVARCH_CONFIG_DIR) for every agent instance.
 Other configuration is via NAVARCH_* environment variables; see runtime/README.md.
@@ -328,6 +329,11 @@ async function main(argv = process.argv.slice(2)) {
             case "supervise":
                 await superviseCommand(flags);
                 break;
+            case "code-graph": {
+                const { codeGraphCommand } = await import("./code-graph.cjs");
+                console.log(JSON.stringify(codeGraphCommand(flags), null, 2));
+                break;
+            }
             case "doctor":
                 await doctorCommand(flags);
                 break;

package/dist/code-graph.cjs

@@ -0,0 +1,198 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCodeSnapshot = readCodeSnapshot;
+exports.buildCodeGraph = buildCodeGraph;
+exports.queryCodeGraph = queryCodeGraph;
+exports.codeGraphCommand = codeGraphCommand;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const typescript_1 = __importDefault(require("typescript"));
+const ROOT = "/navarch-repo/";
+const MAX_BYTES = 10_000_000;
+const MAX_FILES = 2_000;
+/** Reads committed blobs only. Never follows worktree symlinks, runs project code, or loads plugins. */
+function readCodeSnapshot(cwd, ref = "HEAD") {
+    const git = (args, input) => (0, node_child_process_1.execFileSync)("git", args, {
+        cwd, input, encoding: "utf8", maxBuffer: 16_000_000, timeout: 15_000,
+    });
+    const commit = git(["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]).trim();
+    const head = git(["rev-parse", "HEAD"]).trim();
+    const dirty = Boolean(git(["status", "--porcelain", "--untracked-files=no"]).trim());
+    const warnings = [];
+    if (dirty)
+        warnings.push("Tracked worktree edits are not indexed; this graph describes committed code.");
+    if (commit !== head)
+        warnings.push("Indexed commit differs from checkout HEAD.");
+    const files = [];
+    let bytes = 0;
+    for (const entry of git(["ls-tree", "--full-tree", "-rlz", commit]).split("\0")) {
+        const match = /^(100644|100755) blob ([a-f0-9]+) +([0-9]+)\t(.+)$/s.exec(entry);
+        if (!match)
+            continue;
+        const file = match[4];
+        if ((!/\.(?:[cm]?[jt]sx?)$/.test(file) && file !== "tsconfig.json") ||
+            /(^|\/)(node_modules|dist|build|vendor|\.next)\//.test(file))
+            continue;
+        const size = Number(match[3]);
+        if (/[\r\n]/.test(file) || size > 500_000 || files.length >= MAX_FILES || bytes + size > MAX_BYTES) {
+            warnings.push(`Skipped source: ${file}`);
+            continue;
+        }
+        files.push({ file, sha: match[2], size });
+        bytes += size;
+    }
+    const contents = {};
+    if (files.length) {
+        // Object IDs, rather than paths, form the batch protocol input.
+        const output = (0, node_child_process_1.execFileSync)("git", ["cat-file", "--batch"], {
+            cwd, input: files.map((f) => f.sha).join("\n") + "\n", maxBuffer: 16_000_000, timeout: 15_000,
+        });
+        let offset = 0;
+        for (const file of files) {
+            const end = output.indexOf(10, offset);
+            if (end < 0 || output.subarray(offset, end).toString() !== `${file.sha} blob ${file.size}`) {
+                throw new Error("Invalid git object batch");
+            }
+            offset = end + 1;
+            contents[file.file] = output.subarray(offset, offset + file.size).toString("utf8");
+            offset += file.size + 1;
+        }
+    }
+    return { commit, head, dirty, contents, warnings };
+}
+function buildCodeGraph(snapshot) {
+    const warnings = [...snapshot.warnings];
+    const sources = new Map(Object.entries(snapshot.contents).map(([file, text]) => [ROOT + file, text]));
+    const config = sources.get(ROOT + "tsconfig.json");
+    const raw = config ? typescript_1.default.parseConfigFileTextToJson("tsconfig.json", config) : { config: {} };
+    if (raw.error)
+        warnings.push("Could not parse tsconfig.json; using default module resolution.");
+    if (raw.config?.extends)
+        warnings.push("Inherited tsconfig options are not loaded; unresolved aliases may be omitted.");
+    const converted = typescript_1.default.convertCompilerOptionsFromJson(raw.config?.compilerOptions ?? {}, ROOT);
+    const options = { ...converted.options, allowJs: true, noLib: true, noEmit: true };
+    const canonical = (file) => node_path_1.default.posix.normalize(file);
+    const host = {
+        fileExists: (file) => sources.has(canonical(file)),
+        readFile: (file) => sources.get(canonical(file)),
+        getSourceFile: (file, languageVersion) => {
+            const text = sources.get(canonical(file));
+            return text === undefined ? undefined : typescript_1.default.createSourceFile(file, text, languageVersion, true);
+        },
+        getDefaultLibFileName: () => "", writeFile: () => { }, getCurrentDirectory: () => ROOT,
+        getDirectories: () => [], directoryExists: (dir) => [...sources.keys()].some((f) => f.startsWith(dir.replace(/\/$/, "") + "/")),
+        getCanonicalFileName: canonical, useCaseSensitiveFileNames: () => true, getNewLine: () => "\n",
+    };
+    const program = typescript_1.default.createProgram([...sources.keys()].filter((f) => f !== ROOT + "tsconfig.json"), options, host);
+    const checker = program.getTypeChecker();
+    const nodes = [];
+    const declarations = new Map();
+    const ownedFunctions = new Map();
+    const sourceFiles = program.getSourceFiles().filter((f) => sources.has(f.fileName));
+    for (const source of sourceFiles) {
+        const file = source.fileName.slice(ROOT.length);
+        const fileId = `file:${file}`;
+        nodes.push({ id: fileId, name: file, file, line: 1, kind: "file" });
+        declarations.set(source, fileId);
+        const collect = (node) => {
+            let name;
+            let body;
+            if (typescript_1.default.isFunctionDeclaration(node) || typescript_1.default.isMethodDeclaration(node) || typescript_1.default.isGetAccessorDeclaration(node) || typescript_1.default.isSetAccessorDeclaration(node)) {
+                name = node.name;
+                body = node.body;
+            }
+            else if (typescript_1.default.isVariableDeclaration(node) && node.initializer &&
+                (typescript_1.default.isArrowFunction(node.initializer) || typescript_1.default.isFunctionExpression(node.initializer))) {
+                name = node.name;
+                body = node.initializer;
+            }
+            if (name && body) {
+                const position = source.getLineAndCharacterOfPosition(name.getStart(source));
+                const line = position.line + 1;
+                const id = `${file}:${line}:${position.character + 1}:${name.getText(source)}`;
+                nodes.push({ id, name: name.getText(source), file, line, kind: "function" });
+                declarations.set(node, id);
+                ownedFunctions.set(body, id);
+            }
+            typescript_1.default.forEachChild(node, collect);
+        };
+        collect(source);
+    }
+    const edges = [];
+    let unresolved = 0;
+    const target = (node) => {
+        let symbol = checker.getSymbolAtLocation(node);
+        if (symbol && symbol.flags & typescript_1.default.SymbolFlags.Alias)
+            symbol = checker.getAliasedSymbol(symbol);
+        const targets = new Set(symbol?.declarations?.map((d) => declarations.get(d)).filter((id) => Boolean(id)));
+        return targets.size === 1 ? [...targets][0] : undefined;
+    };
+    for (const source of sourceFiles) {
+        const visit = (node, parent) => {
+            const owner = ownedFunctions.get(node) ?? parent;
+            if (typescript_1.default.isCallExpression(node)) {
+                const expression = typescript_1.default.isPropertyAccessExpression(node.expression) ? node.expression.name : node.expression;
+                const to = target(expression);
+                if (to)
+                    edges.push({ from: owner, to, kind: "call" });
+                else
+                    unresolved++;
+            }
+            if (typescript_1.default.isImportDeclaration(node) || (typescript_1.default.isExportDeclaration(node) && node.moduleSpecifier)) {
+                const to = node.moduleSpecifier ? target(node.moduleSpecifier) : undefined;
+                if (to)
+                    edges.push({ from: declarations.get(source), to, kind: "import" });
+            }
+            typescript_1.default.forEachChild(node, (child) => visit(child, owner));
+        };
+        visit(source, declarations.get(source));
+    }
+    warnings.push(`Static JS/TS analysis only; ${unresolved} external or unresolved calls omitted. Dynamic dispatch and runtime dependencies may be missing.`);
+    return { commit: snapshot.commit, head: snapshot.head, dirty: snapshot.dirty, nodes,
+        edges: [...new Map(edges.map((e) => [`${e.from}\0${e.to}\0${e.kind}`, e])).values()], warnings };
+}
+function queryCodeGraph(graph, query, mode = "search", depth = 3) {
+    if (!query.trim() || query.length > 500)
+        throw new Error("Provide a non-empty --query of at most 500 characters");
+    if (!["search", "callers", "callees", "impact"].includes(mode))
+        throw new Error("--mode must be search, callers, callees, or impact");
+    if (!Number.isInteger(depth) || depth < 1 || depth > 5)
+        throw new Error("--depth must be 1 through 5");
+    const exact = graph.nodes.filter((n) => n.id === query || n.name === query || n.file === query);
+    const matches = exact.length ? exact : graph.nodes.filter((n) => n.name.toLowerCase().includes(query.toLowerCase()));
+    const selected = new Set(matches.slice(0, 100).map((n) => n.id));
+    const paths = [];
+    let truncated = matches.length > 100;
+    if (mode !== "search") {
+        for (let hop = 0; hop < (mode === "impact" ? depth : 1); hop++) {
+            const frontier = new Set(selected);
+            for (const edge of graph.edges) {
+                const from = mode === "callees" ? edge.from : edge.to;
+                const to = mode === "callees" ? edge.to : edge.from;
+                if (!frontier.has(from))
+                    continue;
+                if (!selected.has(to) && selected.size >= 100) {
+                    truncated = true;
+                    continue;
+                }
+                if (paths.length >= 300) {
+                    truncated = true;
+                    break;
+                }
+                selected.add(to);
+                if (!paths.some((p) => p.from === edge.from && p.to === edge.to && p.kind === edge.kind))
+                    paths.push(edge);
+            }
+        }
+    }
+    return { commit: graph.commit, checkout_head: graph.head, dirty: graph.dirty, mode,
+        nodes: graph.nodes.filter((n) => selected.has(n.id)), edges: paths,
+        truncated, warnings: graph.warnings };
+}
+function codeGraphCommand(flags) {
+    const graph = buildCodeGraph(readCodeSnapshot(flags.repo ?? process.cwd(), flags.commit ?? "HEAD"));
+    return queryCodeGraph(graph, flags.query ?? "", flags.mode ?? "search", Number(flags.depth ?? 3));
+}

package/dist/prompt.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderPrompt = renderPrompt;
 exports.renderGuidanceCorrectionPrompt = renderGuidanceCorrectionPrompt;
+const CODE_GRAPH_GUIDANCE = "For JS/TS dependency inspection, the runtime provides `navarch-runtime code-graph --query <symbol-or-file> --mode search|callers|callees|impact --commit HEAD`. If the runtime is not on PATH, use its installed entry point; do not install another copy mid-task. Results describe committed source and include commit/freshness warnings; inspect current files for uncommitted changes and unresolved dependencies.";
 /**
  * Renders the four-layer context bundle (project-plan.md §3.8: steering docs,
  * task itself, task-type playbook, depends_on reports) into the single prompt
@@ -14,7 +15,7 @@ function renderPrompt(task, bundle) {
         const repositoryContext = bundle.repository
             ? `Repository: ${bundle.repository.full_name} (${bundle.repository.url})\nLocal checkout: this session's isolated git worktree (current working directory).`
             : null;
-        return [repositoryContext, bundle.task_context.trim(), bundle.retry_context?.trim()]
+        return [repositoryContext, bundle.task_context.trim(), CODE_GRAPH_GUIDANCE, bundle.retry_context?.trim()]
             .filter((section) => Boolean(section))
             .join("\n\n") + "\n";
     }
@@ -42,6 +43,7 @@ function renderPrompt(task, bundle) {
     }
     sections.push("## Playbook");
     sections.push(bundle.playbook);
+    sections.push(CODE_GRAPH_GUIDANCE);
     return sections.join("\n\n");
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, Gemini, or OpenCode.",
   "type": "commonjs",
   "license": "MIT",
@@ -47,7 +47,9 @@
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
-    "typescript": "^5.7.2",
     "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "typescript": "^5.7.2"
   }
 }