ts-axi 0.1.12 → 0.1.13

package/README.md

@@ -82,7 +82,8 @@ The hook runs `ts-axi` with no arguments: it reads only the file tree and git st
 | `refs <target>` | References of one symbol, grouped by file, with test counts. A class member that implements an interface (or overrides a base) member counts only its direct References; calls through the interface are `via_interface: n (Iface.member)`, sibling implementations are dropped, and an interface member reports `implementations: n`. `--limit`, `--kind calls`, `--via` (via rows with a `via` column), `--implementations` |
 | `callers <target>` | Incoming calls of a function-like symbol, split the same way (`via_interface`, `--via`). `--depth 1..3` |
 | `outline <file>` | Top-level declarations in source order, class members nested: `{line,kind,name,signature}` (`{at,kind,name,signature}` over several files). `--exports`, `--fields exported` |
-| `impact [<git-range> \| -]` | Declarations changed by the working tree (untracked files included; `--staged`), a git range (`main...HEAD`) or a unified diff on stdin (`bb-axi pr diff 42 --raw \| ts-axi impact -`), riskiest first: change class (`signature`, `removed`, `type`, `added`, `body`, `modified`), References outside the change set (direct only), a `via` count of calls through an interface or base member (`--via` lists them), test-file counts, `notes` (a signature change of a member that implements an interface member), `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Rows default to `{symbol,change,at,refs_outside}`; `--fields kind,exported,refs_total,via,files,tests` (or `all`) adds columns. Analyses the current checkout |
+| `impact [<git-range> \| -]` | Declarations changed by the working tree (untracked files included; `--staged`), a git range (`main...HEAD`) or a unified diff on stdin (`bb-axi pr diff 42 --raw \| ts-axi impact -`), riskiest first: change class (`signature`, `removed`, `type`, `added`, `body`, `modified`), References outside the change set (direct only), a `via` count of calls through an interface or base member (`--via` lists them), test-file counts, `notes` (a signature change of a member that implements an interface member), `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Rows default to `{symbol,change,at,refs_outside}`; `--fields kind,exported,refs_total,via,files,tests` (or `all`) adds columns. `--size` adds a `size` block (files, hunks at zero context, lines added and removed, patch characters, exported signature changes, removed symbols) for routing a review by diff size. Analyses the current checkout |
+| `anchor [<git-range> \| - \| --staged] <file:line[-end]>...` | Checks review-comment anchors: a line is commentable when the diff shows it (added or context; removed or context with `--side old`). Rows are `{anchor,ok,reason,symbol}`: a reason with the nearest hunk when not, and the enclosing Declaration (`Cart.total#method`) as a stable key for the finding. Git sources diff at `--context 3` (what Bitbucket and GitHub show); a stdin diff is used as given. `--fields in_diff,in_file,nearest,change,other_line` (or `all`). Exit 3 when any anchor is not ok, with the full output |
 | `config` | Show effective settings with their source; `config set <key> <value>` and `config unset <key>` write `.ts-axi.json` |
 | `setup <hooks\|status\|uninstall>` | Opt-in SessionStart hook for Claude Code, Codex and OpenCode that runs the home view at session start. `--project` for the current repository only |
 
