@nanonets/graft 0.5.1 → 0.7.0

package/README.md

@@ -71,9 +71,11 @@ npx @nanonets/graft init
 ### MCP server
 
 `graft init` also registers Graft's MCP server with agents that support it, so
-`graft_ask`, `graft_check`, and `graft_blast_radius` appear as native tools —
-no shell required. Skip with `--no-mcp`. Run it manually with `graft mcp [dir]`,
-or register it by hand:
+`graft_ask`, `graft_callers`, `graft_grep`, `graft_skeleton`, `graft_map`, and
+`graft_check` appear as native tools — no shell required. Claude Code now gets
+this too: `graft init` writes the server into the project's `.mcp.json` (restart
+Claude Code to load it). Skip with `--no-mcp`. Run it manually with
+`graft mcp [dir]`, or register it by hand:
 
 ```json
 { "mcpServers": { "graft": { "command": "npx", "args": ["-y", "@nanonets/graft", "mcp"] } } }
@@ -187,10 +189,11 @@ graft build --extensions .ts .py     # only include these code extensions
 
 graft ask "<task>" [dir]             # query the graph — ranked nodes + exact file:line (no LLM, no key)
 graft ask "<task>" --json            # machine-readable result
+graft ask "<task>" --in <scope>      # narrow to one sub-project of a monorepo/multi-repo folder (see below)
 
 graft callers <symbol> [dir]         # who calls/references/imports/implements/extends a symbol (no LLM, no key)
-graft callees <symbol> [dir]         # what a symbol calls/references/imports/implements/extends (no LLM, no key)
-graft impact <symbol> [dir] -d N     # BFS over incoming edges — who breaks if this symbol changes (no LLM, no key)
+graft callers <symbol> --direction out  # the reverse: what the symbol itself calls/references (was `graft callees`)
+graft callers <symbol> -d N          # walk transitively out to depth N — full blast radius (was `graft impact`)
 
 graft grep "<regex>" [dir]           # exhaustive regex search over indexed files, grouped by enclosing symbol (no LLM, no key)
 graft grep "<regex>" --in <path>     # narrow to files whose path contains this substring
@@ -205,7 +208,7 @@ graft check --json                   # print the drift report as JSON
 graft viz [dir]                      # see the graph: serves an interactive viewer on localhost
 graft viz --port 5000 --no-open      # pick a port; don't auto-open the browser
 
-graft init [dir]                     # wire Graft into the coding agents detected in this repo (Claude Code always gets full hooks + statusline)
+graft init [dir]                     # wire Graft into the coding agents detected in this repo (Claude Code always gets full hooks + statusline + MCP)
 graft init --no-build                # wire the files only; don't build the graph
 graft init --agents cursor kiro      # wire only these agents (ids: agents, cursor, gemini, copilot, kiro, windsurf, claude)
 graft init --all-agents              # wire every known agent, detected or not
@@ -221,7 +224,7 @@ graft --version, -v                  # print the installed version and exit
 
 Method calls resolve through the receiver's type — constructor assignments
 (`self.router = APIRouter()`) and type annotations, not just the call-site
-name — so `callers`/`impact`/`grep --in` return calls bound to the right
+name — so `callers`/`grep --in` return calls bound to the right
 type on method-heavy code, not every method anywhere with that name.
 
 ## Search & orient (`graft grep` / `graft map`)
@@ -257,6 +260,25 @@ scripts/            2 files · 0 symbols
 hotspots: set · method · src/graph/bindings.ts:L21-L23 · 38←  contextDirFor · function · src/context/node-file.ts:L100-L103 · 11←  wiringPath · function · src/graph/write.ts:L20-L22 · 10←  ...
 ```
 
+## Monorepos & multi-repo folders
+
+Graft handles two shapes without any config:
+
+- **A monorepo with one `.git`** (a `pnpm-workspace.yaml`/`package.json`
+  `workspaces`, or per-package `go.mod`/`pyproject.toml`/`Cargo.toml`) —
+  `graft build` discovers each sub-project as a ranking scope. `ask`/`map`
+  rank every scope on its own terms and fuse the results, so the biggest
+  sub-project can't drown a small one; hits carry `[scope/]` labels, and
+  `graft map` groups its directory clusters by scope first.
+- **A folder of separate git repos** (no `.git` at the top) — `graft build`
+  auto-splits: each child keeps its own committable `graft/`, and the parent
+  gets a `graft/workspace.json` index. Queries from the parent federate across
+  every child, always labeled `<child>/`. Run `graft build` inside a child to
+  work on just that repo.
+
+Either way, narrow to one sub-project with `graft ask "<task>" --in <scope>/`
+once you know where you're working.
+
 ## Visualize it (`graft viz`)
 
 `graft viz` opens a local, interactive view of both graphs — no install, no dev

package/dist/ask/ask.d.ts

@@ -1,4 +1,5 @@
-import type { Relation } from "../graph/types.js";
+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;
@@ -12,6 +13,10 @@ export interface AskHit {
      * 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;
 }
 export interface AskResult {
     query: string;
@@ -33,7 +38,45 @@ export interface AskResult {
      * 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;
+        }[];
+    };
 }
+/** 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;
@@ -50,6 +93,12 @@ export interface AskOptions {
      * 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;
 }
 /** Answer a query from the graft/ graph at `dir`. Deterministic, $0. */
 export declare function ask(dir: string, query: string, opts?: AskOptions): AskResult;
@@ -65,6 +114,8 @@ 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).

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

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/ask/ask.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAA2B,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAI3E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd;;qFAEiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;IACzC,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;sFAEkF;IAClF,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;oFAIgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2aD,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;qFACiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;sFAEkF;IAClF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;6EAIyE;IACzE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAsFD,wEAAwE;AACxE,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,SAAS,CA8BhF;AAID,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;2EAE2E;AAC3E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,cAAc,CA6BtG;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CASxD;AAOD,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAsC9C"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/ask/ask.ts"],"names":[],"mappings":"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"}