@nanonets/graft 0.5.1 → 0.7.0

package/dist/ask/ask.js

@@ -17,8 +17,11 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import matter from "gray-matter";
 import { contextDirFor } from "../context/node-file.js";
+import { savingsFooter, savingsFor } from "../context/savings.js";
 import { loadGraphCached, loadAskIndexCached } from "../graph/load.js";
+import { pathUnderPrefix, scopeLabel, scopeOf, scopesHereClause, scopesOfGraph } from "../graph/scopes.js";
 import { resolveSymbol } from "../graph/traverse.js";
+import { rankScopesAndFuse } from "./fuse.js";
 import { personalizedPageRank } from "./graphrank.js";
 import { counts, tokenize } from "./index-file.js";
 /** Max source lines to inline per hit — a definition longer than this is
@@ -143,11 +146,22 @@ function subjectWords(query) {
  * last regardless of outcome, so a caller can name *something* in a fallthrough
  * note even when nothing resolved (e.g. `subjects.length === 0`). This is what
  * makes a qualified/dotted subject like `Cache.get` resolve, where the old
- * plain name-equality lookup (`findSubject`) never matched it. */
-function findSubjectNodes(query, graph) {
+ * plain name-equality lookup (`findSubject`) never matched it.
+ *
+ * `inPrefix`, when given, filters each word's `resolveSymbol` matches down to
+ * nodes under that path prefix BEFORE checking whether any survived — same
+ * "narrow the subject resolution" semantics `callers`/`callees`/`impact --in`
+ * already have (segment-aware here, via `pathUnderPrefix`). A word that
+ * resolves globally but has nothing under the prefix does NOT count as a
+ * match; the next (shorter) word is tried instead, same as an unresolved word
+ * today — and if nothing survives for ANY word, `subjects.length === 0`
+ * naturally falls through to the existing loud fallthrough note. */
+function findSubjectNodes(query, graph, inPrefix) {
     const words = subjectWords(query).sort((a, b) => b.length - a.length);
     for (const w of words) {
-        const nodes = resolveSymbol(graph, w);
+        let nodes = resolveSymbol(graph, w);
+        if (inPrefix)
+            nodes = nodes.filter((n) => pathUnderPrefix(n.path, inPrefix));
         if (nodes.length > 0)
             return { nodes, tried: w };
     }
@@ -157,12 +171,12 @@ function fallthroughNoteFor(subject) {
     return (`structural index: no entries for '${subject}' — showing lexical matches; ` +
         `for exhaustive callers use grep -rn '${subject}'`);
 }
-function structural(query, graph, limit) {
+function structural(query, graph, limit, inPrefix) {
     const wantsIn = INCOMING.test(query);
     const wantsOut = OUTGOING.test(query);
     if (!wantsIn && !wantsOut)
         return null;
-    const { nodes: subjects, tried } = findSubjectNodes(query, graph);
+    const { nodes: subjects, tried } = findSubjectNodes(query, graph, inPrefix);
     if (subjects.length === 0)
         return { fallthroughNote: fallthroughNoteFor(tried) };
     const ids = new Set(subjects.map((n) => n.id));
@@ -231,6 +245,20 @@ function hasTerm(f, t) {
  * "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 function strongShare(q, node, doc, idf, dfltIdf) {
+    if (node.kind === "file")
+        return 0;
+    return matchedIdfShare(q, [doc.name], idf, dfltIdf);
+}
 function matchedIdfShare(q, fields, idf, dfltIdf) {
     let matched = 0;
     let total = 0;
@@ -242,14 +270,19 @@ function matchedIdfShare(q, fields, idf, dfltIdf) {
     }
     return total > 0 ? matched / total : 0;
 }
-function lexical(query, corpus, limit, graphRank) {
+function lexical(query, corpus, limit, graphRank, inPrefix) {
     // Binary query terms: a word repeated in a pasted issue body counts once, so a
     // ranty description can't linearly amplify an incidental word.
     const q = new Map([...counts(tokenize(query)).keys()].map((t) => [t, 1]));
     const graph = corpus.graph;
     // ── Pass 1: tokenize every scored field once, and collect per-document token
-    // bags so IDF can down-weight words that occur across the whole corpus. ──
-    const conceptDocs = corpus.concepts.map((c) => ({
+    // bags so IDF can down-weight words that occur across the whole corpus. `--in`
+    // drops a concept unless at least one of its sources falls under the prefix —
+    // filtering happens here, before any scoring, so a narrowed query never sees
+    // an unrelated concept from outside the prefix. ──
+    const conceptDocs = corpus.concepts
+        .filter((c) => !inPrefix || c.sources.some((p) => pathUnderPrefix(p, inPrefix)))
+        .map((c) => ({
         c,
         name: counts(tokenize(c.name)),
         body: counts(tokenize(c.text)),
@@ -261,6 +294,18 @@ function lexical(query, corpus, limit, graphRank) {
     // that — missing, unparseable, unknown version, wrong count, mismatched ids —
     // falls back to live tokenization so results never depend on the sidecar
     // existing; see `readAskIndex`'s own null-on-anything-off contract.
+    //
+    // `--in` does NOT disable the sidecar here: `writeGraph` strips `body_text`
+    // from every node it serializes (see `write.ts`) — the sidecar's per-doc
+    // `docs[].body` bags are the ONLY place a symbol's body tokens survive on a
+    // graph loaded from disk. Bypassing the sidecar under `--in` would silently
+    // empty out `body` for every node (falling back to `n.body_text ?? ""`,
+    // always `""` post-slim-serialization), losing every body-only match under
+    // the filtered prefix. What DOES need bypassing under `--in` is the
+    // sidecar's GLOBAL `df`/`docCount`/`avgBodyLen` — those cover the whole
+    // corpus, not the filtered subset — so each read of those three fields below
+    // is separately gated on `!inPrefix`, while the per-doc bags (used to build
+    // `symbolDocs` right after this) are used unconditionally.
     let docById = null;
     if (corpus.askIndex && graph && corpus.askIndex.docs.length === graph.nodes.length) {
         const map = new Map(corpus.askIndex.docs.map((d) => [d.id, d]));
@@ -271,8 +316,12 @@ function lexical(query, corpus, limit, graphRank) {
     // Symbols AND file nodes are scored: a symbol's body_text is its definition;
     // a file's body_text is the module-level residual (imports/constants not in
     // any symbol). Including files closes the recall gap where a gold file's only
-    // query-relevant text lives outside every function/class.
-    const symbolDocs = (graph?.nodes ?? []).map((n) => {
+    // query-relevant text lives outside every function/class. `--in` filters the
+    // node set here, at the very top, before any scoring — every downstream stat
+    // (idf, avgdl, candidates, the per-scope partition below) then naturally
+    // reflects only the filtered set with no other code needing to know about it.
+    const graphNodes = inPrefix ? (graph?.nodes ?? []).filter((n) => pathUnderPrefix(n.path, inPrefix)) : (graph?.nodes ?? []);
+    const symbolDocs = graphNodes.map((n) => {
         const d = docById?.get(n.id);
         if (d)
             return { n, name: new Map(d.name), path: new Map(d.path), body: new Map(d.body) };
@@ -295,18 +344,25 @@ function lexical(query, corpus, limit, graphRank) {
     // IDF must see the SAME inputs either way: with a sidecar, its `df` (stored
     // WITHOUT concepts) plus these live concept bags reproduces exactly what
     // `computeIdf` below would compute from concept+symbol bags tokenized live.
-    const idf = askIndex
+    // `askIndex.df` is a corpus-GLOBAL count, so `--in` can't use it — the
+    // filtered doc set needs its own idf, computed from (already-filtered)
+    // `symbolDocs`' own bags, regardless of where those bags came from.
+    const idf = askIndex && !inPrefix
         ? computeIdfFromIndex(askIndex, conceptBags)
         : computeIdf([...conceptBags, ...symbolDocs.map((d) => new Set([...d.name.keys(), ...d.path.keys(), ...d.body.keys()]))]);
     // Per-hit idf-weighted coverage, kept out of the public AskHit shape; only
     // the top hit's value survives, as `coverage` on the result. The df=0 weight
     // mirrors idfFromDf's formula at df=0 for whichever corpus size idf was
-    // computed from.
-    const nDocs = askIndex
+    // computed from. Same `--in` reasoning as `idf` above: `askIndex.docCount`
+    // is global.
+    const nDocs = askIndex && !inPrefix
         ? askIndex.docCount + conceptBags.length
         : conceptBags.length + symbolDocs.length;
     const dfltIdf = Math.log(1 + nDocs);
     const matchedOf = new Map();
+    // Parallel to matchedOf, but over NAME+PATH only (body dropped) — the
+    // match-strength signal exported as `coverageStrong`.
+    const matchedStrongOf = new Map();
     // ── Concepts (prose nodes; not in the wiring graph) ──
     const conceptHits = [];
     let maxConcept = 0;
@@ -323,6 +379,7 @@ function lexical(query, corpus, limit, graphRank) {
                 score: total,
             };
             matchedOf.set(hit, matchedIdfShare(q, [name, body], idf, dfltIdf));
+            matchedStrongOf.set(hit, matchedIdfShare(q, [name], idf, dfltIdf)); // concepts have no path field
             conceptHits.push(hit);
         }
     }
@@ -334,56 +391,159 @@ function lexical(query, corpus, limit, graphRank) {
             s += v;
         return s;
     };
-    const avgBodyLen = askIndex
-        ? askIndex.avgBodyLen
-        : symbolDocs.length
-            ? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length
-            : 0;
-    const lex = new Map(); // node id → lexical score (>0 only)
-    let maxLex = 0;
-    for (const { n, name, path, body } of symbolDocs) {
-        // Name and path are short identifiers → plain idf-weighted overlap; the body
-        // is length-normalized via BM25 so long definitions don't win on bulk.
-        const total = score(q, name, idf) * 3 +
-            score(q, path, idf) * 2 +
-            bm25(q, body, idf, bodyLen(body), avgBodyLen);
-        if (total > 0) {
-            lex.set(n.id, total);
-            maxLex = Math.max(maxLex, total);
-        }
-    }
-    // ── Graph-rank: let connectivity to the matched set reorder and rescue ──
-    const pr = graphRank && graph && lex.size > 0
-        ? personalizedPageRank(graph, lex)
-        : new Map();
-    // Candidate symbols = everything the query word-matched, plus nodes the walk
-    // found strongly central even without a word match (RESCUE_FLOOR).
-    const candidates = new Set(lex.keys());
-    for (const [id, p] of pr)
-        if (p >= RESCUE_FLOOR)
-            candidates.add(id);
     const docsById = new Map(symbolDocs.map((d) => [d.n.id, d]));
     const symbolHits = [];
-    for (const id of candidates) {
-        const n = byId.get(id);
-        if (!n)
-            continue;
-        const lexN = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
-        const blended = lexN + GRAPH_WEIGHT * (pr.get(id) ?? 0);
-        if (blended <= 0)
-            continue;
-        const hit = {
-            kind: "symbol",
-            title: `${n.name} · ${n.kind}`,
-            // A file node points at the whole file (locator, no span) so `--source`
-            // never inlines an entire file; symbol nodes keep their exact span.
-            pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
-            snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
-            score: blended,
-        };
-        const d = docsById.get(id);
-        matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);
-        symbolHits.push(hit);
+    // The single-vs-multi-scope branch keys on `scopesOfGraph` ONLY: one scope
+    // (or no graph) takes the existing path below completely untouched — that
+    // branch is a byte-level regression guarantee for single-scope repos.
+    const scopes = graph ? scopesOfGraph(graph) : null;
+    let scopeMeta;
+    if (scopes && scopes.length > 1) {
+        // ── Multi-scope repo: rank each sub-project against its OWN corpus (its
+        // IDF, its BM25 length prior, its subgraph walk), then fuse the per-scope
+        // orderings by reciprocal rank — the big scope can't drown the small one.
+        // Same scoring functions and blend as the single-scope path, just fed
+        // per-scope inputs; the fusion itself lives in fuse.ts. ──
+        const byScope = new Map();
+        for (const d of symbolDocs) {
+            const s = scopeOf(d.n.path, scopes).prefix;
+            const list = byScope.get(s);
+            if (list)
+                list.push(d);
+            else
+                byScope.set(s, [d]);
+        }
+        const idfOf = new Map();
+        const fusion = rankScopesAndFuse([...byScope.keys()].sort(), {
+            lex: (s) => {
+                const docs = byScope.get(s);
+                // Per-scope IDF/BM25 stats: concepts are repo-level so their bags
+                // fold in everywhere, symbol bags come from this scope only. (The
+                // build sidecar's df/avgBodyLen are corpus-global, so multi-scope
+                // always computes these live — from the sidecar's own token maps.)
+                const sIdf = computeIdf([
+                    ...conceptBags,
+                    ...docs.map((d) => new Set([...d.name.keys(), ...d.path.keys(), ...d.body.keys()])),
+                ]);
+                idfOf.set(s, { idf: sIdf, dflt: Math.log(1 + conceptBags.length + docs.length) });
+                const avg = docs.reduce((a, d) => a + bodyLen(d.body), 0) / docs.length;
+                const out = new Map();
+                for (const { n, name, path, body } of docs) {
+                    const total = score(q, name, sIdf) * 3 +
+                        score(q, path, sIdf) * 2 +
+                        bm25(q, body, sIdf, bodyLen(body), avg);
+                    if (total > 0)
+                        out.set(n.id, total);
+                }
+                return out;
+            },
+            // The participation gate's match-STRENGTH signal, evaluated once per
+            // scope on that scope's raw-lex top doc — same `strongShare`/
+            // `matchedIdfShare` functions and per-scope idf `lex` (above) just
+            // computed, so this reads the SAME strength `federateAsk` gates on
+            // (see fuse.ts's STRONG_FLOOR/HIGH_FLOOR).
+            strength: (s, id) => {
+                const d = docsById.get(id);
+                const si = idfOf.get(s);
+                if (!d || !si)
+                    return { coverage: 0, coverageStrong: 0 };
+                return {
+                    coverage: matchedIdfShare(q, [d.name, d.path, d.body], si.idf, si.dflt),
+                    coverageStrong: strongShare(q, d.n, d, si.idf, si.dflt),
+                };
+            },
+            walk: (s, seeds) => graphRank
+                ? personalizedPageRank(graph, seeds, {
+                    nodeFilter: (id) => {
+                        const path = byId.get(id)?.path ?? "";
+                        return scopeOf(path, scopes).prefix === s && (!inPrefix || pathUnderPrefix(path, inPrefix));
+                    },
+                })
+                : new Map(),
+        }, GRAPH_WEIGHT, RESCUE_FLOOR);
+        for (const rd of fusion.ranked) {
+            const n = byId.get(rd.id);
+            if (!n)
+                continue;
+            const hit = {
+                kind: "symbol",
+                title: `${n.name} · ${n.kind}`,
+                pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
+                snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
+                score: rd.score,
+                scope: rd.scope,
+            };
+            const d = docsById.get(rd.id);
+            const si = idfOf.get(rd.scope);
+            matchedOf.set(hit, d && si ? matchedIdfShare(q, [d.name, d.path, d.body], si.idf, si.dflt) : 0);
+            matchedStrongOf.set(hit, d && si ? strongShare(q, n, d, si.idf, si.dflt) : 0);
+            symbolHits.push(hit);
+        }
+        // Label + footer only when federation actually happened (or a scope was
+        // gated out and is worth mentioning) — a query matching one scope of a
+        // multi-scope repo reads exactly like today.
+        if (fusion.federated.length > 1 || fusion.alsoMatched.length > 0)
+            scopeMeta = { federated: fusion.federated, alsoMatched: fusion.alsoMatched };
+    }
+    else {
+        // Single-scope: the pre-scopes ranking path, byte-identical output when
+        // `--in` is absent (Task 3's regression guarantee: `askIndex && !inPrefix`
+        // reduces to plain `askIndex` when `inPrefix` is undefined, so this line is
+        // a no-op change for every non-`--in` caller). Under `--in`, `askIndex`'s
+        // `avgBodyLen` is corpus-global and must not be reused for the filtered set.
+        const avgBodyLen = askIndex && !inPrefix
+            ? askIndex.avgBodyLen
+            : symbolDocs.length
+                ? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length
+                : 0;
+        const lex = new Map(); // node id → lexical score (>0 only)
+        let maxLex = 0;
+        for (const { n, name, path, body } of symbolDocs) {
+            // Name and path are short identifiers → plain idf-weighted overlap; the body
+            // is length-normalized via BM25 so long definitions don't win on bulk.
+            const total = score(q, name, idf) * 3 +
+                score(q, path, idf) * 2 +
+                bm25(q, body, idf, bodyLen(body), avgBodyLen);
+            if (total > 0) {
+                lex.set(n.id, total);
+                maxLex = Math.max(maxLex, total);
+            }
+        }
+        // ── Graph-rank: let connectivity to the matched set reorder and rescue ──
+        // `--in` restricts the walk itself, not just the seeds: without a nodeFilter
+        // here, a RESCUE_FLOOR-qualifying neighbour OUTSIDE the prefix could still
+        // surface, defeating the "filters before scoring" contract.
+        const pr = graphRank && graph && lex.size > 0
+            ? personalizedPageRank(graph, lex, inPrefix ? { nodeFilter: (id) => pathUnderPrefix(byId.get(id)?.path ?? "", inPrefix) } : {})
+            : new Map();
+        // Candidate symbols = everything the query word-matched, plus nodes the walk
+        // found strongly central even without a word match (RESCUE_FLOOR).
+        const candidates = new Set(lex.keys());
+        for (const [id, p] of pr)
+            if (p >= RESCUE_FLOOR)
+                candidates.add(id);
+        for (const id of candidates) {
+            const n = byId.get(id);
+            if (!n)
+                continue;
+            const lexN = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
+            const blended = lexN + GRAPH_WEIGHT * (pr.get(id) ?? 0);
+            if (blended <= 0)
+                continue;
+            const hit = {
+                kind: "symbol",
+                title: `${n.name} · ${n.kind}`,
+                // A file node points at the whole file (locator, no span) so `--source`
+                // never inlines an entire file; symbol nodes keep their exact span.
+                pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
+                snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
+                score: blended,
+            };
+            const d = docsById.get(id);
+            matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);
+            matchedStrongOf.set(hit, d ? strongShare(q, n, d, idf, dfltIdf) : 0);
+            symbolHits.push(hit);
+        }
     }
     // Concepts and symbols live on comparable 0..~1.5 scales so they merge fairly:
     // concept scores are normalized to their own max, symbol scores are the
@@ -396,8 +556,14 @@ function lexical(query, corpus, limit, graphRank) {
         query,
         mode: scored.length ? "lexical" : "empty",
         hits: scored.slice(0, limit),
+        scopes: scopeMeta,
         coverage: scored.length && q.size > 0 ? matchedOf.get(scored[0]) ?? 0 : undefined,
-        note: scored.length ? undefined : "no matching nodes — try different words, or `graft build` if graft/ is empty",
+        coverageStrong: scored.length && q.size > 0 ? matchedStrongOf.get(scored[0]) ?? 0 : undefined,
+        // Zero hits on a genuinely multi-scope graph names the scopes that exist,
+        // so a query that missed everywhere still tells the caller where to look.
+        note: scored.length
+            ? undefined
+            : `no matching nodes — try different words, or \`graft build\` if graft/ is empty${scopesHereClause(scopes ?? [])}`,
     };
 }
 /** Parse a `path:Lx-Ly` pointer into its parts, or null if it isn't one
@@ -475,20 +641,7 @@ function hitFiles(hits) {
 function baselineFor(hits, graph) {
     if (!graph)
         return undefined;
-    const size = new Map();
-    for (const n of graph.nodes)
-        if (n.kind === "file" && typeof n.chars === "number")
-            size.set(n.path, n.chars);
-    let baselineChars = 0;
-    let files = 0;
-    for (const path of hitFiles(hits)) {
-        const c = size.get(path);
-        if (c === undefined)
-            continue;
-        baselineChars += c;
-        files++;
-    }
-    return files > 0 ? { files, baselineChars } : undefined;
+    return savingsFor(graph, hitFiles(hits));
 }
 /** Answer a query from the graft/ graph at `dir`. Deterministic, $0. */
 export function ask(dir, query, opts = {}) {
@@ -497,14 +650,26 @@ export function ask(dir, query, opts = {}) {
     const limit = opts.limit ?? 8;
     const corpus = loadCorpus(outDir);
     const graphRank = opts.graphRank ?? true;
+    // Trailing slash(es) stripped ONCE, up front, and this normalized value used
+    // everywhere below (validation, filtering, structural). `ask --in frontend/`
+    // must work exactly like `--in frontend` — `scopeLabel`/the footer's own
+    // `--in <scope>/` suggestion always includes the slash, so rejecting it
+    // would make the tool's own suggested next command fail.
+    const inPrefix = opts.in ? opts.in.replace(/\/+$/, "") : undefined;
+    // `--in` validated up front, before any mode runs: a prefix matching no
+    // indexed node is a caller mistake (typo, wrong sub-project), not a
+    // legitimate zero-hit query, so it's a loud error rather than an empty pack.
+    if (inPrefix && corpus.graph && !corpus.graph.nodes.some((n) => pathUnderPrefix(n.path, inPrefix))) {
+        throw new Error(`nothing indexed under "${inPrefix}/"${scopesHereClause(scopesOfGraph(corpus.graph))} (or any path prefix)`);
+    }
     let result;
     if (corpus.graph) {
-        const outcome = structural(query, corpus.graph, limit);
+        const outcome = structural(query, corpus.graph, limit, inPrefix);
         if (outcome && "result" in outcome) {
             result = outcome.result;
         }
         else {
-            result = lexical(query, corpus, limit, graphRank);
+            result = lexical(query, corpus, limit, graphRank, inPrefix);
             // A structural-intent query that couldn't be answered structurally still
             // gets a prominent note on the lexical fallback result — never silent.
             if (outcome && "fallthroughNote" in outcome) {
@@ -513,7 +678,7 @@ export function ask(dir, query, opts = {}) {
         }
     }
     else {
-        result = lexical(query, corpus, limit, graphRank);
+        result = lexical(query, corpus, limit, graphRank, inPrefix);
     }
     if (opts.source) {
         inlineSource(root, result.hits, corpus.graph, opts.full ?? false);
@@ -553,6 +718,7 @@ export function skeleton(dir, file, opts = {}) {
             signature: n.signature,
             summary: n.summary?.split("\n")[0].trim() || undefined,
         })),
+        saved: savingsFor(graph, [defs[0].path]),
     };
 }
 /** Render a {@link SkeletonResult} as compact markdown. */
@@ -565,7 +731,8 @@ export function formatSkeleton(r) {
         const sum = e.summary ? ` — ${e.summary}` : "";
         return `- ${e.span}  ${e.kind} ${e.name}${sig}${sum}`;
     });
-    return `${head}\n${lines.join("\n")}\n`;
+    const body = `${head}\n${lines.join("\n")}`;
+    return body + savingsFooter(body, r.saved) + "\n";
 }
 /** Rough tokens for a byte length (≈ 4 chars/token; good enough for an estimate). */
 function toTokens(chars) {
@@ -602,7 +769,10 @@ export function formatAsk(r) {
     }
     else {
         r.hits.forEach((h, i) => {
-            lines.push(`${i + 1}. ${h.title}  [${h.kind}]`);
+            // Multi-scope results label each hit with its sub-project (root scope
+            // "" stays unlabeled) so a reviewer can tell WHICH codebase answered.
+            const label = r.scopes && h.scope ? `[${h.scope}/] ` : "";
+            lines.push(`${i + 1}. ${label}${h.title}  [${h.kind}]`);
             lines.push(`   ${h.pointer}`);
             if (h.snippet)
                 lines.push(`   ${h.snippet}`);
@@ -612,9 +782,10 @@ export function formatAsk(r) {
                 lines.push("", "```", h.code, "```");
             lines.push("");
         });
+        lines.push(...scopeFooterLines(r));
     }
     const body = lines.join("\n").trimEnd();
-    return body + savingsFooter(r, body) + escalationNudge(r) + "\n";
+    return body + askSavingsFooter(r, body) + escalationNudge(r) + "\n";
 }
 /** When a lexical `ask` returns thin/no results, the productive next move is a
  * different TOOL, not a re-phrased ask — re-asking is the "over-ask" trap that
@@ -631,7 +802,7 @@ function escalationNudge(r) {
 /** The one-line token-saving estimate `ask` appends in retriever mode, so the
  * agent gets the number for free in the tool output — no extra work on its end.
  * `packChars` is measured from the rendered body: exactly what the agent reads. */
-function savingsFooter(r, body) {
+function askSavingsFooter(r, body) {
     if (!r.saved || r.saved.baselineChars <= 0)
         return "";
     const pack = toTokens(body.length);
@@ -644,4 +815,24 @@ function savingsFooter(r, body) {
         `${pack.toLocaleString()} tok vs reading the ${r.saved.files} source file(s) whole ≈ ` +
         `${base.toLocaleString()} tok. Estimate (baseline = those files read in full).`);
 }
+/** Multi-scope footer: answers a reviewer's two questions — "which
+ * sub-projects did this pack come from?" (`matched in:`, displayed-hit counts,
+ * biggest first) and "did anything else match that I should know about?"
+ * (`also matched:` for scopes gated out of fusion, with the flag to narrow).
+ * Empty (zero output) whenever the result isn't a federated multi-scope one. */
+function scopeFooterLines(r) {
+    if (!r.scopes)
+        return [];
+    const perScope = new Map();
+    for (const h of r.hits)
+        if (h.scope !== undefined)
+            perScope.set(h.scope, (perScope.get(h.scope) ?? 0) + 1);
+    const parts = [...perScope]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([s, c]) => `${scopeLabel(s)} (${c})`);
+    const out = parts.length ? [`matched in: ${parts.join(" · ")}`] : [];
+    for (const m of r.scopes.alsoMatched)
+        out.push(`also matched: ${scopeLabel(m.scope)} — narrow with --in ${scopeLabel(m.scope)}`);
+    return out;
+}
 //# sourceMappingURL=ask.js.map