@@ -149,6 +150,30 @@ help[4]:
   ...
 ```
 
+### Anchoring review comments
+
+An inline comment only lands when the review tool shows its line in the diff. Check the anchors against the diff the tool renders before posting:
+
+```sh
+bb-axi pr diff 42 --raw | ts-axi anchor - src/a.ts:12 src/b.ts:40-44
+```
+
+```
+base: stdin diff
+head: working tree
+side: new
+anchors[2]{anchor,ok,reason,symbol}:
+  "src/a.ts:12",true,"-",Cart.total#method
+  "src/b.ts:40-44",false,not in diff - nearest 51-58,formatPrice#function
+invalid: 1
+help[3]:
+  - "Move src/b.ts:40-44 into src/b.ts:51-58 or post it as a general comment"
+  - exit 3 (ANCHOR_INVALID) - 1 of 2 anchors cannot be commented; fix or drop them before posting
+  - "Run `<diff> | ts-axi anchor - src/b.ts:40-44 --fields all` for in_diff, in_file, nearest, change and other_line"
+```
+
+The exit code is 3 when any anchor is not commentable, so a script can gate on it. `--side old` checks lines of the before file (comments on removed lines); a new-side anchor on a removed line says `removed line - use --side old`. With a stdin diff, `symbol` and `in_file` come from the working tree, so check out the PR head first; a mismatch is reported as a warning.
+
 ### Interfaces are not conflated
 
 `findReferences` in the compiler resolves a call like `parser.parse(raw)` (with `parser: FieldParser`) to every implementation of `parse`, and lists the other implementations' declarations as references. For a review that inflates the blast radius badly. ts-axi keeps the split:

package/dist/src/anchor.js

@@ -0,0 +1,113 @@
+import { usageError } from "./errors.js";
+const ANCHOR = /^(.+):(\d+)(?:-(\d+))?$/;
+const WITH_COLUMN = /^.+:\d+:\d+$/;
+/** `path:line` or `path:start-end`; `path:line:col` counts too, so it gets a precise error. */
+export function looksLikeAnchor(value) {
+    return value !== "-" && (ANCHOR.test(value) || WITH_COLUMN.test(value));
+}
+export function parseAnchor(raw) {
+    if (WITH_COLUMN.test(raw)) {
+        throw usageError(`anchor '${raw}' has a column - anchors are file:line or file:start-end`, [`Use ${raw.replace(/:\d+$/, "")}`]);
+    }
+    const m = ANCHOR.exec(raw);
+    if (!m)
+        throw usageError(`'${raw}' is not an anchor - expected file:line or file:start-end`);
+    const start = Number(m[2]);
+    const end = m[3] === undefined ? start : Number(m[3]);
+    if (start < 1)
+        throw usageError(`anchor '${raw}' - lines start at 1`);
+    if (end < start)
+        throw usageError(`anchor '${raw}' ends before it starts`, [`Use ${m[1]}:${end}-${start}`]);
+    return { raw, path: m[1].replace(/^\.\//, ""), start, end };
+}
+export function sideMap(file, side) {
+    const shown = new Map();
+    const hunks = new Map();
+    file.hunks.forEach((h, i) => {
+        const own = side === "new" ? h.added : h.removed;
+        for (const l of own)
+            shown.set(l.line, { hunk: i, kind: side === "new" ? "added" : "removed" });
+        for (const c of h.context) {
+            const [line, other] = side === "new" ? [c.newLine, c.oldLine] : [c.oldLine, c.newLine];
+            shown.set(line, { hunk: i, kind: "context", other });
+        }
+        const lines = [...own.map((l) => l.line), ...h.context.map((c) => (side === "new" ? c.newLine : c.oldLine))];
+        if (lines.length > 0)
+            hunks.set(i, [Math.min(...lines), Math.max(...lines)]);
+    });
+    return { shown, hunks };
+}
+/** Line count as an editor shows it: split on `\n` only, a trailing newline ends the last line. */
+export function lineCount(text) {
+    if (text === "")
+        return 0;
+    return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+export function formatSpan([a, b]) {
+    return a === b ? String(a) : `${a}-${b}`;
+}
+/** The closest range to [start, end]; ties go to the earlier one. */
+export function nearestRange(ranges, start, end) {
+    let best;
+    let bestDistance = Infinity;
+    for (const r of ranges) {
+        const distance = end < r[0] ? r[0] - end : start > r[1] ? start - r[1] : 0;
+        if (distance < bestDistance) {
+            best = r;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/**
+ * Judge one anchor against its file's diff. `lines` = line count of the chosen side's text
+ * (undefined when unknown). Every line of a range must be shown, in a single hunk.
+ */
+export function judge(anchor, file, side, lines) {
+    if (!file)
+        return { ok: false, reason: "file not in diff", inDiff: false, inFile: undefined };
+    if (file.binary)
+        return { ok: false, reason: "binary", inDiff: false, inFile: undefined };
+    const inFile = lines === undefined ? undefined : anchor.end <= lines;
+    if (side === "old" && file.status === "added")
+        return { ok: false, reason: "file added - use --side new", inDiff: false, inFile: false };
+    const map = sideMap(file, side);
+    const hits = [];
+    for (let n = anchor.start; n <= anchor.end; n++) {
+        const hit = map.shown.get(n);
+        if (hit)
+            hits.push(hit);
+    }
+    const span = anchor.end - anchor.start + 1;
+    const first = hits[0];
+    if (first && hits.length === span && hits.every((h) => h.hunk === first.hunk)) {
+        return { ok: inFile !== false, reason: inFile === false ? `past end of file (${lines} lines)` : "-", inDiff: true, inFile, ...(first.other !== undefined ? { otherLine: first.other } : {}) };
+    }
+    if (first) {
+        const nearest = formatSpan(map.hunks.get(first.hunk));
+        return { ok: false, reason: `crosses hunk boundary - hunk ${nearest}`, inDiff: false, inFile, nearest };
+    }
+    const otherSide = sideMap(file, side === "new" ? "old" : "new").shown.get(anchor.start);
+    if (side === "new" && otherSide?.kind === "removed")
+        return { ok: false, reason: "removed line - use --side old", inDiff: false, inFile };
+    if (side === "old" && otherSide?.kind === "added")
+        return { ok: false, reason: "added line - use --side new", inDiff: false, inFile };
+    if (side === "new" && file.status === "deleted")
+        return { ok: false, reason: "file deleted - use --side old", inDiff: false, inFile: false };
+    if (inFile === false)
+        return { ok: false, reason: `past end of file (${lines} lines)`, inDiff: false, inFile };
+    const near = nearestRange([...map.hunks.values()], anchor.start, anchor.end);
+    if (!near)
+        return { ok: false, reason: `not in diff - no ${side}-side lines in this file`, inDiff: false, inFile };
+    const nearest = formatSpan(near);
+    return { ok: false, reason: `not in diff - nearest ${nearest}`, inDiff: false, inFile, nearest };
+}
+/** Smallest Declaration spanning the whole range. */
+export function enclosing(decls, start, end) {
+    let best;
+    for (const d of decls) {
+        if (d.line <= start && end <= d.endLine && (!best || d.endLine - d.line < best.endLine - best.line))
+            best = d;
+    }
+    return best;
+}

package/dist/src/cli.js

@@ -1,4 +1,5 @@
 import { runAxiCli } from "axi-sdk-js";
+import { anchorCommand, ANCHOR_HELP } from "./commands/anchor.js";
 import { configCommand, CONFIG_HELP } from "./commands/config.js";
 import { defCommand, DEF_HELP } from "./commands/def.js";
 import { homeCommand } from "./commands/home.js";
@@ -13,8 +14,8 @@ import { out, renderErrorOutput, setHintRef, setJsonMode, toJson } from "./rende
 import { VERSION } from "./version.js";
 export const DESCRIPTION = "TypeScript/JavaScript symbol CLI for agents - definitions, references, callers, file outlines and change impact (what a diff affects) from the TypeScript compiler. Prefer it over grep for 'who uses this'.";
 export const TOP_HELP = `usage: ts-axi [command] [args] [flags]
