trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/graph/seed.js

@@ -0,0 +1,229 @@
+/**
+ * `seedGraph` — give a linked git worktree the graph its parent checkout already has.
+ *
+ * `graft/` is a local cache, so it is gitignored, so `git worktree add` never checks
+ * it out: a worktree starts with `src/` and `.claude/` and no graph at all. Every
+ * MCP tool then answers "no graph found — run graft build first" for the whole
+ * session, and the passive surface (`INDEX.md`, the cards) is missing too. The agent
+ * that was supposed to be cheapest in a fresh worktree is instead blind in one.
+ *
+ * What travels is the graph and the sidecars a query reads — never the markdown; see
+ * `seedable` for why the cards are the parent's branch and not this one's.
+ *
+ * The parent checkout has not gone anywhere, though — a worktree's `.git` is a *file*
+ * naming it, and the harness that creates these worktrees already reaches back the
+ * same way (Claude Code symlinks `node_modules` to the parent's). So: copy the
+ * parent's `graft/` in, then let the ordinary refresh gate repair the difference.
+ *
+ * Copy, not symlink. `node_modules` is the same for every branch; a graph is a set of
+ * `file:line` spans for one specific tree, so a shared one would have the worktree
+ * rewriting the parent's graph with its own branch's line numbers. What makes the
+ * copy worth doing rather than just rebuilding cold:
+ *
+ * - **The Tier-2 meaning layer survives.** Summaries and cruxes cost real money;
+ *   `buildGraph` folds a prior `wiring.json` in by `body_hash`, so an unchanged
+ *   function keeps the summary someone already paid for. A cold build throws them all
+ *   away and the worktree silently drops to structural-only answers.
+ * - **The repair is small.** `probeDrift` confirms a suspect file by content hash, so
+ *   a fresh checkout's brand-new mtimes cost one hashing pass and nothing more; the
+ *   drift that survives is exactly the diff between the two checkouts' commits.
+ * - **$0 and offline**, like everything else on the query path.
+ *
+ * Never writes to the parent, never throws, and no-ops unless there is genuinely a
+ * built parent checkout on disk — so a fresh clone, CI, or a cloud session whose repo
+ * was *cloned* rather than worktree'd behaves exactly as it did before: "run graft
+ * build first".
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { ASK_INDEX_FILE } from "../ask/index-file.js";
+import { CACHE_DIR, contextDirFor } from "../context/node-file.js";
+import { EXTRACT_CACHE_PREFIX } from "./extract-cache.js";
+import { FINGERPRINT_PREFIX } from "./fingerprint.js";
+import { GRAPH_DIR, wiringPath } from "./write.js";
+/** The one line a linked worktree's `.git` file carries. */
+const GITDIR_KEY = "gitdir:";
+/** Env kill switch, mirroring `GRAFT_NO_REFRESH` in ./refresh.ts. */
+export function seedDisabled() {
+    const v = process.env.GRAFT_NO_SEED;
+    return v !== undefined && v !== "" && v !== "0" && v !== "false";
+}
+/**
+ * The main checkout of the repo `root` is a linked worktree of, or null when `root`
+ * isn't one (which is the common case, and not an error).
+ *
+ * Filesystem-only on purpose: no `git` subprocess on a path that runs before every
+ * query. The shapes it has to tell apart:
+ *
+ * - `<root>/.git` is a **directory** → this *is* the main checkout. Nothing to seed.
+ * - `gitdir: <main>/.git/worktrees/<name>` → a linked worktree. `commondir` inside
+ *   that dir points back at the shared `.git` (`../..`), whose parent is the main
+ *   checkout.
+ * - `gitdir: <super>/.git/modules/<name>` → a **submodule**. Identical file shape,
+ *   completely different thing: a submodule is its own repo and its parent's `graft/`
+ *   describes different code entirely. The `worktrees` path segment is what rejects it.
+ * - A bare repo or `--separate-git-dir` layout, where the resolved common dir isn't
+ *   named `.git` and there may be no working tree at all → null.
+ */
+export function mainWorktreeRoot(root) {
+    try {
+        const dot = join(root, ".git");
+        if (statSync(dot).isDirectory())
+            return null;
+        // Read the pointer without a regex. `/^gitdir:[ \t]*(.+?)[ \t]*$/m` is the
+        // polynomial-ReDoS shape CodeQL flagged on `ensureSearchable` (`js/polynomial-redos`,
+        // fixed in 44a191e): `.` also matches space and tab, so the lazy group and the
+        // trailing `[ \t]*` overlap and a line of blanks costs O(n²). Same conclusion as
+        // that fix — the ambiguity buys nothing, and split/startsWith/trim is linear and
+        // plainer. `trim` also absorbs the `\r` of a CRLF checkout.
+        const line = readFileSync(dot, "utf8").split("\n").find((l) => l.startsWith(GITDIR_KEY));
+        if (line === undefined)
+            return null;
+        const target = line.slice(GITDIR_KEY.length).trim();
+        if (!target)
+            return null;
+        const gitdir = isAbsolute(target) ? target : resolve(root, target);
+        if (basename(dirname(gitdir)) !== "worktrees")
+            return null;
+        const rel = readFileSync(join(gitdir, "commondir"), "utf8").trim();
+        if (!rel)
+            return null;
+        const common = isAbsolute(rel) ? rel : resolve(gitdir, rel);
+        if (basename(common) !== ".git" || !statSync(common).isDirectory())
+            return null;
+        const main = dirname(common);
+        if (resolve(main) === resolve(root))
+            return null;
+        return main;
+    }
+    catch {
+        // No `.git` at all, an unreadable one, a `commondir` that doesn't exist: all of
+        // them mean "can't seed from here", which is the same answer as "not a worktree".
+        return null;
+    }
+}
+const NOT_SEEDED = { seeded: false };
+/** Filename of the semantic embeddings database, relative to the cache dir. */
+const EMBEDDINGS_FILE = "embeddings.db";
+/**
+ * An allowlist, not a skip list: is this repo-relative path (posix) one of the few
+ * files a seed may bring across?
+ *
+ * The gate that calls this promises "writes only what a query reads — the graph, the
+ * `ask` sidecar, the freshness record" (see the header of ./refresh.ts). A copy that
+ * wrote anything else would turn a read into a write of the repo, so the copy honours
+ * the same list. The extraction memo is on it because the refresh immediately after
+ * rewrites that file anyway, and replaying it is what keeps the repair cheap.
+ *
+ * **Deliberately absent: the cards and `INDEX.md`.** They would land as this
+ * checkout's documentation while describing the *parent's* branch, and nothing on the
+ * query path rewrites them (`writeCards`/`writeIndex` sit behind `!graphOnly`), so they
+ * would stay wrong indefinitely. An explicit `graft build` regenerates them from this
+ * checkout's own graph — and prunes the ones that no longer apply — which is both
+ * correct and nearly free once the graph is here.
+ *
+ * Also absent, because it belongs to the checkout that produced it: `.cache/session/`
+ * (another session's transcripts), `.sync.lock` (another process's lock), and
+ * `stats.json` (this checkout earns its own savings and dirty flag).
+ */
+function seedable(rel) {
+    // The dirs themselves, or cpSync would never look inside them.
+    if (rel === "" || rel === GRAPH_DIR || rel === CACHE_DIR)
+        return true;
+    if (!rel.startsWith(`${CACHE_DIR}/`))
+        return false; // incl. the graph: `installGraph` places it
+    const name = rel.slice(CACHE_DIR.length + 1);
+    return (name === ASK_INDEX_FILE ||
+        name === EMBEDDINGS_FILE ||
+        name.startsWith(`${EXTRACT_CACHE_PREFIX}.`) ||
+        name.startsWith(`${FINGERPRINT_PREFIX}.`));
+}
+/**
+ * Copy `srcDir` into `outDir`, keeping only what {@link seedable} allows.
+ *
+ * Walked by hand rather than through `cpSync`'s `filter`, which did not hold on
+ * Windows: the graph arrived — it is placed directly, by {@link installGraph} — while
+ * every allowlisted sidecar next to it was dropped. A seeded worktree therefore had no
+ * fingerprint, `probeDrift` read that as "never built", and the query right behind the
+ * seed rebuilt the whole repo instead of the diff against the parent: precisely the
+ * cost seeding exists to avoid, and silent, because a full rebuild still answers
+ * correctly. It only surfaced as a `(? files changed)` note on the CI leg.
+ *
+ * Composing `rel` from the segments this walk joined itself is what fixes it — the
+ * allowlist no longer depends on the form `cpSync` chooses to hand its callback, and
+ * `rel` is posix by construction rather than by conversion. Also narrower than the old
+ * copy in one way worth keeping: only real files and directories travel, never a
+ * symlink, and nothing in the allowlist is one.
+ */
+function copyTree(srcDir, outDir) {
+    const walk = (rel) => {
+        const from = rel ? join(srcDir, rel) : srcDir;
+        mkdirSync(rel ? join(outDir, rel) : outDir, { recursive: true });
+        for (const entry of readdirSync(from, { withFileTypes: true })) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (!seedable(childRel))
+                continue;
+            if (entry.isDirectory())
+                walk(childRel);
+            else if (entry.isFile())
+                copyFileSync(join(from, entry.name), join(outDir, childRel));
+        }
+    };
+    walk("");
+}
+/**
+ * Put `wiring.json` in place last, via a temp file and a rename.
+ *
+ * Its presence is the flag every caller reads to mean "this repo has a graph"
+ * (`refresh.ts`, `workspace.ts`, every MCP tool). So it must appear only once the
+ * rest of the copy has landed and must never appear half-written: a seed killed
+ * midway then leaves no graph, and the next call simply seeds again.
+ */
+function installGraph(srcGraph, destGraph) {
+    mkdirSync(dirname(destGraph), { recursive: true });
+    const tmp = `${destGraph}.seed.${process.pid}`;
+    try {
+        copyFileSync(srcGraph, tmp);
+        renameSync(tmp, destGraph);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch { /* nothing to clean up */ }
+        throw err;
+    }
+}
+/**
+ * Copy the parent checkout's graph into `root`'s own `graft/`, if all of this holds:
+ * `root` is a linked worktree, it has no graph yet, the parent has one, and no `--dir`
+ * override is in play (a custom output dir can't be mapped to a sibling checkout —
+ * the same conservatism `ensureGitignored` applies).
+ *
+ * Best-effort by contract: the caller's fallback is the behaviour that existed before
+ * this function did, so every failure returns `{ seeded: false }` rather than raising.
+ */
+export function seedGraph(root, opts = {}) {
+    if (opts.contextDir || seedDisabled())
+        return NOT_SEEDED;
+    try {
+        const dir = resolve(root);
+        const outDir = contextDirFor(dir);
+        if (existsSync(wiringPath(outDir)))
+            return NOT_SEEDED; // already has its own
+        const main = mainWorktreeRoot(dir);
+        if (!main)
+            return NOT_SEEDED;
+        const srcDir = contextDirFor(main);
+        const srcGraph = wiringPath(srcDir);
+        if (!existsSync(srcGraph))
+            return NOT_SEEDED; // parent never built either
+        copyTree(srcDir, outDir);
+        installGraph(srcGraph, wiringPath(outDir));
+        return { seeded: true, from: main };
+    }
+    catch {
+        return NOT_SEEDED;
+    }
+}
+//# sourceMappingURL=seed.js.map

