ts-axi 0.1.11 → 0.1.13

package/README.md

@@ -78,11 +78,12 @@ The hook runs `ts-axi` with no arguments: it reads only the file tree and git st
 | Command | What it does |
 | --- | --- |
 | `ts-axi` | Home view: project root, tsconfig used (or implicit), source file count, test-file glob and match counts, git branch and dirty count, next steps. Under a second, exit 0 everywhere |
-| `def <target>` | Declarations of a symbol by name (`save`, `User.save`, `path:line`): one match prints detail and body, several print a compact list, none prints `did_you_mean` |
+| `def <target>` | Declarations of a symbol by name (`save`, `User.save`, `path:line`): one match prints detail and body, several print a compact list, none prints `did_you_mean` and, when the name still occurs in the code, the `refs <name> --grep` that lists those textual matches |
 | `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:
@@ -180,7 +205,7 @@ decls[4]{line,kind,name,exported,signature}:
   17,function,cartBadge,true,directive cartBadge()
 ```
 
-An edit inside `CartCtrl` is reported by `impact` as `CartCtrl body`, not as a file-level change. Names registered by a string have no identifier the checker can follow; `refs` says so and offers `--grep`. ui-router and ngRoute states are Declarations of kind `state` (`states.cart`, with callbacks as `states.cart.resolve.items`), so an edit inside a `resolve` names that callback; state objects in exported arrays (`` module.exports = [{ name: `${base}.init`, url, resolve }] ``) count too, their template-literal names filled from same-file consts. Directives, components, their `scope`/`bindings` keys, controllers and filters also get `templates: <n> usages in <m> files` (kebab-case elements and attributes, `ng-controller`, `| filter` in `.html`/`.htm`/`.ejs`/`.hbs`/`.njk`/`.pug`), a `templates` column in `impact`, and a changed template that uses a changed directive or binding is listed under `template_changes` instead of `skipped`.
+An edit inside `CartCtrl` is reported by `impact` as `CartCtrl body`, not as a file-level change. Names registered by a string have no identifier the checker can follow; `refs` says so and offers `--grep`. A registration that names a same-file function (`.directive('fancyBox', fancyBox)`, `['$uibModal', fancyBox]`) links the two, so `refs` on the function reports the registration's template usages too. Function-valued members of an object a function returns (`return { canReadItem: async () => ... }`) are Declarations (`makeItemDeps.canReadItem`), so `def canReadItem` finds them; their `textual:` count covers the whole project, while a real local (a parameter, an IIFE helper, a CommonJS binding no `module.exports` hands out) says `in this file`. ui-router and ngRoute states are Declarations of kind `state` (`states.cart`, with callbacks as `states.cart.resolve.items`), so an edit inside a `resolve` names that callback; state objects in exported arrays (`` module.exports = [{ name: `${base}.init`, url, resolve }] ``) count too, their template-literal names filled from same-file consts. Directives, components, their `scope`/`bindings` keys, controllers and filters also get `templates: <n> usages in <m> files` (kebab-case elements and attributes, `ng-controller`, `| filter` in `.html`/`.htm`/`.ejs`/`.hbs`/`.njk`/`.pug`), a `templates` column in `impact`, and a changed template that uses a changed directive or binding is listed under `template_changes` instead of `skipped`.
 
 ## Monorepos
 

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/common.js

@@ -217,9 +217,27 @@ function identifiers(node, sf, outIds) {
     }
     ts.forEachChild(node, (child) => identifiers(child, sf, outIds));
 }