-commands[8]:
-  (none)=project overview, def, refs, callers, outline, impact, config, setup (opt-in session hooks)
+commands[9]:
+  (none)=project overview, def, refs, callers, outline, impact, anchor (is a review comment's file:line in the diff), config, setup (opt-in session hooks)
 targets:
   name (save), member (User.save) or position (src/a.ts:42 or src/a.ts:42:7)
 flags[5]:
@@ -27,6 +28,7 @@ examples:
   ts-axi refs User.save --ref origin/main
   ts-axi outline src/models/user.ts
   ts-axi impact main...HEAD
+  bb-axi pr diff 42 --raw | ts-axi anchor - src/a.ts:12
   ts-axi refs --help
 `;
 const COMMAND_HELP = {
@@ -35,6 +37,7 @@ const COMMAND_HELP = {
     callers: CALLERS_HELP,
     outline: OUTLINE_HELP,
     impact: IMPACT_HELP,
+    anchor: ANCHOR_HELP,
     config: CONFIG_HELP,
     setup: SETUP_HELP,
 };
@@ -80,12 +83,13 @@ export async function main(options = {}) {
                 callers: command("callers", callersCommand, ctx),
                 outline: command("outline", outlineCommand, ctx),
                 impact: command("impact", impactCommand, ctx),
+                anchor: command("anchor", anchorCommand, ctx),
                 config: command("config", configCommand, ctx),
                 setup: command("setup", (args) => setupCommand(args), ctx),
             },
             getCommandHelp: (name) => COMMAND_HELP[name],
             renderUnknownCommand: (name) => `${renderErrorOutput(`unknown command '${name}'`, "VALIDATION_ERROR", [
-                "commands: def, refs, callers, outline, impact, config, setup (no command = project overview)",
+                "commands: def, refs, callers, outline, impact, anchor, config, setup (no command = project overview)",
                 "Run `ts-axi --help` for examples",
             ])}\n`,
             formatError,

package/dist/src/commands/anchor.js

@@ -0,0 +1,250 @@
+import { join, relative, sep } from "node:path";
+import { enclosing, judge, lineCount, looksLikeAnchor, parseAnchor } from "../anchor.js";
+import { bool, enumFlag, flag, intFlag, parseArgs, parseFields } from "../args.js";
+import { changedRanges, headRevOfRange, parseUnifiedDiff } from "../diff.js";
+import { ANCHOR_INVALID_EXIT, AxiError, usageError } from "../errors.js";
+import { sourceFs } from "../fs.js";
+import { diffUnified, isGitRepo, resolveBaseRev, showFile, untrackedFiles } from "../git.js";
+import { classifyFile, liftTypeLevel, matchKey, reverseApply } from "../impact.js";
+import { findRepoRoot, parseSource, SOURCE_EXTENSIONS } from "../project.js";
+import { block, helpBlock, out } from "../render.js";
+import { collectDeclarations } from "../symbols.js";
+import { readStdin, shellWord } from "./impact.js";
+const DEFAULT_CONTEXT = 3;
+const MAX_CONTEXT = 1000;
+const STDIN_EXAMPLE = "bb-axi pr diff 42 --raw | ts-axi anchor - src/a.ts:12";
+export const ANCHOR_HELP = `usage: ts-axi anchor [<git-range> | - | --staged] <file:line[-end]>... [flags]
+checks review-comment anchors: a line is commentable when the diff shows it (an added or context line; removed or context with --side old)
+input:
+  (none) = working tree vs HEAD; --staged = index vs HEAD; <git-range> = any git diff range (main...HEAD)
+  - = unified diff on stdin, used as given - the path for PR review (${STDIN_EXAMPLE})
+  the diff source comes first; anchors are repo-relative file:line or file:start-end (every line of a range must be shown, in one hunk)
+flags[5]:
+  --side new|old (default new; old = lines of the before file - comments on removed lines), --context <0-${MAX_CONTEXT}> (git sources only; default ${DEFAULT_CONTEXT} like Bitbucket and GitHub), --staged, --fields <in_diff,in_file,nearest,change,other_line|all>, --json
+output:
+  base, head, side, anchors[n]{anchor,ok,reason,symbol}, invalid (count)
+  reason = - when ok; else not in diff - nearest <a-b> | past end of file (<n> lines) | removed line - use --side old | crosses hunk boundary - hunk <a-b> | file not in diff | binary
+  symbol = qualifiedName#kind of the innermost Declaration holding the line (a stable key for a finding); file_level outside any; - for non-TS/JS files
+  in_diff = the line is shown in a hunk; in_file = within the line count of that side; nearest = lines of the closest hunk on that side
+  change = impact class of that Symbol in this diff (signature, body, added, ...) or -; other_line = the same line on the other side (context lines) or -
+exit codes:
+  0 every anchor ok; 3 ANCHOR_INVALID = at least one is not (the full output still prints); 2 usage; 1 git
+examples[4]:
+  ${STDIN_EXAMPLE} src/b.ts:40-44
+  ts-axi anchor main...HEAD src/a.ts:12
+  ts-axi anchor --staged src/a.ts:12 --fields all
+  ts-axi anchor main...HEAD src/a.ts:30 --side old
+`;
+const SPECS = [
+    { name: "--staged", boolean: true },
+    { name: "--side" },
+    { name: "--context" },
+    { name: "--fields" },
+];
+const ANCHOR_FIELDS = ["in_diff", "in_file", "nearest", "change", "other_line"];
+function isSourcePath(path) {
+    return SOURCE_EXTENSIONS.some((ext) => path.endsWith(ext));
+}
+/** Positionals -> diff source + anchors; the source is first when it is `-` or no file:line. */
+function split(positionals, staged) {
+    const [first, ...rest] = positionals;
+    const source = first !== undefined && (first === "-" || !looksLikeAnchor(first)) ? first : undefined;
+    const anchors = source === undefined ? positionals : rest;
+    const stray = anchors.find((a) => !looksLikeAnchor(a));
+    if (stray !== undefined) {
+        const valid = anchors.filter(looksLikeAnchor);
+        throw usageError(`'${stray}' is not an anchor - expected file:line or file:start-end`, [
+            `the diff source goes first: \`ts-axi anchor ${shellWord(stray)} ${valid.map(shellWord).join(" ") || "src/a.ts:12"}\``,
+        ]);
+    }
+    if (staged && source !== undefined)
+        throw usageError("--staged cannot be combined with a range or -", [`Run \`ts-axi anchor --staged ${anchors.map(shellWord).join(" ")}\``]);
+    if (anchors.length === 0) {
+        throw usageError("no anchors given", [`Run \`ts-axi anchor ${source !== undefined ? `${shellWord(source)} ` : ""}src/a.ts:12\` (file:line or file:start-end)`]);
+    }
+    return { source, anchors };
+}
+export async function anchorCommand(args, ctx) {
+    const parsed = parseArgs(args, SPECS, "ts-axi anchor");
+    const staged = bool(parsed, "--staged");
+    const side = enumFlag(parsed, "--side", ["new", "old"], "new");
+    const extras = new Set(parseFields(flag(parsed, "--fields"), ANCHOR_FIELDS));
+    const { source: arg, anchors: rawAnchors } = split(parsed.positionals, staged);
+    if (arg === "-" && flag(parsed, "--context") !== undefined) {
+        throw usageError("--context applies to git diffs - a stdin diff is used as given", [`Run \`${STDIN_EXAMPLE}\``]);
+    }
+    const context = intFlag(parsed, "--context", DEFAULT_CONTEXT, { min: 0, max: MAX_CONTEXT });
+    const anchors = rawAnchors.map(parseAnchor);
+    const root = findRepoRoot(ctx.cwd);
+    let text;
+    let source;
+    if (arg === "-") {
+        text = ctx.stdin ?? (await readStdin("anchor", STDIN_EXAMPLE));
+        source = { kind: "stdin", base: "stdin diff", head: "working tree" };
+    }
+    else {
+        if (!(await isGitRepo(ctx.cwd))) {
+            throw new AxiError("not a git repository - anchor needs git or a diff on stdin", "GIT_ERROR", [`Run \`${STDIN_EXAMPLE}\``]);
+        }
+        text = await diffUnified(ctx.cwd, arg, staged, context);
+        const headRev = arg !== undefined ? headRevOfRange(arg) : undefined;
+        source = staged
+            ? { kind: "staged", base: "HEAD", head: "index" }
+            : arg === undefined
+                ? { kind: "worktree", base: "HEAD", head: "working tree" }
+                : { kind: "range", range: arg, base: await resolveBaseRev(ctx.cwd, arg), head: headRev ?? "working tree" };
+    }
+    const files = parseUnifiedDiff(text, { binary: true });
+    // Untracked files are wholly added in a working-tree diff (as in impact).
+    let untracked;
+    const findFile = async (path) => {
+        const hit = files.find((f) => (side === "old" ? (f.oldPath ?? f.path) === path : f.path === path)) ?? files.find((f) => f.path === path || f.oldPath === path);
+        if (hit || source.kind !== "worktree")
+            return hit;
+        untracked ??= new Set(await untrackedFiles(ctx.cwd));
+        if (!untracked.has(path))
+            return undefined;
+        const body = sourceFs().readFile(join(root, path)) ?? "";
+        const n = lineCount(body);
+        const added = Array.from({ length: n }, (_, i) => ({ line: i + 1, text: "" }));
+        const file = { path, oldPath: undefined, status: "added", hunks: n > 0 ? [{ oldStart: 0, oldLines: 0, newStart: 1, newLines: n, removed: [], added, context: [] }] : [] };
+        files.push(file);
+        return file;
+    };
+    // An anchor relative to a subdirectory cwd, or carrying an a/ or b/ prefix, still finds its file.
+    const prefix = relative(root, ctx.cwd).split(sep).join("/");
+    const resolveFile = async (anchor) => {
+        const candidates = [anchor.path, ...(prefix && !prefix.startsWith("..") ? [`${prefix}/${anchor.path}`] : []), ...(/^[ab]\//.test(anchor.path) ? [anchor.path.slice(2)] : [])];
+        for (const c of candidates) {
+            const f = await findFile(c);
+            if (f)
+                return f;
+        }
+        return undefined;
+    };
+    // --- Both sides of a file, read once ---
+    const worktree = (path) => sourceFs().readFile(join(root, path)) ?? null;
+    const texts = new Map();
+    let mismatched = 0;
+    const textsOf = (f) => {
+        let entry = texts.get(f);
+        if (!entry) {
+            entry = (async () => {
+                if (f.binary)
+                    return { after: undefined, before: undefined };
+                let after;
+                if (f.status === "deleted")
+                    after = null;
+                else if (source.kind === "staged")
+                    after = await showFile(ctx.cwd, "", f.path);
+                else if (source.kind === "range" && source.head !== "working tree")
+                    after = await showFile(ctx.cwd, source.head, f.path);
+                else
+                    after = worktree(f.path);
+                let before;
+                if (source.kind === "stdin") {
+                    // The checkout must be the diff's after side; otherwise both texts are unknown. A deleted file's hunks hold all of it.
+                    const reversed = reverseApply(after ?? "", f.hunks);
+                    if (reversed === null) {
+                        mismatched++;
+                        after = undefined;
+                    }
+                    before = f.status === "added" ? null : reversed ?? undefined;
+                }
+                else if (f.status === "added")
+                    before = null;
+                else
+                    before = await showFile(ctx.cwd, source.base, f.oldPath ?? f.path);
+                return { after, before };
+            })();
+            texts.set(f, entry);
+        }
+        return entry;
+    };
+    const decls = new Map();
+    const declsOf = (path, sideText, key) => {
+        let list = decls.get(key);
+        if (!list) {
+            list = collectDeclarations(parseSource(path, sideText), path);
+            decls.set(key, list);
+        }
+        return list;
+    };
+    const classified = new Map();
+    const changesOf = (f, after, before) => {
+        let result = classified.get(f);
+        if (!result) {
+            const { after: a, before: b } = changedRanges(f);
+            result = classifyFile({ path: f.path, ...(f.oldPath ? { oldPath: f.oldPath } : {}), status: f.status, after: a, before: b, afterText: after, beforeText: before });
+            classified.set(f, result);
+        }
+        return result;
+    };
+    const rows = [];
+    for (const anchor of anchors) {
+        const file = await resolveFile(anchor);
+        const { after, before } = file ? await textsOf(file) : { after: undefined, before: undefined };
+        const sideText = side === "new" ? after : before;
+        const lines = typeof sideText === "string" ? lineCount(sideText) : sideText === null ? 0 : undefined;
+        const verdict = judge(anchor, file, side, lines);
+        let symbol = "-";
+        let change = "-";
+        const sidePath = file ? (side === "old" ? (file.oldPath ?? file.path) : file.path) : anchor.path;
+        if (file && typeof sideText === "string" && verdict.inFile !== false && isSourcePath(sidePath)) {
+            const list = declsOf(sidePath, sideText, `${side}:${sidePath}`);
+            const decl = enclosing(list, anchor.start, anchor.end);
+            symbol = decl ? matchKey(decl) : "file_level";
+            if (decl) {
+                const key = matchKey(liftTypeLevel(list, decl));
+                change = changesOf(file, after, before).changes.find((c) => c.key === key)?.change ?? "-";
+            }
+        }
+        rows.push({ anchor, verdict, symbol, change });
+    }
+    const invalid = rows.filter((r) => !r.verdict.ok);
+    if (invalid.length > 0)
+        process.exitCode = ANCHOR_INVALID_EXIT;
+    const sourceWord = arg === "-" ? "-" : arg !== undefined ? shellWord(arg) : staged ? "--staged" : "";
+    const again = (rest) => `${arg === "-" ? "<diff> | " : ""}${["ts-axi anchor", sourceWord, rest, ...(flag(parsed, "--context") !== undefined ? [`--context ${context}`] : [])].filter(Boolean).join(" ")}`;
+    const help = [];
+    for (const r of invalid.slice(0, 3)) {
+        if (r.verdict.reason.startsWith("removed line"))
+            help.push(`Run \`${again(`${r.anchor.raw} --side old`)}\` - ${r.anchor.raw} is a removed line`);
+        else if (r.verdict.reason.startsWith("added line"))
+            help.push(`Run \`${again(r.anchor.raw)}\` - ${r.anchor.raw} is an added line on the new side`);
+        else if (r.verdict.nearest)
+            help.push(`Move ${r.anchor.raw} into ${r.anchor.path}:${r.verdict.nearest} or post it as a general comment`);
+    }
+    if (invalid.length > 0) {
+        help.push(`exit 3 (ANCHOR_INVALID) - ${invalid.length} of ${rows.length} anchors cannot be commented; fix or drop them before posting`);
+        if (extras.size === 0)
+            help.push(`Run \`${again(`${invalid.map((r) => shellWord(r.anchor.raw)).join(" ")} --fields all`)}\` for in_diff, in_file, nearest, change and other_line`);
+    }
+    else {
+        help.push("Every anchor is commentable - symbol is a stable key for each finding across pushes");
+    }
+    if (mismatched > 0)
+        help.push("Check out the diff's head commit so symbol and in_file come from the code the diff describes");
+    return out(block({
+        ...(mismatched > 0 ? { warning: `${mismatched} files in the stdin diff do not match the working tree - symbol and in_file unknown there` } : {}),
+        base: source.base,
+        head: source.head,
+        ...(source.kind !== "stdin" ? { context } : {}),
+        side,
+        anchors: rows.map(({ anchor, verdict, symbol, change }) => {
+            const full = {
+                anchor: anchor.raw,
+                ok: verdict.ok,
+                reason: verdict.reason,
+                symbol,
+                in_diff: verdict.inDiff,
+                in_file: verdict.inFile ?? "-",
+                nearest: verdict.nearest ?? "-",
+                change,
+                other_line: verdict.otherLine ?? "-",
+            };
+            return Object.fromEntries(Object.entries(full).filter(([k]) => !ANCHOR_FIELDS.includes(k) || extras.has(k)));
+        }),
+        invalid: invalid.length,
+    }), helpBlock(help));
+}

package/dist/src/commands/impact.js

@@ -3,7 +3,7 @@ import { sourceFs } from "../fs.js";
 import { basename, dirname, join, relative, sep } from "node:path";
 import ts from "typescript";
 import { bool, flag, intFlag, parseArgs, parseFields } from "../args.js";
-import { changedRanges, parseUnifiedDiff } from "../diff.js";
+import { changedRanges, headRevOfRange, parseUnifiedDiff } from "../diff.js";
 import { AxiError, usageError } from "../errors.js";
 import { diffNameStatus, diffUnified, isGitRepo, resolveBaseRev, showFile, untrackedFiles } from "../git.js";
 import { allocateBudget, classifyFile, compareChanges, formatRanges, inRanges, localOnlyLine, matchKey, reverseApply, wordMatches, } from "../impact.js";
@@ -25,8 +25,8 @@ input:
   (none) = working tree vs HEAD (staged + unstaged + untracked); --staged = index vs HEAD
   <git-range> = any git diff range (main...HEAD, abc123, v1..v2); - = unified diff on stdin (needs the after side checked out)
   analysis is of the current checkout - for a range whose head is not the working tree, check that head out first
-flags[8]:
-  --staged, --via (adds References through an interface or base member to refs[n] with a via column), --depth <1-3> (callers_depthN[n]{file,count} for N > 1), --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} ref rows across the report), --grep (adds unresolved[n]{file,line,context} - textual matches that are not References; also searches .astro/.vue/.svelte/.mdx/.html), --test-glob <glob> (repeatable), --fields <kind,exported,refs_total,via,files,tests|all> (extra changed[n] columns), -P <tsconfig>, --json
+flags[9]:
+  --staged, --size (adds size{files,hunks,lines_added,lines_removed,patch_chars,exported_signature_changes,removed_symbols} - hunks are counted at zero context for a git source, as given for -; untracked files count as added),--via (adds References through an interface or base member to refs[n] with a via column), --depth <1-3> (callers_depthN[n]{file,count} for N > 1), --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} ref rows across the report), --grep (adds unresolved[n]{file,line,context} - textual matches that are not References; also searches .astro/.vue/.svelte/.mdx/.html), --test-glob <glob> (repeatable), --fields <kind,exported,refs_total,via,files,tests|all> (extra changed[n] columns), -P <tsconfig>, --json
 output:
   base, head, changes (count), changed[n]{symbol,change,at,refs_outside} by default; --fields adds columns in place, --fields all gives {symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}
   change = signature | removed | type | added | body | modified (before unavailable) - riskiest first
