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

package/dist/ai/synthesize.js

@@ -0,0 +1,230 @@
+import { recoverToolArgsFromContent, warnToolChoiceIgnored } from "./llm/recover-tool.js";
+const SYSTEM_PROMPT = `You build an ARCHITECTURE graph of a codebase from per-file summaries. The reader is an AI agent that will read this graph before working on the code, so it must describe the system at the level a senior engineer would explain it — not file by file.
+
+Produce a CURATED set of nodes of mixed granularity:
+- "system" nodes: GROUP files that collaborate as one component (usually a directory or a cohesive set) into a SINGLE node. This should be the most common node type. Prefer one system node over several file nodes.
+- "file" nodes: only for a substantial, standalone module that genuinely deserves its own node apart from its system.
+- "concept" nodes: cross-cutting ideas, design decisions, or invariants that span multiple files (e.g. "local-first provider fallback", "staleness checking", "content-hash provenance"). Include several — they are the most valuable nodes for an agent.
+
+Rules:
+- Every summary must earn its tokens with NON-OBVIOUS information: invariants, ordering constraints, conventions, failure modes, "X must never happen after Y" facts, and the WHY behind a design. Never restate what a README says or what a directory listing already makes obvious ("src/api contains the API code" is worthless); an agent reading the node already sees the file paths. If all you can say about a group of files is what their names say, fold them into a larger node instead.
+- Strongly prefer FEWER, larger, meaningful nodes. For a repo of N files, aim for well under N nodes. Do NOT emit one node per file, and never a node per incidental identifier (a local interface, helper, or third-party symbol).
+- Merge duplicates and surface-form variants into one node.
+- For each node give: a canonical human-readable name; a type ("system" | "file" | "concept"); a 1-3 sentence summary of its ROLE in the system; "sources" = the exact file paths (from the input) it is grounded in (a system lists all its files; a concept lists the files that motivate it); and "links" to other nodes you define, each with a relation and a short description of what concretely happens in the code.
+- The relation MUST be one of exactly these verbs (each answers a question a code reviewer asks): "part_of" (where does this live?), "uses" (what breaks if the target changes?), "depends_on" (same, for non-call dependencies), "produces" (where does this output come from?), "configures" (what changes its behavior without a code change?), "validates" (what checks or judges this? tests, drift checks, scoring), "implements" (what contract must this honor?). Never invent vague relations like "influences", "supports", or "relates_to" — if none of the verbs fit, drop the link.
+- Only link to nodes you actually define in this response.
+Respond only via the record_graph tool / JSON schema.`;
+const NODES_SCHEMA = {
+    type: "object",
+    properties: {
+        nodes: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    type: { type: "string" },
+                    summary: { type: "string" },
+                    sources: { type: "array", items: { type: "string" } },
+                    links: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                to: { type: "string" },
+                                relation: {
+                                    type: "string",
+                                    enum: ["part_of", "uses", "depends_on", "produces", "configures", "validates", "implements"],
+                                },
+                                description: { type: "string" },
+                            },
+                            required: ["to", "relation"],
+                        },
+                    },
+                },
+                required: ["name", "type", "summary", "sources"],
+            },
+        },
+    },
+    required: ["nodes"],
+};
+/** Cap the total summary text sent in one call so it never blows the context. */
+const MAX_INPUT_CHARS = 60_000;
+function userContent(files) {
+    const body = files.map((f) => `## ${f.path}\n\n${f.summary}`).join("\n\n");
+    return body.length > MAX_INPUT_CHARS
+        ? `${body.slice(0, MAX_INPUT_CHARS)}\n… (truncated)`
+        : body;
+}
+/** Normalize a raw model response into clean {@link SynthNode}s. */
+function clean(nodes) {
+    if (!Array.isArray(nodes))
+        return [];
+    const out = [];
+    for (const n of nodes) {
+        if (!n || typeof n.name !== "string" || typeof n.type !== "string")
+            continue;
+        out.push({
+            name: n.name,
+            type: n.type,
+            summary: typeof n.summary === "string" ? n.summary : "",
+            sources: Array.isArray(n.sources) ? n.sources.filter((s) => typeof s === "string") : [],
+            links: Array.isArray(n.links)
+                ? n.links
+                    .filter((l) => l && typeof l.to === "string" && typeof l.relation === "string")
+                    .map((l) => ({
+                    to: l.to,
+                    relation: l.relation,
+                    description: typeof l.description === "string" ? l.description : undefined,
+                }))
+                : [],
+        });
+    }
+    return out;
+}
+/**
+ * A forced `record_graph` call can still deliver `nodes` as a JSON *string*
+ * (double-encoded args). `clean` would then return [] and the CLI ticked
+ * `✓ concepts: 0 nodes` (#383). Parse, then salvage balanced `{"name":…}`
+ * objects if a stray brace breaks the string. Do not reuse recover-tool —
+ * that path only runs when there is no tool-call args object.
+ */
+function coerceRecordGraphNodes(nodes, toolCalls) {
+    if (Array.isArray(nodes))
+        return nodes;
+    if (typeof nodes !== "string")
+        return [];
+    let parsed;
+    let salvaged = 0;
+    try {
+        parsed = JSON.parse(nodes);
+    }
+    catch {
+        const objs = salvageNamedObjects(nodes);
+        parsed = objs;
+        salvaged = objs.length;
+    }
+    const values = Array.isArray(parsed) ? parsed : [];
+    const salvageBit = salvaged > 0 ? ` — salvaged ${salvaged} node(s) from malformed JSON` : "";
+    console.error(`⚠ synthesize: tool call returned "nodes" as a ${nodes.length}-char string, not an array; ${toolCalls} tool call(s)${salvageBit}`);
+    return values;
+}
+/** Pull complete `{"name":…}` objects out of a near-JSON string. */
+function salvageNamedObjects(raw) {
+    const out = [];
+    for (let i = 0; i < raw.length;) {
+        const start = raw.indexOf("{", i);
+        if (start === -1)
+            break;
+        const end = balancedClose(raw, start);
+        if (end === -1) {
+            i = start + 1;
+            continue;
+        }
+        try {
+            const obj = JSON.parse(raw.slice(start, end + 1));
+            if (obj && typeof obj === "object" && !Array.isArray(obj) && typeof obj.name === "string") {
+                out.push(obj);
+            }
+        }
+        catch {
+            /* slice was not a complete object */
+        }
+        i = end + 1;
+    }
+    return out;
+}
+function balancedClose(raw, start) {
+    let depth = 0;
+    let inStr = false;
+    let escape = false;
+    for (let i = start; i < raw.length; i++) {
+        const c = raw[i];
+        if (inStr) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (c === "\\") {
+                escape = true;
+                continue;
+            }
+            if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            continue;
+        }
+        if (c === "{")
+            depth++;
+        else if (c === "}") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function shapeOfNodes(nodes) {
+    if (typeof nodes === "string")
+        return `"nodes" is string, ${nodes.length} chars`;
+    if (Array.isArray(nodes))
+        return `"nodes" is array, ${nodes.length} entries`;
+    if (nodes === undefined)
+        return `"nodes" is undefined`;
+    return `"nodes" is ${typeof nodes}`;
+}
+const RECORD_TOOL = "record_graph";
+/** Synthesizer backed by any {@link ChatModel} via forced tool calling. */
+export class ChatSynthesizer {
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    async synthesize(files) {
+        if (files.length === 0)
+            return [];
+        const res = await this.model.create({
+            temperature: 0,
+            maxTokens: 8192,
+            tools: [
+                {
+                    name: RECORD_TOOL,
+                    description: "Record the curated architecture-graph nodes and their links.",
+                    parameters: NODES_SCHEMA,
+                },
+            ],
+            responseFormat: { kind: "tool", name: RECORD_TOOL },
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userContent(files) },
+            ],
+        });
+        const raw = nodesFromResponse(res)?.nodes;
+        const out = clean(coerceRecordGraphNodes(raw, res.toolCalls.length));
+        if (out.length === 0) {
+            console.error(`⚠ synthesize: empty batch (${shapeOfNodes(raw)}; ${res.toolCalls.length} tool call(s))`);
+        }
+        return out;
+    }
+}
+/**
+ * Prefer a real tool call; if the gateway ignored `tool_choice` (#129), recover
+ * the same payload from `content`. Recovered args still go through {@link clean}.
+ */
+function nodesFromResponse(res) {
+    const call = res.toolCalls.find((c) => c.name === RECORD_TOOL) ?? res.toolCalls[0];
+    if (call?.args && typeof call.args === "object" && !Array.isArray(call.args)) {
+        return call.args;
+    }
+    const recovered = recoverToolArgsFromContent(res.text, {
+        toolNames: [RECORD_TOOL, "emit_json"],
+        payloadKey: "nodes",
+    });
+    if (!recovered)
+        warnToolChoiceIgnored("synthesize", res.text?.trim() ? "unparsed" : "empty");
+    return recovered;
+}
+//# sourceMappingURL=synthesize.js.map