package/dist/graph/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../src/graph/seed.ts"],"names":[],"mappings":"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"}

package/dist/graph/source-files.d.ts

@@ -0,0 +1,46 @@
+/** Every extension graft has a parser for (depth + breadth + container), sorted
+ * and de-duped — the authoritative answer to "what does `-e` actually support". */
+export declare function supportedExtensions(): string[];
+/**
+ * The subset of user-supplied `-e` extensions that no parser claims (depth or breadth).
+ * `graft build -e ".vue"` used to accept these silently and index nothing; the CLI warns
+ * on whatever this returns so an unsupported extension is never a quiet no-op.
+ */
+export declare function unsupportedExtensions(exts: string[]): string[];
+/**
+ * The source files a graph build parses: supported languages, minus the
+ * output dir. When no pre-enumerated `repoFiles` is passed, the walk reads
+ * `root`'s persisted file-walk choices directly from state, so every caller
+ * that enumerates through here (the fingerprint probe and hooks/refresh path,
+ * none of which ever see a CLI flag) behaves identically to the build that
+ * saved those choices.
+ */
+/** Keep only files whose repo-relative path is at or under one of `onlyDirs`.
+ * No-op when `onlyDirs` is empty/absent. The whitelist is carried in the graph
+ * itself (the fingerprint records it at build time), never in the source repo,
+ * so a build and the query-path freshness probe read the identical set. */
+export declare function filterByOnlyDirs(files: string[], root: string, onlyDirs?: ReadonlySet<string>): string[];
+/**
+ * Returns true for OpenSpec `.md` files that should be auto-indexed regardless
+ * of `--include-md`. Covers `openspec/specs/**` and active `openspec/changes/**`,
+ * excluding `openspec/changes/archive/**` unless `includeArchive` is true.
+ */
+export declare function isOpenSpecMd(rel: string, includeArchive: boolean): boolean;
+export declare function listSourceFiles(root: string, outDir: string, repoFiles?: string[], onlyDirs?: ReadonlySet<string>): string[];
+export interface SourceStat {
+    /** Absolute path. */
+    abs: string;
+    /** Repo-relative, posix (`relPosix`) — exactly the form `buildGraph` uses for
+     * node ids and `checkGraph` diffs against, so cache keys and ids can never
+     * disagree. Posix on every platform: see `../util/paths.ts`. */
+    rel: string;
+    size: number;
+    mtimeMs: number;
+}
+/**
+ * {@link listSourceFiles} plus each file's `(size, mtimeMs)` — the currency of
+ * both the freshness probe and the extraction cache. Files that vanish between
+ * the walk and the stat are dropped (same fail-soft posture as `walkDir`).
+ */
+export declare function listSourceStats(root: string, outDir: string, repoFiles?: string[], onlyDirs?: ReadonlySet<string>): SourceStat[];
+//# sourceMappingURL=source-files.d.ts.map

