Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat(context): add files linked to the target only by text
KageBinary16d73b8d8fcb
diff --git a/ix-cli/src/cli/__tests__/related-files.test.ts b/ix-cli/src/cli/__tests__/related-files.test.tsindex 80de6108..d19c3f92 100644--- a/ix-cli/src/cli/__tests__/related-files.test.ts+++ b/ix-cli/src/cli/__tests__/related-files.test.ts@@ -266,6 +266,17 @@ describe("related files in a bundle", () => {expect(lines.join("\n")).toContain("src/rank.ts");});+ it("says why a textual link is there, instead of what it was reached through", () => {+ const languages: RelatedRef = {+ id: "file:core-ingestion/src/languages.ts", name: "languages.ts", kind: "file",+ path: "core-ingestion/src/languages.ts", score: 0.6, reason: "named in supported-extensions.ts",+ via: [], named: "named in supported-extensions.ts",+ };+ const row = build([rank, languages]).evidence.find((e) => e.source === "facts.related")!;+ expect(row.title).toBe("related files: src/rank.ts, core-ingestion/src/languages.ts");+ expect(row.reason).toContain("languages.ts (named in supported-extensions.ts)");+ });+it("adds no row when nothing was found", () => {expect(build([]).evidence.some((e) => e.source === "facts.related")).toBe(false);});diff --git a/ix-cli/src/cli/__tests__/text-references.test.ts b/ix-cli/src/cli/__tests__/text-references.test.tsnew file mode 100644index 00000000..852e0998--- /dev/null+++ b/ix-cli/src/cli/__tests__/text-references.test.ts@@ -0,0 +1,158 @@+// Copyright 2026 Ix Infrastructure Inc.++import { execFileSync } from "node:child_process";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";++import { afterEach, describe, expect, it } from "vitest";++import {+ collectTextReferences,+ gitRepoAccess,+ resolveToken,+ type RepoAccess,+} from "../explain/text-references.js";++/**+ * Links between files that exist only in text: a build path in a string, a+ * file named in a comment, a test that reads a file by path. Each case below+ * is one the ix-bench bundles could not reach through the graph.+ */++function memoryRepo(files: Record<string, string>): RepoAccess {+ return {+ files: () => Object.keys(files),+ read: (path) => files[path],+ grep: (needle) =>+ Object.entries(files).flatMap(([path, text]) =>+ text.split("\n").filter((line) => line.includes(needle)).map((line) => ({ path, line }))),+ };+}++const index = (files: string[]) => {+ const byBasename = new Map<string, string[]>();+ for (const f of files) {+ const base = f.split("/").pop()!;+ byBasename.set(base, [...(byBasename.get(base) ?? []), f]);+ }+ return { tracked: new Set(files), byBasename };+};++describe("resolveToken", () => {+ const files = [+ "core-ingestion/src/languages.ts",+ "core-ingestion/src/index.ts",+ "ix-cli/src/cli/supported-extensions.ts",+ "ix-cli/src/cli/commands/ingestion-loader.ts",+ "ix-cli/src/cli/index.ts",+ ];+ const { tracked, byBasename } = index(files);++ it("maps a build path back to its source", () => {+ expect(resolveToken("../../../../core-ingestion/dist/languages.js",+ "ix-cli/src/cli/commands/ingestion-loader.ts", tracked, byBasename))+ .toBe("core-ingestion/src/languages.ts");+ });++ it("resolves a relative path from the file it appears in", () => {+ expect(resolveToken("../../../ix-cli/src/cli/supported-extensions.ts",+ "core-ingestion/src/__tests__/extension-parity.test.ts", tracked, byBasename))+ .toBe("ix-cli/src/cli/supported-extensions.ts");+ });++ it("resolves a unique basename, and refuses an ambiguous one", () => {+ expect(resolveToken("languages.ts", "x/y.ts", tracked, byBasename)).toBe("core-ingestion/src/languages.ts");+ expect(resolveToken("index.ts", "x/y.ts", tracked, byBasename)).toBeUndefined();+ });++ it("resolves a unique path suffix", () => {+ expect(resolveToken("cli/supported-extensions.ts", "x/y.ts", tracked, byBasename))+ .toBe("ix-cli/src/cli/supported-extensions.ts");+ });++ it("does not resolve a path that climbs out of the repository", () => {+ expect(resolveToken("../../../../languages.ts", "a/b.ts", tracked, byBasename)).toBeUndefined();+ });+});++describe("collectTextReferences", () => {+ it("finds a file named in a comment of an imported file", () => {+ const repo = memoryRepo({+ "ix-cli/src/cli/commands/watch.ts": `import { SUPPORTED_EXTENSIONS } from "../supported-extensions.js";\n`,+ "ix-cli/src/cli/supported-extensions.ts":+ "// This MUST stay in sync with core-ingestion's EXT_MAP (languages.ts).\nexport const SUPPORTED_EXTENSIONS = new Set();\n",+ "core-ingestion/src/languages.ts": "export const EXT_MAP = {};\n",+ });+ const refs = collectTextReferences(repo, [+ { path: "ix-cli/src/cli/commands/watch.ts", role: "target" },+ { path: "ix-cli/src/cli/supported-extensions.ts", role: "import" },+ ], new Set());+ expect(refs).toEqual([+ { path: "core-ingestion/src/languages.ts", score: 0.6, reason: "named in supported-extensions.ts" },+ ]);+ });++ it("finds a test that reads a file by path, but not the files that import it", () => {+ const repo = memoryRepo({+ "ix-cli/src/cli/supported-extensions.ts": "export const SUPPORTED_EXTENSIONS = new Set();\n",+ "core-ingestion/src/__tests__/extension-parity.test.ts":+ "const walked = read('../../../ix-cli/src/cli/supported-extensions.ts');\n",+ "ix-cli/src/cli/commands/watch.ts": `import { SUPPORTED_EXTENSIONS } from "../supported-extensions.js";\n`,+ });+ const refs = collectTextReferences(repo, [+ { path: "ix-cli/src/cli/supported-extensions.ts", role: "target" },+ ], new Set());+ expect(refs.map((r) => r.path)).toEqual(["core-ingestion/src/__tests__/extension-parity.test.ts"]);+ expect(refs[0].reason).toBe("names supported-extensions.ts in its text");+ });++ it("reads a dynamic import's argument, which the graph often cannot resolve", () => {+ const repo = memoryRepo({+ "a/loader.ts": `const m = await import("../b/dist/parser.js");\n`,+ "b/src/parser.ts": "export {};\n",+ });+ expect(collectTextReferences(repo, [{ path: "a/loader.ts", role: "target" }], new Set())+ .map((r) => r.path)).toEqual(["b/src/parser.ts"]);+ });++ it("ignores a name everyone mentions, prose, and files the bundle already has", () => {+ const files: Record<string, string> = {+ "src/target.ts": "// see helper.ts and known.ts\n",+ "src/helper.ts": "export {};\n",+ "src/known.ts": "export {};\n",+ "README.md": "target.ts is the entry point\n",+ };+ for (let i = 0; i < 8; i++) files[`src/user${i}.ts`] = "// calls into target.ts\n";+ const refs = collectTextReferences(memoryRepo(files),+ [{ path: "src/target.ts", role: "target" }], new Set(["src/known.ts"]));+ expect(refs.map((r) => r.path)).toEqual(["src/helper.ts"]);+ });+});++describe("gitRepoAccess", () => {+ let dir: string | undefined;+ afterEach(() => {+ if (dir) rmSync(dir, { recursive: true, force: true });+ dir = undefined;+ });++ it("lists, reads and greps a real checkout, and declines a directory that is not one", () => {+ dir = mkdtempSync(join(tmpdir(), "ix-text-refs-"));+ const write = (path: string, text: string) => {+ mkdirSync(dirname(join(dir!, path)), { recursive: true });+ writeFileSync(join(dir!, path), text);+ };+ expect(gitRepoAccess(dir)).toBeUndefined();++ execFileSync("git", ["init", "-q"], { cwd: dir });+ write("src/a.ts", "// see b.ts\n");+ write("src/b.ts", "export {};\n");+ execFileSync("git", ["add", "."], { cwd: dir });+ const repo = gitRepoAccess(dir)!;+ expect(repo.files().sort()).toEqual(["src/a.ts", "src/b.ts"]);+ expect(repo.read("src/a.ts")).toContain("b.ts");+ expect(repo.grep("b.ts")).toEqual([{ path: "src/a.ts", line: "// see b.ts" }]);+ expect(repo.grep("nothing-matches")).toEqual([]);+ });+});diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 8a21965f..e78ad839 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -18,15 +18,16 @@ import type {IntentReport,StructuredContext,} from "../../client/types.js";-import { getEndpoint } from "../config.js";+import { getEndpoint, resolveWorkspaceRoot } from "../config.js";import { collectFacts, type ContextFacts, type EntityLocation } from "../explain/facts.js";-import { collectRelatedFiles, type RelatedRef } from "../explain/related-files.js";+import { collectRelatedFiles, MAX_RELATED, type RelatedRef } from "../explain/related-files.js";+import { collectTextReferences, gitRepoAccess, type TextSource } from "../explain/text-references.js";import { llmLine, llmShortId, printLlmLines } from "../llm.js";import { parseBudgetOption, parsePickOption, parseRevisionOption } from "../options.js";-import { resolveFileOrReport } from "../resolve.js";+import { activeReadScope, resolveFileOrReport } from "../resolve.js";import { createStaleProbe, hasCompletedSourceGraphBaseline } from "../stale.js";import { renderNote, renderSection, renderWarning, renderWarningErr, reportFailure } from "../ui.js";-import { printJson } from "../format.js";+import { printJson, relativePath } from "../format.js";/** The `--max-*` knobs that bound a bundle. */interface BudgetSnapshot {@@ -1456,10 +1457,62 @@ async function collectContextFacts(resolved: { id: string; name: string; kind: string },): Promise<ContextFacts> {const facts = await collectFacts(client, resolved.id, resolved.name, resolved.kind, "context");- const relatedRefs = await collectRelatedFiles(client, resolved, facts).catch(() => []);+ const graphRefs = await collectRelatedFiles(client, resolved, facts).catch(() => []);+ const textRefs = await collectTextRelated(client, facts, graphRefs).catch(() => []);+ // Added to the graph's files, not ranked against them. Put first and sharing+ // the eight slots, they displaced graph finds the benchmark needed+ // (`main.ts` for `mcp/runner.ts`) with mentions that led nowhere.+ const relatedRefs = [...graphRefs.slice(0, MAX_RELATED), ...textRefs];return relatedRefs.length > 0 ? { ...facts, relatedRefs } : facts;}+/** Imported files whose text is read for names, after the target's own. */+const TEXT_SOURCE_IMPORTS = 8;++/**+ * Files linked to the target by text rather than by any graph edge: a path in+ * a string (`"../../../../core-ingestion/dist/languages.js"`), a file named+ * in a comment, a test that reads a file by path. Read from the working tree,+ * so skipped outside a git checkout. See `collectTextReferences`.+ */+async function collectTextRelated(+ client: IxClient,+ facts: ContextFacts,+ graphRefs: RelatedRef[],+): Promise<RelatedRef[]> {+ if (!facts.path) return [];+ const repo = gitRepoAccess(resolveWorkspaceRoot());+ if (!repo) return [];+ const sources: TextSource[] = [+ { path: facts.path, role: "target" },+ ...(facts.importRefs ?? [])+ .filter((ref) => ref.kind === "file" && ref.path)+ .slice(0, TEXT_SOURCE_IMPORTS)+ .map((ref) => ({ path: ref.path!, role: "import" as const })),+ ];+ const known = new Set<string>();+ for (const ref of [+ ...(facts.importRefs ?? []), ...(facts.calleeRefs ?? []), ...(facts.topCallerRefs ?? []),+ ...(facts.topDependentRefs ?? []), ...(facts.neighbourRefs ?? []), ...graphRefs,+ ]) {+ if (ref.path) known.add(ref.path);+ }+ const found = collectTextReferences(repo, sources, known);+ const scope = activeReadScope();+ return Promise.all(found.map(async (ref): Promise<RelatedRef> => {+ const name = ref.path.split("/").pop()!;+ // The file's node, for an entity id the rest of the bundle can refer to.+ // Scoped: a backend holding two checkouts of one repository has two.+ const nodes = await client.search(name, { kind: "file", nameOnly: true, limit: 10, ...scope })+ .catch(() => []);+ const node = nodes.find((n) => relativePath(n.provenance?.sourceUri) === ref.path);+ return {+ id: node?.id ?? `file:${ref.path}`, name, kind: "file", path: ref.path,+ score: ref.score, reason: ref.reason, via: [], named: ref.reason,+ };+ }));+}+export function buildBundle(input: BuildInput): ContextBundle {const { resolved, facts, context, provenance, asOfRev, depth, budgets } = input;@@ -2158,6 +2211,7 @@ function formatLocation(location: EvidenceLocation): string {/** `rank.ts via listByKind, resolveWorkspaceId`, or just `rank.ts`. */function relatedClause(ref: RelatedRef): string {const name = (ref.path ?? ref.name).split("/").pop();+ if (ref.named) return `${name} (${ref.named})`;return ref.via.length > 0 ? `${name} via ${ref.via.join(", ")}` : `${name} directly`;}diff --git a/ix-cli/src/cli/explain/related-files.ts b/ix-cli/src/cli/explain/related-files.tsindex 56f07ac4..46ab00c9 100644--- a/ix-cli/src/cli/explain/related-files.ts+++ b/ix-cli/src/cli/explain/related-files.ts@@ -48,6 +48,8 @@ export interface RelatedRef extends EntityLocation {reason: string;/** The names it was reached through, most weight first; empty when direct. */via: string[];+ /** Set when the link is textual rather than a graph edge: `named in watch.ts`. */+ named?: string;}/** How many related files a bundle carries. */diff --git a/ix-cli/src/cli/explain/text-references.ts b/ix-cli/src/cli/explain/text-references.tsnew file mode 100644index 00000000..0c04ce39--- /dev/null+++ b/ix-cli/src/cli/explain/text-references.ts@@ -0,0 +1,233 @@+// Copyright 2026 Ix Infrastructure Inc.++import { execFileSync } from "node:child_process";+import { existsSync, readFileSync, statSync } from "node:fs";+import { join, posix } from "node:path";++/**+ * Files a context target names in its text, and files whose text names it.+ *+ * Some links between files are never edges in the graph, because nothing+ * imports anything. On ix-bench, three expected files were unreachable by any+ * walk for exactly that reason:+ *+ * - `ingestion-loader.ts` loads the parser registry through a string,+ * `"../../../../core-ingestion/dist/languages.js"`, which names the build+ * output of `core-ingestion/src/languages.ts`;+ * - `supported-extensions.ts` says, in a comment, that it "MUST stay in sync+ * with core-ingestion's EXT_MAP (languages.ts)";+ * - the parity test reads `supported-extensions.ts` as text, by path, rather+ * than importing it.+ *+ * So this reads the target and the files it imports for path-like tokens+ * that name a repository file (forward), and searches the repository for+ * files that name the target or its imports outside an import statement+ * (reverse). Import lines are skipped on both sides: the graph already has+ * those, and counting them again would turn every importer into a "mention".+ *+ * Precision comes from resolution, not from the pattern. A token counts only+ * when it resolves to exactly one tracked file: relative to the file it is in,+ * as a repository path, as a unique path suffix, or as a basename no other+ * file shares. A build path maps back to its source (`dist/` -> `src/`,+ * `.js` -> `.ts`). A name that half the repository mentions is not a link.+ */++export interface TextReference {+ /** Repository-relative path of the file referred to or referring. */+ path: string;+ /** Higher is stronger. Comparable within one bundle. */+ score: number;+ /** Why, for the evidence row: `named in supported-extensions.ts`. */+ reason: string;+}++export interface TextSource {+ /** Repository-relative path of a file whose text is read. */+ path: string;+ /** The target itself, or one of the files it imports. */+ role: "target" | "import";+}++/** How the repository is read. Injected so the logic is testable without one. */+export interface RepoAccess {+ /** Every tracked file, repository-relative. */+ files(): string[];+ /** A tracked file's text, or undefined when unreadable or too large. */+ read(path: string): string | undefined;+ /** Files containing `needle` literally, with the matching lines. */+ grep(needle: string): Array<{ path: string; line: string }>;+}++/** Text references a bundle carries. */+export const MAX_TEXT_REFERENCES = 3;+/** A name mentioned outside imports by more files than this is not a link. */+const MAX_MENTIONERS = 6;+/** Files larger than this are not scanned for names. */+const MAX_SCAN_BYTES = 256 * 1024;++const WEIGHT = { forwardTarget: 1, reverseTarget: 0.8, forwardImport: 0.6, reverseImport: 0.5 };++// A path-like token ending in a source or config extension: `./x.ts`,+// `../../a/dist/b.js`, `core-ingestion/src/languages.ts`, `languages.ts`.+const PATH_TOKEN =+ /(?<![\w./-])((?:\.{1,2}\/)*(?:[\w@-][\w.@-]*\/)*[\w-][\w.-]*\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|scala|rb|json|ya?ml|toml|sh))(?![\w/])/g;++/**+ * `import … from`, `export … from`, `require(` -- the graph has these. A+ * dynamic `import("…")` is deliberately not here: its argument is often+ * computed or a build path, which is exactly the link the graph lacks.+ */+const IMPORT_LINE = /^\s*(?:import\b(?!\s*\()|export\b[^=]*\bfrom\b)|\brequire\s*\(/;++/** Files whose mention of a name is a reference: code, not prose. */+const CODE_FILE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|scala|rb|sh)$/;++export function collectTextReferences(+ repo: RepoAccess,+ sources: TextSource[],+ exclude: ReadonlySet<string>,+ limit = MAX_TEXT_REFERENCES,+): TextReference[] {+ const files = repo.files();+ const tracked = new Set(files);+ const byBasename = new Map<string, string[]>();+ for (const file of files) {+ const base = posix.basename(file);+ byBasename.set(base, [...(byBasename.get(base) ?? []), file]);+ }+ const sourcePaths = new Set(sources.map((s) => s.path));+ const found = new Map<string, TextReference>();+ const credit = (path: string, score: number, reason: string) => {+ if (exclude.has(path) || sourcePaths.has(path)) return;+ const prior = found.get(path);+ if (!prior || score > prior.score) found.set(path, { path, score, reason });+ };++ for (const source of sources) {+ const text = repo.read(source.path);+ if (text === undefined) continue;+ const name = posix.basename(source.path);++ // Forward: what this file names.+ const named = new Set<string>();+ for (const line of text.split("\n")) {+ if (IMPORT_LINE.test(line)) continue;+ for (const match of line.matchAll(PATH_TOKEN)) {+ const resolved = resolveToken(match[1], source.path, tracked, byBasename);+ if (resolved && resolved !== source.path) named.add(resolved);+ }+ }+ const forward = source.role === "target" ? WEIGHT.forwardTarget : WEIGHT.forwardImport;+ for (const path of named) credit(path, forward, `named in ${name}`);++ // Reverse: who names this file. Only a basename no other tracked file+ // shares can be attributed from a bare mention.+ if ((byBasename.get(name) ?? []).length !== 1) continue;+ const mentioners = new Set<string>();+ for (const hit of repo.grep(name)) {+ if (hit.path === source.path || !tracked.has(hit.path) || !CODE_FILE.test(hit.path)) continue;+ if (IMPORT_LINE.test(hit.line)) continue;+ mentioners.add(hit.path);+ }+ if (mentioners.size === 0 || mentioners.size > MAX_MENTIONERS) continue;+ const reverse = (source.role === "target" ? WEIGHT.reverseTarget : WEIGHT.reverseImport) / mentioners.size;+ for (const path of mentioners) credit(path, reverse, `names ${name} in its text`);+ }++ return [...found.values()]+ .sort((a, b) => b.score - a.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))+ .slice(0, limit);+}++/**+ * The one tracked file a token names, or undefined.+ *+ * Tried in order: relative to the file it appears in, as a repository path,+ * as a unique path suffix, as a unique basename. Each form is also tried as a+ * build path mapped back to source.+ */+export function resolveToken(+ token: string,+ from: string,+ tracked: ReadonlySet<string>,+ byBasename: ReadonlyMap<string, string[]>,+): string | undefined {+ const exists = (candidate: string) => sourceForms(candidate).find((f) => tracked.has(f));++ if (token.startsWith("./") || token.startsWith("../")) {+ const joined = posix.normalize(posix.join(posix.dirname(from), token));+ return joined.startsWith("..") ? undefined : exists(joined);+ }+ if (token.includes("/")) {+ const direct = exists(token);+ if (direct) return direct;+ const suffix = sourceForms(token);+ const hits = [...tracked].filter((f) => suffix.some((s) => f.endsWith(`/${s}`)));+ return hits.length === 1 ? hits[0] : undefined;+ }+ const candidates = new Set(sourceForms(token).flatMap((f) => byBasename.get(f) ?? []));+ return candidates.size === 1 ? [...candidates][0] : undefined;+}++/** A path and the source paths its build output could have come from. */+const BUILD_EXTENSIONS: Array<[RegExp, string[]]> = [+ [/\.js$/, [".ts", ".tsx", ".js"]],+ [/\.mjs$/, [".mts", ".mjs"]],+ [/\.cjs$/, [".cts", ".cjs"]],+ [/\.jsx$/, [".tsx", ".jsx"]],+];++function sourceForms(path: string): string[] {+ const bases = new Set([path]);+ if (/(^|\/)dist\//.test(path)) bases.add(path.replace(/(^|\/)dist\//, "$1src/"));+ const out = new Set<string>();+ for (const base of bases) {+ out.add(base);+ for (const [pattern, exts] of BUILD_EXTENSIONS) {+ if (pattern.test(base)) for (const ext of exts) out.add(base.replace(pattern, ext));+ }+ }+ return [...out];+}++/**+ * The repository as git sees it, rooted at `root`. Outside a git checkout+ * there is no file list to resolve against, and this returns undefined: the+ * signal is skipped rather than guessed.+ */+export function gitRepoAccess(root: string): RepoAccess | undefined {+ let listing: string[];+ try {+ listing = execFileSync("git", ["ls-files", "-z"], {+ cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024,+ }).split("\0").filter(Boolean);+ } catch {+ return undefined;+ }+ return {+ files: () => listing,+ read: (path) => {+ const abs = join(root, path);+ try {+ if (!existsSync(abs) || statSync(abs).size > MAX_SCAN_BYTES) return undefined;+ return readFileSync(abs, "utf-8");+ } catch {+ return undefined;+ }+ },+ grep: (needle) => {+ try {+ const out = execFileSync("git", ["grep", "-n", "-I", "-F", "-e", needle], {+ cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 16 * 1024 * 1024,+ });+ return out.split("\n").filter(Boolean).map((row) => {+ const first = row.indexOf(":");+ const second = row.indexOf(":", first + 1);+ return { path: row.slice(0, first), line: row.slice(second + 1) };+ });+ } catch {+ return []; // exit 1 is "no match"+ }+ },+ };+}