package/dist/ai/synthesize.js.map

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

package/dist/ask/ask.d.ts

@@ -0,0 +1,199 @@
+import { type Savings } from "../context/savings.js";
+import type { NodeV1, Relation } from "../graph/types.js";
+export interface AskHit {
+    kind: "concept" | "symbol" | "caller" | "callee";
+    title: string;
+    /** A `file` or `file:Lx-Ly` pointer the agent can open directly. */
+    pointer: string;
+    snippet: string;
+    relation?: Relation;
+    related?: string[];
+    score: number;
+    /** The actual source at `pointer`, sliced from disk when `source` is on.
+     * This is what makes `ask` substitutive — the agent reads the span here
+     * instead of opening the file, so no source read happens on top of the query. */
+    code?: string;
+    /** Multi-scope repos only: the ranking scope (path prefix, "" = root) this
+     * hit was ranked within — answers "which sub-project is this from?". Drives
+     * the `[scope/] ` label in formatAsk. Absent on single-scope repos. */
+    scope?: string;
+}
+/** Internal file-aware ranking group. The first hit is the one document that
+ * participates in a higher-level ranker; the remaining hits are projected only
+ * after every ranked group has emitted its leader. */
+export interface AskRankingGroup {
+    key: string;
+    hits: AskHit[];
+    /** Exact baseline-scored members of this group, in baseline order. Populated
+     * only in opt-in metadata so a workspace top lock never reuses a pooled
+     * leader score for a secondary span. */
+    baselineHits?: AskHit[];
+    coverage: number;
+    coverageStrong: number;
+}
+/** Internal metadata used by workspace federation to fuse file documents
+ * before projecting symbol spans. It is opt-in and never appears in normal
+ * CLI/API results. */
+export interface AskRankingMetadata {
+    groups: AskRankingGroup[];
+    baseline: Array<{
+        group: string;
+        hit: AskHit;
+    }>;
+    baselineCoverage?: number;
+    baselineCoverageStrong?: number;
+}
+export interface AskResult {
+    query: string;
+    mode: "structural" | "lexical" | "empty";
+    /** For structural mode: the symbol whose neighbours we walked. */
+    subject?: string;
+    /** Authoritative result order. Lexical results preserve each hit's raw
+     * relevance score, but select distinct-file leaders before sibling spans, so
+     * callers must not re-sort this list by `score`. */
+    hits: AskHit[];
+    note?: string;
+    /** The repo keeps notes on this machine, so an empty `notes` means "none
+     *  about this yet" rather than "this repo keeps no notes". */
+    notesChecked?: boolean;
+    /** One line about the notes, e.g. that this many would search better ranked. */
+    notesHint?: string;
+    /** Token-saving estimate, set only in `--source` (retriever) mode: the whole
+     * size of the distinct files these hits point into, i.e. the baseline cost of
+     * reading them instead of this pack. Computed from file sizes stored at build. */
+    saved?: {
+        files: number;
+        baselineChars: number;
+    };
+    /** Lexical mode only: share (0..1) of the query's distinct terms the TOP hit
+     * matched. A relevance signal for callers that inject packs unprompted (the
+     * Claude prompt hook): a low share means the query's words barely overlap the
+     * best result, i.e. the pack is probably noise for this prompt. Absent in
+     * structural mode — a resolved "who calls X" is itself the relevance signal. */
+    coverage?: number;
+    /** Like {@link coverage}, but the top hit's idf-weighted matched share over
+     * its NAME + PATH fields ONLY (body excluded) — a match-STRENGTH signal:
+     * "did the query hit a high-value field, or only incidental body tokens?".
+     * A body-only collision (a variable that happens to share a query word) has
+     * `coverageStrong === 0` while `coverage` can still look respectable. Used by
+     * workspace federation to gate a weak child out of the cross-repo ranking.
+     * Absent in structural mode; same lexical-only contract as `coverage`. */
+    coverageStrong?: number;
+    /** Multi-scope lexical results only: which scopes federated into the fused
+     * ranking, plus scopes that matched too weakly to federate (with their best
+     * doc id). Drives formatAsk's `matched in:` / `also matched:` footer.
+     * Absent on single-scope repos — zero output change there. */
+    scopes?: {
+        federated: string[];
+        alsoMatched: {
+            scope: string;
+            bestId: string;
+        }[];
+    };
+    /** @internal Opt-in latent file groups plus the exact pre-file-ranking list. */
+    ranking?: AskRankingMetadata;
+}
+/** Score a document's token counts against the query counts (name field
+ * pre-weighted by caller). Each shared term is weighted by its inverse document
+ * frequency (`idf`), so a word that appears in many nodes — "overlay" across a
+ * whole widget subsystem, or a repeated word in a pasted issue body — counts for
+ * far less than a rare, discriminating identifier ("scrolling"). Without idf,
+ * pure term-frequency lets an incidental common word dominate the ranking; this
+ * is the lexical half of the keyword-collision fix (graph-rank is the other). */
+/** Test files rarely answer "how does X work" / "where is Y" — they mirror the
+ * real symbol's tokens, so a test can out-score the definition on a lexical tie
+ * and land as the top hit (observed: an `ask` returning a `Test…` function first,
+ * sending the agent to the wrong file). A multiplicative de-rank keeps tests in
+ * the results (they still matter for "where are the tests") but below the real
+ * definition. Covers Go (`_test.go`), JS/TS (`.test.` / `.spec.`), and test dirs. */
+export declare function isTestPath(path: string): boolean;
+/** Idf-weighted share (0..1) of the query a document matches: each query term
+ * counts by its rarity, so this separates task prompts from chatter in a way a
+ * raw term count can't. A conversational prompt's words are either off-corpus
+ * (rare → heavy, unmatched → sinks the ratio) or generic code words ("list",
+ * "write": common → near-weightless even when they collide with a symbol name);
+ * a task prompt matches exactly its rare, discriminating identifiers. Terms the
+ * corpus has never seen take `dfltIdf` (the df=0 weight). */
+/** The match-STRENGTH share behind `coverageStrong`: idf-weighted share of the
+ * query matched in the node's NAME field ONLY. The PATH field is deliberately
+ * excluded — a coincidental generic directory (`gateway/`) or file basename
+ * (`gateway.ts`) in an unrelated repo would otherwise clear the strength gate
+ * and float that repo to the top; an on-topic path-organized repo is still
+ * rescued by the broad-coverage HIGH_FLOOR clause instead. For the same reason
+ * a `kind:"file"` node contributes zero strength: its `name` is a basename (a
+ * path component), not a symbol name, so a file whose basename happens to share
+ * a query word is not a strong match. */
+export declare function strongShare(q: Map<string, number>, node: NodeV1, doc: {
+    name: Map<string, number>;
+}, idf: Map<string, number>, dfltIdf: number): number;
+export interface AskOptions {
+    contextDir?: string;
+    limit?: number;
+    /** Inline the source at each `path:Lx-Ly` hit, sliced from `dir`. Turns the
+     * pack from a locator into a retriever so the agent needn't re-open the file. */
+    source?: boolean;
+    /** Re-rank lexical hits by graph connectivity (personalized PageRank over the
+     * wiring edges), demoting same-word collisions and rescuing strongly-connected
+     * neighbours the query didn't name. On by default; set false for pure lexical. */
+    graphRank?: boolean;
+    /** With `source`: inline each hit's WHOLE definition span (capped at
+     * {@link MAX_SPAN_LINES}) instead of the default crux-first slice. The
+     * default inlines the ≤8-line LLM-chosen crux when a node has one — the
+     * decision point, ~10× cheaper than the full span — and the pack marks each
+     * crux so the agent knows `--full` (or the file itself) has the rest. */
+    full?: boolean;
+    /** Narrow the doc/node set to this path prefix BEFORE scoring (segment-aware,
+     * like `scopeOf` — "frontend" never matches "frontend-utils"). Per-scope
+     * IDF/BM25/walk come free: the filtered set is usually one scope, so the
+     * existing multi-scope machinery degrades to its single-scope passthrough
+     * with no scope labels. A prefix matching nothing indexed throws. */
+    in?: string;
+    /** @internal Defer file-first projection to a downstream authoritative
+     * ranking stage (currently workspace federation). Direct callers should
+     * leave this unset. */
+    fileFirst?: boolean;
+    /** @internal Bounded file scoring control. */
+    fileComplement?: boolean;
+    /** @internal Exact baseline top-hit lock. Requires bounded file
+     * scoring and composes it with the file-first frontier. */
+    fileTopLock?: boolean;
+    /** @internal Return latent file queues and the exact baseline list so a
+     * workspace parent can fuse files before projecting spans. */
+    includeRankingMetadata?: boolean;
+}
+/** Answer a query from the graft/ graph at `dir`. Deterministic, $0. */
+export declare function ask(dir: string, query: string, opts?: AskOptions): AskResult;
+export interface SkeletonEntry {
+    name: string;
+    kind: string;
+    span: string;
+    signature: string | null;
+    /** First line of the Tier-2 summary, when the node has one. */
+    summary?: string;
+}
+export interface SkeletonResult {
+    file: string;
+    entries: SkeletonEntry[];
+    note?: string;
+    /** Tokens-saved baseline: this file read whole vs the signatures-only view. */
+    saved?: Savings;
+}
+/** Signatures-only view of one file, straight from the wiring graph — the
+ * cheapest way to understand a file's API surface (~10× less than reading it).
+ * `file` is matched as an exact repo-relative path, then as a basename. */
+export declare function skeleton(dir: string, file: string, opts?: {
+    contextDir?: string;
+}): SkeletonResult;
+/** Render a {@link SkeletonResult} as compact markdown. */
+export declare function formatSkeleton(r: SkeletonResult): string;
+/** Render an {@link AskResult} as a compact markdown context pack. */
+export declare function formatAsk(r: AskResult): string;
+/** {@link formatAsk}, plus the tokens its pack saved (what {@link askSavedTokens} says), from the one render. */
+export declare function formatAskWithSaved(r: AskResult): {
+    text: string;
+    savedTokens: number;
+};
+/** Tokens this lookup's pack saved against reading the files it covers whole:
+ * the number `formatAsk` prints as "tokens saved ≈ N", or 0 when it prints none. */
+export declare function askSavedTokens(r: AskResult): number;
+//# sourceMappingURL=ask.d.ts.map

package/dist/ask/ask.d.ts.map

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