@@ -41,10 +41,11 @@ output:
   skipped[n]{file,reason} = files in the diff that were not analysed (.astro, .json, outside the Project)
   tests: 0 on an exported signature or body change = no Test file references it (columns from --fields exported,tests)
   scope = in a monorepo without -P the program is the touched files + two levels of importers (scope_partial: true when capped)
-examples[5]:
+examples[6]:
   ts-axi impact
   ts-axi impact --staged
   ts-axi impact main...HEAD
+  ts-axi impact main...HEAD --size
   ts-axi impact HEAD~3 --depth 2 --grep
   bb-axi pr diff 42 --raw | ts-axi impact -
 `;
@@ -56,14 +57,24 @@ const SPECS = [
     { name: "--grep", boolean: true },
     { name: "--test-glob", repeatable: true },
     { name: "--fields" },
+    { name: "--size", boolean: true },
     { name: "-P" },
 ];
 // Opt-in columns of changed[n]; the default keeps symbol, change, at, refs_outside.
 const IMPACT_FIELDS = ["kind", "exported", "refs_total", "via", "files", "tests"];
 const OPT_IN = new Set(IMPACT_FIELDS);
-async function readStdin() {
+function diffSize(parsed, text) {
+    return {
+        files: parsed.length,
+        hunks: parsed.reduce((n, f) => n + f.hunks.length, 0),
+        lines_added: parsed.reduce((n, f) => n + f.hunks.reduce((m, h) => m + h.added.length, 0), 0),
+        lines_removed: parsed.reduce((n, f) => n + f.hunks.reduce((m, h) => m + h.removed.length, 0), 0),
+        patch_chars: text.length,
+    };
+}
+export async function readStdin(command = "impact", example = "git diff -U0 | ts-axi impact -") {
     if (process.stdin.isTTY) {
-        throw usageError("`impact -` reads a unified diff from stdin and nothing was piped", ["git diff -U0 | ts-axi impact -"]);
+        throw usageError(`\`${command} -\` reads a unified diff from stdin and nothing was piped`, [example]);
     }
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -79,16 +90,6 @@ function readText(abs) {
         return null;
     }
 }