+function isFunctionValue(expr) {
+    let e = expr;
+    while (ts.isParenthesizedExpression(e))
+        e = e.expression;
+    return ts.isArrowFunction(e) || ts.isFunctionExpression(e);
+}
+/** Declares a name: a Declaration kind, a parameter, a binding element, or a function-valued property. */
 function isDeclarationName(id) {
     const parent = id.parent;
-    return parent !== undefined && parent.name === id && (kindOf(parent) !== undefined || ts.isParameter(parent) || ts.isBindingElement(parent));
+    if (parent === undefined || parent.name !== id)
+        return false;
+    if (ts.isPropertyAssignment(parent))
+        return isFunctionValue(parent.initializer);
+    return kindOf(parent) !== undefined || ts.isParameter(parent) || ts.isBindingElement(parent);
+}
+/** The node a declaration name owns, for nesting: `this.x = fn` → the whole assignment. */
+function declarationNode(id) {
+    const parent = id.parent;
+    if (ts.isPropertyAccessExpression(parent) && parent.name === id && ts.isBinaryExpression(parent.parent) && parent.parent.left === parent)
+        return parent.parent;
+    return parent;
 }
 /** The identifier a `path:line[:col]` target points at (see PLAN.md Targets). */
 export function resolvePosition(index, cwd, target) {
@@ -252,33 +270,41 @@ export function resolvePosition(index, cwd, target) {
         return hit ? pick(hit) : { kind: "none", abs, file, reason: `no identifier at ${file}:${target.line}:${target.col}` };
     }
     // A string-registered name has no identifier: its line stands for it.
-    const nameless = decls.find((d) => d.nameless && d.nameLine === target.line);
+    // The registration line too: `.directive('x', fancyBox)` has its name far from the function.
+    const nameless = decls.find((d) => d.nameless && d.nameLine === target.line) ?? decls.find((d) => d.nameless && d.line === target.line);
     if (nameless)
         return { kind: "decl", decl: nameless, abs };
     if (onLine.length === 0)
         return { kind: "none", abs, file, reason: `no identifier on ${file}:${target.line}` };
+    const ambiguous = (ids) => {
+        const distinct = new Map();
+        for (const id of ids)
+            if (!distinct.has(id.text))
+                distinct.set(id.text, id);
+        if (distinct.size === 1)
+            return pick(ids[0]);
+        return {
+            kind: "ambiguous",
+            abs,
+            file,
+            candidates: [...distinct.values()].map((id) => ({ name: id.text, line: target.line, col: id.getStart(sf) - lineStart + 1 })),
+        };
+    };
     const constructorDecl = decls.find((d) => d.nameLine === target.line && d.name === "constructor");
-    const declared = onLine.find((id) => declFor(id)) ?? onLine.find(isDeclarationName);
-    if (declared)
-        return pick(declared);
+    // The declaration that starts the line: names nested in another one's declaration (its parameters, its members) rank after it.
+    const declaring = onLine.filter((id) => declFor(id) !== undefined || isDeclarationName(id));
+    const owned = (inner, outer) => {
+        const node = declarationNode(outer);
+        const at = inner.getStart(sf);
+        return node !== declarationNode(inner) && node.getStart(sf) <= at && at < node.end;
+    };
+    const outer = declaring.filter((id) => !(constructorDecl && ts.isParameter(id.parent) && ts.isConstructorDeclaration(id.parent.parent)) &&
+        !declaring.some((other) => other !== id && owned(id, other)));
+    if (outer.length > 0)
+        return ambiguous(outer);
     if (constructorDecl)
         return { kind: "decl", decl: constructorDecl, abs };
-    const distinct = new Map();
-    for (const id of onLine)
-        if (!distinct.has(id.text))
-            distinct.set(id.text, id);
-    if (distinct.size === 1)
-        return pick(onLine[0]);
-    return {
-        kind: "ambiguous",
-        abs,
-        file,
-        candidates: [...distinct.values()].map((id) => ({
-            name: id.text,
-            line: target.line,
-            col: id.getStart(sf) - lineStart + 1,
-        })),
-    };
+    return ambiguous(onLine);
 }
 /** A Declaration for an arbitrary declaration name position (locals, parameters) not in the index. */
 export function declarationAt(index, abs, pos, fallbackKind) {

package/dist/src/commands/def.js

@@ -1,5 +1,6 @@
 import { bool, expectPositionals, flag, parseArgs } from "../args.js";
 import { semanticFor } from "../scope.js";
+import { textualScan, textualScanHint } from "./impact.js";
 import { block, fenced, helpBlock, out } from "../render.js";
 import { isFunctionLike, kindFromScriptElement, parseTarget } from "../symbols.js";
 import { BODY_LINES, declarationAt, filterSuffix, MATCH_ROWS, matchRows, narrowHints, numberedLines, open, positionStartDir, resolveNameTarget, resolvePosition, suggestions, TARGET_FLAGS, targetLabel, readFilters, useRef, } from "./common.js";
@@ -9,7 +10,7 @@ flags[8]:
 output:
   1 match = file, line, kind, exported, signature + body fenced with file line numbers
   several = matches[n]{at,kind,signature} (at = path:line) (at most ${MATCH_ROWS}; matches_total + truncated past that) + the narrowing forms (--in, --kind, Class.member, --exported) with how many each keeps
-  none = matches: 0 + did_you_mean
+  none = matches: 0 + did_you_mean; when the name still occurs in Project files, help gives the refs --grep that lists those textual matches
 examples[5]:
   ts-axi def User
   ts-axi def User.save
@@ -78,7 +79,8 @@ export async function defCommand(args, ctx) {
         return detail(opened, groups[0].decls, full, label);
     if (groups.length === 0) {
         const suggested = suggestions(opened, target);
-        const help = suggested.slice(0, 2).map((s) => `Run \`ts-axi def ${s}\``);
+        const text = f.fuzzy ? 0 : textualScan(opened, target.member ?? target.name).length;
+        const help = [...(text > 0 ? [textualScanHint(label, text)] : []), ...suggested.slice(0, 2).map((s) => `Run \`ts-axi def ${s}\``)];
         if (!f.fuzzy)
             help.push(`Run \`ts-axi def ${label} --fuzzy\` for substring matches`);
         if (f.kind || f.in.length > 0 || f.exported)