package/dist/graph/source-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-files.d.ts","sourceRoot":"","sources":["../../src/graph/source-files.ts"],"names":[],"mappings":"AAkBA;mFACmF;AACnF,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAQD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAG9D;AAED;;;;;;;GAOG;AACH;;;2EAG2E;AAC3E,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,MAAM,EAAE,CAMV;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAK1E;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAM,EAGf,EACF,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,MAAM,EAAE,CAwBV;AAED,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ;;oEAEgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,UAAU,EAAE,CAYd"}

package/dist/graph/source-files.js

@@ -0,0 +1,118 @@
+/**
+ * The file set a graph build parses, and its stat metadata.
+ *
+ * Split out of `build.ts` so the freshness probe (`fingerprint.ts`) can enumerate
+ * exactly the same files without importing the builder (which would be an import
+ * cycle: build → fingerprint → build). `build.ts` re-exports
+ * {@link listSourceFiles} so its existing importers are unaffected.
+ */
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { walkDir } from "../ingest/fs.js";
+import { relPosix } from "../util/paths.js";
+import { readFollowNestedRepos, readFollowSubmodules, readIncludeDirs, readIncludeMd, readIncludeOpenSpecArchive, readMdOnlyDirs } from "../util/state.js";
+import { languageOf, depthExtensions } from "./extract.js";
+import { genericLangOf, genericExtensions } from "./generic.js";
+import { containerLangOf, containerExtensions } from "./container.js";
+import { isMdFile, MD_EXT } from "./markdown.js";
+/** Every extension graft has a parser for (depth + breadth + container), sorted
+ * and de-duped — the authoritative answer to "what does `-e` actually support". */
+export function supportedExtensions() {
+    return [...new Set([...depthExtensions(), ...genericExtensions(), ...containerExtensions(), MD_EXT])].sort();
+}
+/** Normalize a user-supplied extension: ensure a leading dot, lower-case. */
+function normExt(e) {
+    const t = e.trim().toLowerCase();
+    return t.startsWith(".") ? t : `.${t}`;
+}
+/**
+ * The subset of user-supplied `-e` extensions that no parser claims (depth or breadth).
+ * `graft build -e ".vue"` used to accept these silently and index nothing; the CLI warns
+ * on whatever this returns so an unsupported extension is never a quiet no-op.
+ */
+export function unsupportedExtensions(exts) {
+    const supported = new Set(supportedExtensions());
+    return exts.filter((e) => !supported.has(normExt(e)));
+}
+/**
+ * The source files a graph build parses: supported languages, minus the
+ * output dir. When no pre-enumerated `repoFiles` is passed, the walk reads
+ * `root`'s persisted file-walk choices directly from state, so every caller
+ * that enumerates through here (the fingerprint probe and hooks/refresh path,
+ * none of which ever see a CLI flag) behaves identically to the build that
+ * saved those choices.
+ */
+/** Keep only files whose repo-relative path is at or under one of `onlyDirs`.
+ * No-op when `onlyDirs` is empty/absent. The whitelist is carried in the graph
+ * itself (the fingerprint records it at build time), never in the source repo,
+ * so a build and the query-path freshness probe read the identical set. */
+export function filterByOnlyDirs(files, root, onlyDirs) {
+    if (!onlyDirs || onlyDirs.size === 0)
+        return files;
+    return files.filter((abs) => {
+        const rel = relPosix(root, abs);
+        return [...onlyDirs].some((d) => rel === d || rel.startsWith(`${d}/`));
+    });
+}
+/**
+ * Returns true for OpenSpec `.md` files that should be auto-indexed regardless
+ * of `--include-md`. Covers `openspec/specs/**` and active `openspec/changes/**`,
+ * excluding `openspec/changes/archive/**` unless `includeArchive` is true.
+ */
+export function isOpenSpecMd(rel, includeArchive) {
+    if (rel.startsWith('openspec/specs/'))
+        return true;
+    if (!rel.startsWith('openspec/changes/'))
+        return false;
+    if (rel.startsWith('openspec/changes/archive/'))
+        return includeArchive;
+    return true;
+}
+export function listSourceFiles(root, outDir, repoFiles = walkDir(root, readIncludeDirs(resolve(root)), {
+    followSubmodules: readFollowSubmodules(resolve(root)),
+    followNestedRepos: readFollowNestedRepos(resolve(root)),
+}), onlyDirs) {
+    // A file is a source file if a depth-tier grammar (languageOf), a breadth-tier
+    // grammar (genericLangOf) or a container (containerLangOf) claims its extension.
+    // All three must agree here or `build` and `check` would enumerate different sets.
+    const mdOnlyDirs = readMdOnlyDirs(root);
+    const includeArchive = readIncludeOpenSpecArchive(root);
+    return filterByOnlyDirs(repoFiles.filter((f) => {
+        if (f.startsWith(outDir))
+            return false;
+        if (languageOf(f) !== null || genericLangOf(f) !== null || containerLangOf(f) !== null)
+            return true;
+        if (!isMdFile(f))
+            return false;
+        // Auto-include OpenSpec .md files (specs + active changes, archive opt-in).
+        const rel = relPosix(root, f);
+        if (isOpenSpecMd(rel, includeArchive))
+            return true;
+        // Explicit --include-md behaviour (mdOnlyDirs filter applies).
+        if (!readIncludeMd(root))
+            return false;
+        if (mdOnlyDirs.length === 0)
+            return true;
+        return mdOnlyDirs.some((d) => rel === d || rel.startsWith(`${d}/`));
+    }), root, onlyDirs);
+}
+/**
+ * {@link listSourceFiles} plus each file's `(size, mtimeMs)` — the currency of
+ * both the freshness probe and the extraction cache. Files that vanish between
+ * the walk and the stat are dropped (same fail-soft posture as `walkDir`).
+ */
+export function listSourceStats(root, outDir, repoFiles, onlyDirs) {
+    const out = [];
+    for (const abs of listSourceFiles(root, outDir, repoFiles, onlyDirs)) {
+        let s;
+        try {
+            s = statSync(abs);
+        }
+        catch {
+            continue;
+        }
+        out.push({ abs, rel: relPosix(root, abs), size: s.size, mtimeMs: s.mtimeMs });
+    }
+    return out;
+}
+//# sourceMappingURL=source-files.js.map