-/** Right side of a range; undefined when git diffs it against the working tree (`abc123`). */
-function headOfRange(range) {
-    const triple = range.indexOf("...");
-    if (triple > 0)
-        return range.slice(triple + 3) || "HEAD";
-    const double = range.indexOf("..");
-    if (double > 0)
-        return range.slice(double + 2) || "HEAD";
-    return undefined;
-}
 async function gitInput(cwd, root, range, staged) {
     if (!(await isGitRepo(cwd))) {
         throw new AxiError("not a git repository - impact needs git or a diff on stdin", "GIT_ERROR", [
@@ -97,8 +98,9 @@ async function gitInput(cwd, root, range, staged) {
     }
     const [diffText, names] = await Promise.all([diffUnified(cwd, range, staged), diffNameStatus(cwd, range, staged)]);
     const parsed = parseUnifiedDiff(diffText);
+    const size = diffSize(parsed, diffText);
     const base = staged ? "HEAD" : await resolveBaseRev(cwd, range);
-    const headRev = staged ? "" : range !== undefined ? headOfRange(range) : undefined;
+    const headRev = staged ? "" : range !== undefined ? headRevOfRange(range) : undefined;
     const files = [];
     for (const diff of parsed) {
         const { after, before } = changedRanges(diff);
@@ -113,16 +115,23 @@ async function gitInput(cwd, root, range, staged) {
                 continue;
             const lines = text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
             files.push({ path, status: "added", after: lines > 0 ? [[1, lines]] : [], before: [], afterText: text, beforeText: null });
+            // Untracked files count as added, one hunk each; they are not in patch_chars.
+            size.files++;
+            size.hunks += lines > 0 ? 1 : 0;
+            size.lines_added += lines;
         }
     }
     const seen = new Set(parsed.map((d) => d.path));
+    const noText = names.filter((n) => !seen.has(n.path) && n.status !== "deleted").map((n) => n.path);
+    size.files += noText.length;
     return {
         base,
         head: staged ? "index" : headRev ?? "working tree",
         ...(headRev !== undefined ? { headRev } : {}),
         files,
-        noText: names.filter((n) => !seen.has(n.path) && n.status !== "deleted").map((n) => n.path),
+        noText,
         missing: [],
+        size,
     };
 }
 function stdinInput(text, root) {
@@ -139,7 +148,7 @@ function stdinInput(text, root) {
         const beforeText = diff.status === "added" ? null : reverseApply(afterText ?? "", diff.hunks) ?? undefined;
         files.push({ path: diff.path, ...(diff.oldPath ? { oldPath: diff.oldPath } : {}), status: diff.status, after, before, afterText, beforeText });
     }
-    return { base: "stdin diff", head: "working tree", files, noText: [], missing };
+    return { base: "stdin diff", head: "working tree", files, noText: [], missing, size: diffSize(parseUnifiedDiff(text, { binary: true }), text) };
 }
 function isSourcePath(path) {
     return SOURCE_EXTENSIONS.some((ext) => path.endsWith(ext));
@@ -470,7 +479,7 @@ function capped(key, rows) {
     };
 }
 /** Quotes a value for a pasteable command. */
-function shellWord(value) {
+export function shellWord(value) {
     return /^[\w@%+=:,.\/-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 }
 /** The same `impact` invocation with every given flag replayed, the one `extra` sets replaced by it. */
@@ -593,12 +602,22 @@ export async function impactCommand(args, ctx) {
         }
     }
     const total = declChanges.length + fileLevel.length;
+    const exportedOf = (c) => (c.after ?? c.before)?.exported ?? false;
     const header = {
         ...(warnings.length > 0 ? { warning: warnings.join("; ") } : {}),
         ...projectFields(opened),
         base: input.base,
         head: input.head,
         changes: total,
+        ...(bool(parsed, "--size")
+            ? {
+                size: {
+                    ...input.size,
+                    exported_signature_changes: declChanges.filter((c) => c.change === "signature" && exportedOf(c)).length,
+                    removed_symbols: declChanges.filter((c) => c.change === "removed").length,
+                },
+            }
+            : {}),
     };
     const skipTemplates = (used) => {
         for (const f of templateInputs)

package/dist/src/diff.js

@@ -40,8 +40,8 @@ function parseGitHeader(rest) {
     const m = /^"?a\/(.+?)"? "?b\/(.+?)"?$/.exec(rest);
     return m ? [m[1], m[2]] : [undefined, undefined];
 }
-function finish(draft) {
-    if (draft.binary)
+function finish(draft, keepBinary) {
+    if (draft.binary && !keepBinary)
         return undefined;
     const isNew = draft.newMode || draft.minus === null;
     const isDeleted = draft.deletedMode || draft.plus === null;
@@ -62,13 +62,15 @@ function finish(draft) {
         oldPath: status === "renamed" ? oldP : undefined,
         status,
         hunks: draft.hunks,
+        ...(draft.binary ? { binary: true } : {}),
     };
 }
 /**
- * Parse git-style unified diff text. Binary files are skipped; files with no
- * hunks (pure renames, mode changes) are kept with `hunks: []`.
+ * Parse git-style unified diff text. Binary files are skipped unless `binary` is set; files
+ * with no hunks (pure renames, mode changes) are kept with `hunks: []`. Splits on `\n` only,
+ * so `\r`, U+2028 or U+2029 inside a line never shift the numbering.
  */
-export function parseUnifiedDiff(text) {
+export function parseUnifiedDiff(text, options = {}) {
     const files = [];
     let draft;
     let hunk;
@@ -78,7 +80,7 @@ export function parseUnifiedDiff(text) {
     let newNo = 0;
     const flush = () => {
         if (draft) {
-            const file = finish(draft);
+            const file = finish(draft, options.binary === true);
             if (file)
                 files.push(file);
         }
@@ -104,6 +106,7 @@ export function parseUnifiedDiff(text) {
                 continue;
             }
             if (tag === " " || line === "") {
+                hunk.context.push({ oldLine: oldNo, newLine: newNo });
                 oldNo++;
                 newNo++;
                 oldLeft--;
@@ -130,6 +133,7 @@ export function parseUnifiedDiff(text) {
                 newLines: h[4] === undefined ? 1 : Number(h[4]),
                 removed: [],
                 added: [],
+                context: [],
             };
             draft.hunks.push(hunk);
             oldLeft = hunk.oldLines;
@@ -211,3 +215,13 @@ export function baseRevOfRange(range) {
         return range;
     return range.slice(0, index) || "HEAD";
 }
+/** Right side of a range; undefined when git diffs it against the working tree (`abc123`). */
+export function headRevOfRange(range) {
+    const triple = range.indexOf("...");
+    if (triple > 0)
+        return range.slice(triple + 3) || "HEAD";
+    const double = range.indexOf("..");
+    if (double > 0)
+        return range.slice(double + 2) || "HEAD";
+    return undefined;
+}

package/dist/src/errors.js

@@ -1,5 +1,7 @@
 import { AxiError, exitCodeForError as sdkExitCode } from "axi-sdk-js";
 export { AxiError };
+/** `anchor` exit code when an anchor is not commentable; set by the handler, the output still prints. */
+export const ANCHOR_INVALID_EXIT = 3;
 /** SDK mapping: 2 for usage errors, 1 otherwise (`GIT_ERROR` included). */
 export function exitCodeForError(error) {
     return sdkExitCode(error);

package/dist/src/git.js

@@ -155,10 +155,10 @@ export async function untrackedFiles(cwd) {
     const stdout = await runOrThrow(cwd, ["ls-files", "--others", "--exclude-standard", "-z", "--full-name", ":/"]);
     return stdout.split("\0").filter((p) => p !== "");
 }
-/** Raw unified diff with zero context lines; same target rules as `diffNameStatus`. */
-export async function diffUnified(cwd, range, staged) {
+/** Raw unified diff with `context` lines around each change (default 0); same target rules as `diffNameStatus`. */
+export async function diffUnified(cwd, range, staged, context = 0) {
     const target = await diffTarget(cwd, range, staged);
-    return runOrThrow(cwd, ["diff", "-U0", "--no-color", "--no-ext-diff", "-M", ...target, "--"]);
+    return runOrThrow(cwd, ["diff", `-U${context}`, "--no-color", "--no-ext-diff", "-M", ...target, "--"]);
 }
 /** File content at `rev`, or `null` when the path does not exist there. */
 export async function showFile(cwd, rev, path) {

package/dist/src/skill.js

@@ -3,7 +3,8 @@ import { DESCRIPTION } from "./cli.js";
 // outcome-focused so it fires on code-navigation and review intents.
 export const SKILL_DESCRIPTION = "Navigate TypeScript and JavaScript code and measure change impact through the ts-axi CLI - find where a symbol is declared, " +
     "list its references and callers, outline a file, and see which other code a diff affects. Use before reading many files to find " +
-    "callers or usages of a function, class or type; use `ts-axi impact` when reviewing a diff, a pull request or your own uncommitted changes.";
+    "callers or usages of a function, class or type; use `ts-axi impact` when reviewing a diff, a pull request or your own uncommitted changes, " +
+    "and `ts-axi anchor` to check that review-comment file:line anchors are in the diff before posting them.";
 // Hard cap so a regeneration cannot re-inflate the stub with CLI-owned
 // guidance. The home view and --help output are the source of truth.
 export const MAX_SKILL_MARKDOWN_CHARS = 2000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-axi",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "AXI-compliant TypeScript symbol CLI for agents - definitions, references, callers, file outlines and change impact (blast radius) with token-efficient TOON output",
   "type": "module",
   "keywords": [

package/skills/ts-axi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ts-axi
-description: "Navigate TypeScript and JavaScript code and measure change impact through the ts-axi CLI - find where a symbol is declared, list its references and callers, outline a file, and see which other code a diff affects. Use before reading many files to find callers or usages of a function, class or type; use `ts-axi impact` when reviewing a diff, a pull request or your own uncommitted changes."
+description: "Navigate TypeScript and JavaScript code and measure change impact through the ts-axi CLI - find where a symbol is declared, list its references and callers, outline a file, and see which other code a diff affects. Use before reading many files to find callers or usages of a function, class or type; use `ts-axi impact` when reviewing a diff, a pull request or your own uncommitted changes, and `ts-axi anchor` to check that review-comment file:line anchors are in the diff before posting them."
 user-invocable: false
 ---