terramend 0.2.0

package/src/utils/rangeDiff.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it } from "vitest";
+import { postProcessRangeDiff } from "#app/utils/rangeDiff";
+
+describe("postProcessRangeDiff", () => {
+  it("returns null for identical patches", () => {
+    const input = "1:  abc1234 = 1:  def5678 x";
+    expect(postProcessRangeDiff(input)).toBeNull();
+  });
+
+  it("returns null for empty input", () => {
+    expect(postProcessRangeDiff("")).toBeNull();
+    expect(postProcessRangeDiff("   ")).toBeNull();
+  });
+
+  it("returns null when no changes exist between versions", () => {
+    const input = [
+      "1:  abc1234 ! 1:  def5678 x",
+      "     ## src/file.ts ##",
+      "     @@ src/file.ts",
+      "     +const a = 1;",
+      "     +const b = 2;",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toBeNull();
+  });
+
+  it("strips inner diff prefix from content lines", () => {
+    const input = [
+      "1:  abc1234 ! 1:  def5678 x",
+      "     ## src/math.ts ##",
+      "     @@ src/math.ts",
+      "     +  const a = 1;",
+      "    -+  const b = 2;",
+      "    ++  const b = 3;",
+      "     +  const c = 4;",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			" ## src/math.ts ##
+			 @@ src/math.ts
+			   const a = 1;
+			-  const b = 2;
+			+  const b = 3;
+			   const c = 4;"
+		`);
+  });
+
+  it("handles context lines (inner space prefix)", () => {
+    const input = [
+      "1:  abc1234 ! 1:  def5678 x",
+      "     ## src/file.ts ##",
+      "     @@ src/file.ts",
+      "      const base = true;",
+      "    - const old = true;",
+      "    + const new_ = true;",
+      "      const end = true;",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			" ## src/file.ts ##
+			 @@ src/file.ts
+			 const base = true;
+			-const old = true;
+			+const new_ = true;
+			 const end = true;"
+		`);
+  });
+
+  it("trims context lines around changes", () => {
+    const contextBefore = Array.from(
+      { length: 9 },
+      (_, i) => `     +const line${i + 1} = ${i + 1};`,
+    );
+    const contextAfter = Array.from(
+      { length: 6 },
+      (_, i) => `     +const line${i + 11} = ${i + 11};`,
+    );
+    const input = [
+      "1:  abc1234 ! 1:  def5678 x",
+      "     ## src/large.ts ##",
+      "     @@ src/large.ts",
+      ...contextBefore,
+      "    -+const line10 = 10;",
+      "    ++const line10 = 100;",
+      ...contextAfter,
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			" ## src/large.ts ##
+			 @@ src/large.ts
+			...
+			 const line7 = 7;
+			 const line8 = 8;
+			 const line9 = 9;
+			-const line10 = 10;
+			+const line10 = 100;
+			 const line11 = 11;
+			 const line12 = 12;
+			 const line13 = 13;"
+		`);
+  });
+
+  it("handles multiple files", () => {
+    const input = [
+      "1:  abc ! 1:  def x",
+      "     ## src/a.ts ##",
+      "     @@ src/a.ts",
+      "    -+old line a",
+      "    ++new line a",
+      "     ## src/b.ts ##",
+      "     @@ src/b.ts",
+      "     +unchanged",
+      "    -+old line b",
+      "    ++new line b",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			" ## src/a.ts ##
+			 @@ src/a.ts
+			-old line a
+			+new line a
+			 ## src/b.ts ##
+			 @@ src/b.ts
+			 unchanged
+			-old line b
+			+new line b"
+		`);
+  });
+
+  it("handles new file added in new version", () => {
+    const input = [
+      "1:  abc ! 1:  def x",
+      "    +## src/new.ts (new) ##",
+      "    +@@ src/new.ts (new)",
+      "    ++export const x = 1;",
+      "    ++export const y = 2;",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			"+## src/new.ts (new) ##
+			+@@ src/new.ts (new)
+			+export const x = 1;
+			+export const y = 2;"
+		`);
+  });
+
+  it("handles file removed in new version", () => {
+    const input = [
+      "1:  abc ! 1:  def x",
+      "    -## src/old.ts ##",
+      "    -@@ src/old.ts",
+      "    --export const x = 1;",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			"-## src/old.ts ##
+			-@@ src/old.ts
+			-export const x = 1;"
+		`);
+  });
+
+  it("filters out metadata section via context trimming", () => {
+    const input = [
+      "1:  abc ! 1:  def x",
+      "     @@ Metadata",
+      "      Author: Test <test@test.com>",
+      "     ## Commit message ##",
+      "        x",
+      "     ## src/file.ts ##",
+      "     @@ src/file.ts",
+      "     +const a = 1;",
+      "    -+const b = 2;",
+      "    ++const b = 3;",
+      "     +const c = 4;",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			" ## src/file.ts ##
+			 @@ src/file.ts
+			 const a = 1;
+			-const b = 2;
+			+const b = 3;
+			 const c = 4;"
+		`);
+  });
+
+  it("uses custom context line count", () => {
+    const contextBefore = Array.from(
+      { length: 5 },
+      (_, i) => `     +const line${i + 1} = ${i + 1};`,
+    );
+    const contextAfter = Array.from(
+      { length: 5 },
+      (_, i) => `     +const line${i + 7} = ${i + 7};`,
+    );
+    const input = [
+      "1:  abc1234 ! 1:  def5678 x",
+      "     ## src/file.ts ##",
+      "     @@ src/file.ts",
+      ...contextBefore,
+      "    -+const changed = old;",
+      "    ++const changed = new;",
+      ...contextAfter,
+    ].join("\n");
+    expect(postProcessRangeDiff(input, 1)).toMatchInlineSnapshot(`
+			" ## src/file.ts ##
+			 @@ src/file.ts
+			...
+			 const line5 = 5;
+			-const changed = old;
+			+const changed = new;
+			 const line7 = 7;"
+		`);
+  });
+
+  it("handles two separate change regions in the same file", () => {
+    const middle = Array.from({ length: 10 }, (_, i) => `     +const mid${i + 1} = ${i + 1};`);
+    const input = [
+      "1:  abc ! 1:  def x",
+      "     ## src/file.ts ##",
+      "     @@ src/file.ts",
+      "    -+const first = old;",
+      "    ++const first = new;",
+      ...middle,
+      "    -+const second = old;",
+      "    ++const second = new;",
+    ].join("\n");
+    expect(postProcessRangeDiff(input)).toMatchInlineSnapshot(`
+			" ## src/file.ts ##
+			 @@ src/file.ts
+			-const first = old;
+			+const first = new;
+			 const mid1 = 1;
+			 const mid2 = 2;
+			 const mid3 = 3;
+			...
+			 const mid8 = 8;
+			 const mid9 = 9;
+			 const mid10 = 10;
+			-const second = old;
+			+const second = new;"
+		`);
+  });
+});

package/src/utils/rangeDiff.ts

@@ -0,0 +1,182 @@
+import { log } from "#app/utils/cli";
+import { $ } from "#app/utils/shell";
+
+type ComputeIncrementalDiffParams = {
+  baseBranch: string;
+  beforeSha: string;
+  headSha: string;
+};
+
+/**
+ * computes the incremental diff between two versions of a PR using range-diff
+ * on virtual squash commits created via `git commit-tree`.
+ *
+ * each PR version is squashed into a single synthetic commit (merge-base → tip tree),
+ * then range-diff compares those two single-commit ranges. this:
+ * - isolates each version's net effect (base branch noise eliminated via per-version merge bases)
+ * - avoids commit-matching issues that raw range-diff has with rebases/squashes/reordering
+ * - creates only loose git objects, no branches or refs (unlike temp-branch squash approaches)
+ *
+ * unlike fetchAndFormatPrDiff/formatFilesWithLineNumbers, this output has no line numbers.
+ * range-diff compares *patches* (diffs-of-diffs), not file trees — its hunk headers are
+ * `@@ file.ts` breadcrumbs, not positional `@@ -X,Y +A,B @@` markers. reconstructing
+ * line numbers would require cross-referencing with the v2 diff or content-matching against
+ * file trees, both of which are fragile (duplicate lines, hunk boundary shifts after rebase).
+ * a structured interdiff approach (diff two parsed patches, compare only +/- keys via Myers)
+ * could approximate line numbers but loses semantic precision: range-diff understands patch
+ * structure natively (rename detection, hunk-aware matching, dual-prefix inner/outer changes),
+ * while flat key-sequence comparison can misalign duplicate lines and can't distinguish
+ * "new addition to the PR" from "existing code newly modified by the PR". range-diff is the
+ * right abstraction here — the incremental diff answers "how did the changeset evolve?",
+ * not "where in the file is this?", and forcing positional line numbers onto it would be
+ * semantically misleading.
+ *
+ * alternatives considered:
+ * - plain git diff (two-tree or three-dot): includes base branch changes, no PR isolation
+ * - patch-text diffing (interdiff / diff-of-diffs): fragile, hunk offset noise on rebase
+ * - range-diff on raw commit ranges: confused by commit reorganization across force-pushes
+ */
+export function computeIncrementalDiff(params: ComputeIncrementalDiffParams): string | null {
+  try {
+    // $1=beforeSha, $2=baseBranch, $3=headSha
+    const raw = $(
+      "sh",
+      [
+        "-c",
+        'old_base=$(git merge-base "$1" "origin/$2") && ' +
+          'new_base=$(git merge-base "$3" "origin/$2") && ' +
+          "git range-diff --no-color " +
+          '"$old_base..$(git commit-tree "$1^{tree}" -p "$old_base" -m x)" ' +
+          '"$new_base..$(git commit-tree "$3^{tree}" -p "$new_base" -m x)"',
+        "--",
+        params.beforeSha,
+        params.baseBranch,
+        params.headSha,
+      ],
+      { log: false },
+    );
+
+    return postProcessRangeDiff(raw);
+  } catch (e) {
+    log.debug(`» range-diff failed: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  }
+}
+
+function isDiffPrefix(ch: string): boolean {
+  return ch === " " || ch === "+" || ch === "-";
+}
+
+/**
+ * transforms git range-diff output into a clean incremental diff.
+ *
+ * range-diff content lines have two prefix characters:
+ *   1st (outer): range-diff level — space (same in both), + (new only), - (old only)
+ *   2nd (inner): original diff level — space (context), + (added), - (removed)
+ *
+ * stripping the inner prefix produces a standard unified-diff-like output where
+ * +/- means "changed between PR versions" rather than "changed vs base branch".
+ *
+ * uses a streaming approach: a ring buffer of before-context lines is flushed when
+ * a change is hit, then afterCount lines of after-context are emitted directly.
+ * nearest preceding ## / @@ headers are force-included when outside the context window.
+ */
+export function postProcessRangeDiff(raw: string, contextLines = 3): string | null {
+  if (!raw.trim()) return null;
+  if (/^\d+:\s+\w+\s+=\s+\d+:/m.test(raw)) return null;
+
+  type Line = { prefix: string; from: number; to: number; seq: number };
+
+  const beforeBuf: Line[] = [];
+  let lastFileHdr: Line | null = null;
+  let lastHunkHdr: Line | null = null;
+  let fileHdrEmitted = true;
+  let hunkHdrEmitted = true;
+
+  let out = "";
+  let afterRemaining = 0;
+  let lastEmittedSeq = -2;
+  let seq = 0;
+  let hasChanges = false;
+
+  function emit(line: Line) {
+    if (lastEmittedSeq >= 0 && line.seq > lastEmittedSeq + 1) out += `${out ? "\n" : ""}...`;
+    out += (out ? "\n" : "") + line.prefix + raw.slice(line.from, line.to);
+    lastEmittedSeq = line.seq;
+    if (lastFileHdr?.seq === line.seq) fileHdrEmitted = true;
+    if (lastHunkHdr?.seq === line.seq) hunkHdrEmitted = true;
+  }
+
+  function flushBefore() {
+    if (lastFileHdr && !fileHdrEmitted) emit(lastFileHdr);
+    if (lastHunkHdr && !hunkHdrEmitted) emit(lastHunkHdr);
+    for (const line of beforeBuf) {
+      if (line.seq > lastEmittedSeq) emit(line);
+    }
+    beforeBuf.length = 0;
+  }
+
+  let cursor = 0;
+  while (cursor < raw.length) {
+    const eol = raw.indexOf("\n", cursor);
+    const lineEnd = eol === -1 ? raw.length : eol;
+
+    if (raw.charCodeAt(cursor) >= 48 && raw.charCodeAt(cursor) <= 57) {
+      cursor = lineEnd + 1;
+      continue;
+    }
+
+    if (lineEnd - cursor >= 5 && raw.startsWith("    ", cursor)) {
+      const prefix = raw[cursor + 4]!;
+      if (isDiffPrefix(prefix)) {
+        const contentPos = cursor + 5;
+        const isOuterChange = prefix !== " ";
+        let line: Line;
+        let isChange = false;
+
+        if (contentPos >= lineEnd) {
+          line = { prefix, from: lineEnd, to: lineEnd, seq };
+        } else if (isDiffPrefix(raw[contentPos]!)) {
+          isChange = isOuterChange;
+          line = { prefix, from: contentPos + 1, to: lineEnd, seq };
+        } else {
+          line = { prefix, from: contentPos, to: lineEnd, seq };
+          if (
+            raw.startsWith("## ", contentPos) &&
+            !raw.startsWith("## Commit message", contentPos)
+          ) {
+            lastFileHdr = line;
+            fileHdrEmitted = false;
+            lastHunkHdr = null;
+            hunkHdrEmitted = true;
+          } else if (
+            raw.startsWith("@@", contentPos) &&
+            !raw.startsWith("@@ Metadata", contentPos)
+          ) {
+            lastHunkHdr = line;
+            hunkHdrEmitted = false;
+          }
+        }
+
+        if (isChange) {
+          hasChanges = true;
+          flushBefore();
+          emit(line);
+          afterRemaining = contextLines;
+        } else if (afterRemaining > 0) {
+          emit(line);
+          afterRemaining--;
+        } else {
+          if (beforeBuf.length >= contextLines) beforeBuf.shift();
+          beforeBuf.push(line);
+        }
+
+        seq++;
+      }
+    }
+
+    cursor = lineEnd + 1;
+  }
+
+  return hasChanges ? out : null;
+}

package/src/utils/remediationCommand.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest";
+import { parseRemediationCommand, STRATEGY_REPLY_HINT } from "#app/utils/remediationCommand";
+
+describe("parseRemediationCommand (§3.12)", () => {
+  it("returns null when the body has no mention", () => {
+    expect(parseRemediationCommand("please fix #abc123")).toBeNull();
+    expect(parseRemediationCommand(undefined)).toBeNull();
+  });
+
+  it("parses `fix #<id>` and `fix <id>` into a concern command (lowercased)", () => {
+    expect(parseRemediationCommand("@terramend fix #3a9f1c2")).toEqual({
+      kind: "concern",
+      concernRef: "3a9f1c2",
+    });
+    expect(parseRemediationCommand("@terramend fix ABCDEF12")).toEqual({
+      kind: "concern",
+      concernRef: "abcdef12",
+    });
+  });
+
+  it("parses `fix all <sev>-severity` and `fix all <sev>`", () => {
+    expect(parseRemediationCommand("@terramend fix all high-severity")).toEqual({
+      kind: "severity",
+      severity: "high",
+    });
+    expect(parseRemediationCommand("@terramend fix all low")).toEqual({
+      kind: "severity",
+      severity: "low",
+    });
+  });
+
+  it("parses `fix <sev>-severity` without `all`", () => {
+    expect(parseRemediationCommand("@terramend fix critical-severity")).toEqual({
+      kind: "severity",
+      severity: "critical",
+    });
+  });
+
+  it("parses `fix all` as everything", () => {
+    expect(parseRemediationCommand("@terramend fix all")).toEqual({ kind: "all" });
+  });
+
+  it("parses a file target", () => {
+    expect(parseRemediationCommand("@terramend fix modules/net/main.tf")).toEqual({
+      kind: "file",
+      file: "modules/net/main.tf",
+    });
+    expect(parseRemediationCommand("@terramend fix prod.tfvars")).toEqual({
+      kind: "file",
+      file: "prod.tfvars",
+    });
+  });
+
+  it("tolerates surrounding prose and the [bot] suffix", () => {
+    expect(
+      parseRemediationCommand("hey @terramend[bot] please fix all medium-severity thanks"),
+    ).toEqual({
+      kind: "severity",
+      severity: "medium",
+    });
+  });
+
+  it("returns null for a mention that isn't a fix command", () => {
+    expect(parseRemediationCommand("@terramend what's the status?")).toBeNull();
+  });
+
+  it("prefers `fix all <sev>` over a bare file/concern interpretation", () => {
+    // "all" is a keyword, not a file/concern — must not be read as kind:file.
+    expect(parseRemediationCommand("@terramend fix all")).toEqual({ kind: "all" });
+  });
+
+  it("does NOT read prose 'fix all the bugs' as the fix-all command", () => {
+    // regression: a non-severity word after "all" is prose, not a command.
+    expect(parseRemediationCommand("@terramend please fix all the bugs")).toBeNull();
+    expect(parseRemediationCommand("@terramend fix all outstanding issues")).toBeNull();
+  });
+
+  it("classifies a hex-named .tf file as a file, not a concern id", () => {
+    // regression: `deadbeef.tf` stem is all-hex but it's a filename.
+    expect(parseRemediationCommand("@terramend fix deadbeef.tf")).toEqual({
+      kind: "file",
+      file: "deadbeef.tf",
+    });
+    expect(parseRemediationCommand("@terramend fix 0badf00d.tfvars")).toEqual({
+      kind: "file",
+      file: "0badf00d.tfvars",
+    });
+  });
+
+  it("still reads a bare hex id (no extension) as a concern", () => {
+    expect(parseRemediationCommand("@terramend fix #deadbeef please")).toEqual({
+      kind: "concern",
+      concernRef: "deadbeef",
+    });
+  });
+});
+
+describe("parseRemediationCommand — strategy selection (§26)", () => {
+  it("attaches a strategy label to a `fix #<id>` command (letter, upper-normalised)", () => {
+    expect(parseRemediationCommand("@terramend fix #3a9f1c2 with strategy B")).toEqual({
+      kind: "concern",
+      concernRef: "3a9f1c2",
+      strategy: "B",
+    });
+    expect(parseRemediationCommand("@terramend fix #3a9f1c2 using strategy a")).toEqual({
+      kind: "concern",
+      concernRef: "3a9f1c2",
+      strategy: "A",
+    });
+  });
+
+  it("accepts `option` / `approach` and a digit label", () => {
+    expect(parseRemediationCommand("@terramend fix #deadbeef option 2")).toEqual({
+      kind: "concern",
+      concernRef: "deadbeef",
+      strategy: "2",
+    });
+    expect(parseRemediationCommand("@terramend fix #deadbeef approach C")).toEqual({
+      kind: "concern",
+      concernRef: "deadbeef",
+      strategy: "C",
+    });
+  });
+
+  it("leaves strategy unset on a plain `fix #<id>`", () => {
+    const result = parseRemediationCommand("@terramend fix #3a9f1c2");
+    expect(result).toEqual({ kind: "concern", concernRef: "3a9f1c2" });
+    expect((result as { strategy?: string }).strategy).toBeUndefined();
+  });
+
+  it("reads a bare strategy reply (concern comes from the thread)", () => {
+    expect(parseRemediationCommand("@terramend strategy B")).toEqual({
+      kind: "strategy",
+      strategy: "B",
+    });
+    expect(parseRemediationCommand("@terramend let's go with option 3")).toEqual({
+      kind: "strategy",
+      strategy: "3",
+    });
+  });
+
+  it("keeps an explicit #<id> when a strategy reply names one without `fix`", () => {
+    expect(parseRemediationCommand("@terramend apply strategy A to #deadbeef")).toEqual({
+      kind: "concern",
+      concernRef: "deadbeef",
+      strategy: "A",
+    });
+  });
+
+  it("does not read prose as a strategy pick", () => {
+    expect(parseRemediationCommand("@terramend this is a solid strategy overall")).toBeNull();
+    expect(parseRemediationCommand("@terramend what's the best approach here?")).toBeNull();
+  });
+
+  it("round-trips the canonical reply hint through the parser", () => {
+    const replied = STRATEGY_REPLY_HINT.replace("<concern-id>", "3a9f1c2").replace("<A|B|C>", "B");
+    expect(parseRemediationCommand(replied)).toEqual({
+      kind: "concern",
+      concernRef: "3a9f1c2",
+      strategy: "B",
+    });
+  });
+});

package/src/utils/remediationCommand.ts

@@ -0,0 +1,119 @@
+/**
+ * §3.12 Comment-command interface. A developer can scope a remediation run from
+ * a PR/issue comment that mentions the bot:
+ *
+ *   @terramend fix #3a9f1c2          → fix exactly one concern (by id or short id)
+ *   @terramend fix all high-severity → fix every concern at/above a severity
+ *   @terramend fix all               → fix everything (still bounded by max_prs)
+ *   @terramend fix main.tf           → fix one file's group
+ *
+ * §26 Propose, then let me steer — when a non-trivial finding has several
+ * genuinely distinct valid fixes, Remediate proposes 2–3 labelled strategies in
+ * a comment instead of guessing, and the reviewer picks one by replying:
+ *
+ *   @terramend fix #3a9f1c2 with strategy B   → apply strategy B to that concern
+ *   @terramend strategy 2                      → pick strategy 2 (concern from the thread)
+ *
+ * The parsing is pure + deterministic so the scoping doesn't depend on the
+ * model's reading of the comment. The Remediate mode applies the parsed scope
+ * (which group(s) to act on, and which strategy) instead of the default
+ * "highest-severity group, agent's-choice fix".
+ */
+
+export type RemediationCommand =
+  | { kind: "concern"; concernRef: string; strategy?: string }
+  | { kind: "severity"; severity: Severity }
+  | { kind: "file"; file: string }
+  // §26 — a bare strategy pick (e.g. an in-thread reply to a proposal); the
+  // concern is resolved from the comment thread the run was triggered on.
+  | { kind: "strategy"; strategy: string }
+  | { kind: "all" };
+
+const SEVERITIES = ["critical", "high", "medium", "low", "info"] as const;
+type Severity = (typeof SEVERITIES)[number];
+
+/** the bot handles a mention can use (with or without the `[bot]` suffix). */
+const MENTION = /@terramend(?:\[bot\])?\b/i;
+
+/**
+ * §26 — the canonical phrasing the proposal comment must tell reviewers to reply
+ * with. Lives next to the parser that accepts it so the proposal template (in
+ * the Remediate prompt) and the parser can never drift apart. `<concern-id>` and
+ * `<A|B|C>` are placeholders the agent fills with the real id and the offered
+ * strategy labels.
+ */
+export const STRATEGY_REPLY_HINT = "@terramend fix #<concern-id> with strategy <A|B|C>";
+
+// a strategy label is a single letter (A–Z, normalised to upper) or digit (1–9),
+// introduced by `strategy` / `option` / `approach`. The single-char + `\b` bound
+// keeps it off prose ("a good strategy overall" has no single-char boundary).
+const STRATEGY = /\b(?:strategy|option|approach)\s+#?([A-Za-z]|[1-9])\b/i;
+
+function parseStrategyToken(text: string): string | undefined {
+  const m = text.match(STRATEGY);
+  if (!m) return undefined;
+  const tok = m[1]!;
+  return /[A-Za-z]/.test(tok) ? tok.toUpperCase() : tok;
+}
+
+/**
+ * Parse a `@terramend fix …` command out of a comment body. Returns null when
+ * the body isn't a recognised fix command (the run then falls back to its
+ * default scope). Tolerant of surrounding prose — it scans for the mention then
+ * the `fix` verb and its argument.
+ */
+export function parseRemediationCommand(body: string | undefined): RemediationCommand | null {
+  if (!body) return null;
+  if (!MENTION.test(body)) return null;
+
+  // everything after the mention; we keep original case for the file/concern-ref
+  // capture (the lower-casing happens per match).
+  const afterMention = body.slice(body.search(MENTION));
+  const isSeverity = (s: string): s is Severity => (SEVERITIES as readonly string[]).includes(s);
+
+  // `fix all <sev>[-severity]` / `fix all` — but a NON-severity word after "all"
+  // (prose like "fix all the bugs") is NOT the command: fall through rather than
+  // silently treating it as "fix everything".
+  const all = afterMention.match(/\bfix\s+all\b(?:\s+([a-z]+)(?:\s*-?\s*severity)?)?/i);
+  if (all) {
+    const trailing = all[1]?.toLowerCase();
+    if (!trailing) return { kind: "all" };
+    if (isSeverity(trailing)) return { kind: "severity", severity: trailing };
+    // a non-severity word followed "all" → prose, not a command. fall through.
+  }
+
+  // `fix <sev>-severity` (without "all")
+  const sevOnly = afterMention.match(/\bfix\s+([a-z]+)\s*-?\s*severity\b/i);
+  if (sevOnly) {
+    const sev = sevOnly[1]!.toLowerCase();
+    if (isSeverity(sev)) return { kind: "severity", severity: sev };
+  }
+
+  // `fix <path>.tf` / `fix <path>.tfvars` — a specific file's group. Checked
+  // BEFORE the concern-id form so an all-hex filename stem (e.g. `deadbeef.tf`)
+  // isn't mis-read as a concern id.
+  const file = afterMention.match(/\bfix\s+([^\s#]+\.tf(?:vars)?)\b/i);
+  if (file) return { kind: "file", file: file[1]! };
+
+  // `fix #<id>` or `fix <id>` — a concern id is hex (content hash, 6–40 chars).
+  // §26 — carries an optional strategy label when the comment selects one.
+  const concern = afterMention.match(/\bfix\s+#?([0-9a-f]{6,40})\b/i);
+  if (concern) {
+    const concernRef = concern[1]!.toLowerCase();
+    const strategy = parseStrategyToken(afterMention);
+    return strategy ? { kind: "concern", concernRef, strategy } : { kind: "concern", concernRef };
+  }
+
+  // §26 — a strategy pick with no `fix` verb (e.g. an in-thread reply). If the
+  // reviewer still named a `#<id>`, keep it as a scoped concern; otherwise the
+  // concern is resolved from the thread the comment lives on.
+  const strategy = parseStrategyToken(afterMention);
+  if (strategy) {
+    const id = afterMention.match(/#([0-9a-f]{6,40})\b/i);
+    return id
+      ? { kind: "concern", concernRef: id[1]!.toLowerCase(), strategy }
+      : { kind: "strategy", strategy };
+  }
+
+  return null;
+}