package/dist/graph/source-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-files.js","sourceRoot":"","sources":["../../src/graph/source-files.ts"],"names":[],"mappings":"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"}

package/dist/graph/traverse-cli.d.ts

@@ -0,0 +1,55 @@
+import { type Savings } from "../context/savings.js";
+import { type Direction, type EdgeHit } from "./traverse.js";
+import type { GraphV1, NodeV1 } from "./types.js";
+export interface CallersCliOptions {
+    in?: string;
+    json?: boolean;
+    /** walk direction; defaults to "in" (callers). "out" gives callees. */
+    direction?: string;
+    /** max BFS depth, as the raw --depth string (validated here); defaults to 1. */
+    depth?: string;
+    /** the top-level `--dir` override, so this command respects it like every other. */
+    globalDir?: string;
+}
+/** Exported so the MCP `graft_trace_calls` tool (`src/mcp/tools.ts`) can render the
+ * same human report format as the CLI, rather than re-implementing it — both
+ * surfaces walk the same edges via the same `resolveSymbol` / `edgeWalk` core. */
+export declare function headerOf(n: NodeV1): string;
+/** `showDepth` is set for multi-hop walks (depth > 1), matching the old
+ * `graft impact` output which tagged every hit with its BFS depth.
+ *
+ * `quote`, when given, is the call site itself — the line inside the hit where it
+ * references the symbol. An edge that says "total calls add" is a claim; the line
+ * under it is the evidence, and it saves opening the file to check.
+ */
+export declare function hitLine(direction: Direction, hit: EdgeHit, showDepth: boolean, quote?: Quote): string;
+/** A quoted source line: where the edge actually happens. */
+interface Quote {
+    n: number;
+    text: string;
+}
+/** Tokens-saved baseline for a callers/callees walk: the files of the matched
+ * symbols plus every resolved edge endpoint, read whole — the files you'd open
+ * to trace these edges by hand. Shared by the CLI and the MCP tool so both
+ * surfaces report the same number. */
+export declare function callersSavings(graph: GraphV1, results: {
+    symbol: NodeV1;
+    hits: EdgeHit[];
+}[]): Savings | undefined;
+/** Loud, actionable empty-result note — never a bare empty list. `candidateCount`
+ * is how many nodes {@link resolveSymbol} matched for this query (both call
+ * sites already hold it as `matches.length`) — when it's >1, the query name is
+ * itself ambiguous (several definitions share it), which is exactly the case
+ * `resolve.ts` drops a cross-file call/reference for rather than guessing which
+ * one it means. Without saying so, a zero-hit result here reads as "nothing
+ * calls this" when it may really be "something does, but the edge was dropped". */
+export declare function looseNoteFor(direction: Direction, name: string, candidateCount: number): string;
+/**
+ * Resolve `query` in the graph at `dir` (respecting `--dir`/`--in`), walk edges
+ * per `--direction`/`--depth`, and print either the human report or `--json`.
+ * Exits the process (code 1) when there's no graph at all or the symbol is
+ * unknown — both are caller-facing mistakes, not recoverable states.
+ */
+export declare function runCallersCommand(query: string, dir: string, opts: CallersCliOptions): void;
+export {};
+//# sourceMappingURL=traverse-cli.d.ts.map

package/dist/graph/traverse-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse-cli.d.ts","sourceRoot":"","sources":["../../src/graph/traverse-cli.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAA2B,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;kFAEkF;AAClF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAMrG;AAED,6DAA6D;AAC7D,UAAU,KAAK;IACb,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD;;;sCAGsC;AACtC,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,EAAE,CAAA;CAAE,EAAE,GAC7C,OAAO,GAAG,SAAS,CAOrB;AAED;;;;;;mFAMmF;AACnF,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAQ/F;AAiDD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CA4E3F"}