@izkac/forgekit 0.1.0

package/src/review/merge-tentative.test.mjs

@@ -0,0 +1,363 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  parseArgs,
+  locationFile,
+  firstLineNumber,
+  isDuplicate,
+  dedupeFindings,
+  renumberFindings,
+  runMerge,
+} from './merge-tentative.mjs';
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+/**
+ * @param {Record<string, unknown>} overrides
+ * @returns {Record<string, unknown>}
+ */
+function makeFinding(overrides = {}) {
+  return {
+    id: 'S1-001',
+    lens: 'correctness',
+    location: 'src/a.ts:10',
+    claim: 'claim text',
+    evidence: 'evidence text',
+    tentative_severity: 'minor',
+    confidence: 'medium',
+    ...overrides,
+  };
+}
+
+/**
+ * @param {string} dir
+ * @param {string} base
+ * @param {unknown} content JSON-serialisable content (or a raw string).
+ * @returns {string}
+ */
+function writeScoutFile(dir, base, content) {
+  const p = path.join(dir, base);
+  const text = typeof content === 'string' ? content : `${JSON.stringify(content, null, 2)}\n`;
+  fs.writeFileSync(p, text, 'utf8');
+  return p;
+}
+
+// ---------------------------------------------------------------------------
+// parseArgs
+// ---------------------------------------------------------------------------
+
+test('parseArgs parses --dir and rejects unknown args', () => {
+  const opts = parseArgs(['--dir', '.reviews/x-tentative']);
+  assert.equal(opts.dir, '.reviews/x-tentative');
+  assert.equal(opts.help, false);
+  assert.throws(() => parseArgs(['--bogus']), /unknown argument/);
+});
+
+test('parseArgs defaults dir to null and parses --help', () => {
+  assert.equal(parseArgs([]).dir, null);
+  assert.equal(parseArgs(['--help']).help, true);
+  assert.equal(parseArgs(['-h']).help, true);
+});
+
+// ---------------------------------------------------------------------------
+// pure helpers
+// ---------------------------------------------------------------------------
+
+test('locationFile strips :line and :start-end suffixes', () => {
+  assert.equal(locationFile('services/foo/src/bar.ts:42'), 'services/foo/src/bar.ts');
+  assert.equal(locationFile('path/to/x.ts:10-20'), 'path/to/x.ts');
+  assert.equal(locationFile('path/to/x.ts'), 'path/to/x.ts');
+});
+
+test('firstLineNumber extracts the first line number, null when absent', () => {
+  assert.equal(firstLineNumber('a.ts:42'), 42);
+  assert.equal(firstLineNumber('a.ts:10-20'), 10);
+  assert.equal(firstLineNumber('a.ts'), null);
+});
+
+test('isDuplicate requires same file, same lens, lines within ±5', () => {
+  const base = makeFinding({ location: 'a.ts:10' });
+  assert.equal(isDuplicate(base, makeFinding({ id: 'S2-001', location: 'a.ts:15' })), true);
+  assert.equal(isDuplicate(base, makeFinding({ id: 'S2-002', location: 'a.ts:5' })), true);
+  // 6 lines apart — NOT duplicates.
+  assert.equal(isDuplicate(base, makeFinding({ id: 'S2-003', location: 'a.ts:16' })), false);
+  assert.equal(isDuplicate(base, makeFinding({ id: 'S2-004', location: 'a.ts:4' })), false);
+  // Different file or lens — never duplicates.
+  assert.equal(isDuplicate(base, makeFinding({ id: 'S2-005', location: 'b.ts:10' })), false);
+  assert.equal(
+    isDuplicate(base, makeFinding({ id: 'S2-006', location: 'a.ts:10', lens: 'security' })),
+    false,
+  );
+});
+
+test('isDuplicate: no line number only dupes another no-line finding in the same file', () => {
+  const noLine = makeFinding({ id: 'S1-001', location: 'a.ts' });
+  assert.equal(isDuplicate(noLine, makeFinding({ id: 'S2-001', location: 'a.ts' })), true);
+  assert.equal(isDuplicate(noLine, makeFinding({ id: 'S2-002', location: 'a.ts:3' })), false);
+  assert.equal(isDuplicate(makeFinding({ id: 'S2-003', location: 'a.ts:3' }), noLine), false);
+});
+
+// ---------------------------------------------------------------------------
+// dedupeFindings
+// ---------------------------------------------------------------------------
+
+test('dedupeFindings keeps higher severity and records loser id in related', () => {
+  const minor = makeFinding({ id: 'S1-001', location: 'a.ts:10', tentative_severity: 'minor' });
+  const critical = makeFinding({
+    id: 'S2-001',
+    location: 'a.ts:12',
+    tentative_severity: 'critical',
+  });
+  const { survivors, collapsed } = dedupeFindings([minor, critical]);
+  assert.equal(survivors.length, 1);
+  assert.equal(collapsed, 1);
+  assert.equal(survivors[0].id, 'S2-001');
+  assert.equal(survivors[0].tentative_severity, 'critical');
+  assert.deepEqual(survivors[0].related, ['S1-001']);
+});
+
+test('dedupeFindings ties on severity break by higher confidence', () => {
+  const low = makeFinding({ id: 'S1-001', location: 'a.ts:10', confidence: 'low' });
+  const high = makeFinding({ id: 'S2-001', location: 'a.ts:11', confidence: 'high' });
+  const { survivors } = dedupeFindings([low, high]);
+  assert.equal(survivors.length, 1);
+  assert.equal(survivors[0].id, 'S2-001');
+  assert.deepEqual(survivors[0].related, ['S1-001']);
+});
+
+test('dedupeFindings full tie keeps the first encountered', () => {
+  const first = makeFinding({ id: 'S1-001', location: 'a.ts:10' });
+  const second = makeFinding({ id: 'S2-001', location: 'a.ts:10' });
+  const { survivors } = dedupeFindings([first, second]);
+  assert.equal(survivors.length, 1);
+  assert.equal(survivors[0].id, 'S1-001');
+  assert.deepEqual(survivors[0].related, ['S2-001']);
+});
+
+test('dedupeFindings appends to an existing related array without losing entries', () => {
+  const winner = makeFinding({
+    id: 'S1-001',
+    location: 'a.ts:10',
+    tentative_severity: 'important',
+    related: ['S0-009'],
+  });
+  const loser = makeFinding({ id: 'S2-001', location: 'a.ts:12', tentative_severity: 'minor' });
+  const { survivors } = dedupeFindings([winner, loser]);
+  assert.deepEqual(survivors[0].related, ['S0-009', 'S2-001']);
+});
+
+test('dedupeFindings does not collapse findings 6 lines apart', () => {
+  const a = makeFinding({ id: 'S1-001', location: 'a.ts:10' });
+  const b = makeFinding({ id: 'S2-001', location: 'a.ts:16' });
+  const { survivors, collapsed } = dedupeFindings([a, b]);
+  assert.equal(survivors.length, 2);
+  assert.equal(collapsed, 0);
+});
+
+// ---------------------------------------------------------------------------
+// renumberFindings
+// ---------------------------------------------------------------------------
+
+test('renumberFindings sorts by (file, first line, original id) and assigns F-###', () => {
+  const findings = [
+    makeFinding({ id: 'S3-001', location: 'z.ts:5' }),
+    makeFinding({ id: 'S1-002', location: 'a.ts:100' }),
+    makeFinding({ id: 'S2-001', location: 'a.ts:1' }),
+    makeFinding({ id: 'S1-001', location: 'a.ts:1' }),
+  ];
+  const renumbered = renumberFindings(findings);
+  assert.deepEqual(
+    renumbered.map((f) => [f.id, f.location]),
+    [
+      ['F-001', 'a.ts:1'], // S1-001 before S2-001 (original id tie-break)
+      ['F-002', 'a.ts:1'],
+      ['F-003', 'a.ts:100'],
+      ['F-004', 'z.ts:5'],
+    ],
+  );
+});
+
+test('renumberFindings orders no-line findings before numbered ones in the same file', () => {
+  const renumbered = renumberFindings([
+    makeFinding({ id: 'S1-001', location: 'a.ts:2' }),
+    makeFinding({ id: 'S2-001', location: 'a.ts' }),
+  ]);
+  assert.deepEqual(
+    renumbered.map((f) => [f.id, f.location]),
+    [
+      ['F-001', 'a.ts'],
+      ['F-002', 'a.ts:2'],
+    ],
+  );
+});
+
+// ---------------------------------------------------------------------------
+// runMerge — end-to-end against a temp dir
+// ---------------------------------------------------------------------------
+
+test('runMerge merges findings across 3 scout files and writes merged.json', () => {
+  const dir = tmp('review-merge-');
+  try {
+    writeScoutFile(dir, 'scout-1.json', {
+      findings: [makeFinding({ id: 'S1-001', location: 'src/b.ts:20' })],
+    });
+    writeScoutFile(dir, 'scout-2.json', {
+      findings: [
+        makeFinding({ id: 'S2-001', location: 'src/a.ts:5', lens: 'security' }),
+        makeFinding({ id: 'S2-002', location: 'src/c.ts:1' }),
+      ],
+    });
+    writeScoutFile(dir, 'scout-3.json', {
+      findings: [makeFinding({ id: 'S3-001', location: 'src/a.ts:50' })],
+    });
+
+    const result = runMerge({ dir });
+    assert.equal(result.exitCode, 0, result.message);
+
+    const merged = JSON.parse(fs.readFileSync(path.join(dir, 'merged.json'), 'utf8'));
+    assert.equal(merged.findings.length, 4);
+    assert.deepEqual(
+      merged.findings.map((f) => f.id),
+      ['F-001', 'F-002', 'F-003', 'F-004'],
+    );
+    assert.deepEqual(
+      merged.findings.map((f) => f.location),
+      ['src/a.ts:5', 'src/a.ts:50', 'src/b.ts:20', 'src/c.ts:1'],
+    );
+
+    // Per-file counts, duplicates collapsed, final count in the message.
+    assert.ok(result.message.includes('scout-1.json: 1'));
+    assert.ok(result.message.includes('scout-2.json: 2'));
+    assert.ok(result.message.includes('scout-3.json: 1'));
+    assert.ok(/collapsed:\s*0/.test(result.message));
+    assert.ok(/final:\s*4/.test(result.message));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runMerge dedupes across files, keeps higher severity, records loser in related', () => {
+  const dir = tmp('review-merge-dupe-');
+  try {
+    writeScoutFile(dir, 'scout-1.json', {
+      findings: [
+        makeFinding({ id: 'S1-001', location: 'src/a.ts:10', tentative_severity: 'minor' }),
+      ],
+    });
+    writeScoutFile(dir, 'scout-2.json', {
+      findings: [
+        makeFinding({ id: 'S2-001', location: 'src/a.ts:13', tentative_severity: 'critical' }),
+      ],
+    });
+
+    const result = runMerge({ dir });
+    assert.equal(result.exitCode, 0, result.message);
+
+    const merged = JSON.parse(fs.readFileSync(path.join(dir, 'merged.json'), 'utf8'));
+    assert.equal(merged.findings.length, 1);
+    assert.equal(merged.findings[0].id, 'F-001');
+    assert.equal(merged.findings[0].tentative_severity, 'critical');
+    assert.deepEqual(merged.findings[0].related, ['S1-001']);
+    assert.ok(/collapsed:\s*1/.test(result.message));
+    assert.ok(/final:\s*1/.test(result.message));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runMerge honors the ±5 window — 6 lines apart stay separate', () => {
+  const dir = tmp('review-merge-window-');
+  try {
+    writeScoutFile(dir, 'scout-1.json', {
+      findings: [makeFinding({ id: 'S1-001', location: 'src/a.ts:10' })],
+    });
+    writeScoutFile(dir, 'scout-2.json', {
+      findings: [makeFinding({ id: 'S2-001', location: 'src/a.ts:16' })],
+    });
+
+    const result = runMerge({ dir });
+    assert.equal(result.exitCode, 0, result.message);
+    const merged = JSON.parse(fs.readFileSync(path.join(dir, 'merged.json'), 'utf8'));
+    assert.equal(merged.findings.length, 2);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runMerge ignores an existing merged.json as input', () => {
+  const dir = tmp('review-merge-rerun-');
+  try {
+    writeScoutFile(dir, 'scout-1.json', {
+      findings: [makeFinding({ id: 'S1-001', location: 'src/a.ts:10' })],
+    });
+    writeScoutFile(dir, 'merged.json', {
+      findings: [makeFinding({ id: 'F-099', location: 'stale.ts:1' })],
+    });
+
+    const result = runMerge({ dir });
+    assert.equal(result.exitCode, 0, result.message);
+    const merged = JSON.parse(fs.readFileSync(path.join(dir, 'merged.json'), 'utf8'));
+    assert.equal(merged.findings.length, 1);
+    assert.equal(merged.findings[0].location, 'src/a.ts:10');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runMerge exits 1 naming the file on invalid JSON and writes nothing', () => {
+  const dir = tmp('review-merge-badjson-');
+  try {
+    writeScoutFile(dir, 'scout-1.json', {
+      findings: [makeFinding({ id: 'S1-001' })],
+    });
+    writeScoutFile(dir, 'scout-2.json', '{ not valid json !!!');
+
+    const result = runMerge({ dir });
+    assert.equal(result.exitCode, 1);
+    assert.ok(result.message.includes('scout-2.json'));
+    assert.equal(fs.existsSync(path.join(dir, 'merged.json')), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runMerge exits 1 naming the file when findings array is missing', () => {
+  const dir = tmp('review-merge-nofindings-');
+  try {
+    writeScoutFile(dir, 'scout-1.json', {
+      findings: [makeFinding({ id: 'S1-001' })],
+    });
+    writeScoutFile(dir, 'scout-2.json', { results: [] });
+
+    const result = runMerge({ dir });
+    assert.equal(result.exitCode, 1);
+    assert.ok(result.message.includes('scout-2.json'));
+    assert.ok(/findings/.test(result.message));
+    assert.equal(fs.existsSync(path.join(dir, 'merged.json')), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runMerge exits 1 without --dir, on a missing dir, and on an empty dir', () => {
+  const noDir = runMerge({ dir: null });
+  assert.equal(noDir.exitCode, 1);
+  assert.ok(/--dir/.test(noDir.message));
+
+  const missing = runMerge({ dir: path.join(tmpdir(), 'no-such-review-merge-dir') });
+  assert.equal(missing.exitCode, 1);
+
+  const dir = tmp('review-merge-empty-');
+  try {
+    const empty = runMerge({ dir });
+    assert.equal(empty.exitCode, 1);
+    assert.ok(/no input/i.test(empty.message));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/review/new-review.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Scaffold a new thorough-code-review JSON sidecar under `.reviews/`.
+ *
+ * Removes the hand-generated-timestamp / slug / git-SHA failure mode: this
+ * stamps the canonical ISO-UTC time, derives the review id, captures base/head
+ * SHAs from git, and writes a schema-valid skeleton with empty findings. The
+ * agent then fills in findings and runs `review:render` + `review:export`.
+ *
+ * Usage:
+ *   review new <scope-slug> [options]
+ *
+ * Options:
+ *   --type <t>          uncommitted | branch | paths | commit_range | file
+ *   --kind <k>          review | reverify          (default: review)
+ *   --description "..." Human scope description
+ *   --lenses a,b,c      Comma list (default: all nine)
+ *   --paths p1,p2       Comma list of scoped paths
+ *   --parent <id>       Parent review_id (required for --kind reverify)
+ *   --base-branch <b>   Merge-base branch for --type branch (default: main)
+ *   --reviews-dir <dir> Output dir (default: .reviews)
+ *   --no-git            Skip git SHA capture
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { REVIEWS_DIR, LENSES, buildReviewSkeleton } from './lib.mjs';
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = {
+    slug: null,
+    type: 'branch',
+    kind: 'review',
+    description: '',
+    lenses: [...LENSES],
+    paths: /** @type {string[]} */ ([]),
+    parent: null,
+    baseBranch: 'main',
+    reviewsDir: REVIEWS_DIR,
+    git: true,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--type') opts.type = argv[++i];
+    else if (arg === '--kind') opts.kind = argv[++i];
+    else if (arg === '--description') opts.description = argv[++i];
+    else if (arg === '--lenses') opts.lenses = splitList(argv[++i]);
+    else if (arg === '--paths') opts.paths = splitList(argv[++i]);
+    else if (arg === '--parent') opts.parent = argv[++i];
+    else if (arg === '--base-branch') opts.baseBranch = argv[++i];
+    else if (arg === '--reviews-dir') opts.reviewsDir = argv[++i];
+    else if (arg === '--no-git') opts.git = false;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg.startsWith('--')) throw new Error(`unknown argument: ${arg}`);
+    else if (opts.slug == null) opts.slug = arg;
+    else throw new Error(`unexpected positional argument: ${arg}`);
+  }
+
+  return opts;
+}
+
+/**
+ * @param {string} value
+ * @returns {string[]}
+ */
+function splitList(value) {
+  return String(value)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} baseBranch
+ * @param {('uncommitted'|'branch'|'paths'|'commit_range'|'file')} type
+ * @returns {{ baseSha?: string, headSha?: string }}
+ */
+function captureGit(cwd, baseBranch, type) {
+  const run = (args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+  /** @type {{ baseSha?: string, headSha?: string }} */
+  const out = {};
+  try {
+    out.headSha = run(['rev-parse', 'HEAD']);
+  } catch {
+    return out;
+  }
+  if (type === 'branch') {
+    try {
+      out.baseSha = run(['merge-base', baseBranch, 'HEAD']);
+    } catch {
+      /* base branch may not exist locally — leave undefined */
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {ReturnType<typeof parseArgs>} opts
+ * @param {{ now: Date, cwd?: string, gitImpl?: typeof captureGit }} ctx
+ * @returns {{ exitCode: number; message: string; jsonPath?: string }}
+ */
+export function runNew(opts, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  if (!opts.slug) {
+    return { exitCode: 1, message: 'a scope-slug positional argument is required' };
+  }
+
+  const git = opts.git ? (ctx.gitImpl ?? captureGit)(cwd, opts.baseBranch, opts.type) : {};
+
+  let built;
+  try {
+    built = buildReviewSkeleton({
+      slug: opts.slug,
+      type: opts.type,
+      kind: opts.kind,
+      description: opts.description,
+      lenses: opts.lenses,
+      paths: opts.paths,
+      parentReport: opts.parent ?? undefined,
+      baseSha: git.baseSha,
+      headSha: git.headSha,
+      now: ctx.now,
+    });
+  } catch (err) {
+    return { exitCode: 1, message: /** @type {Error} */ (err).message };
+  }
+
+  const reviewsDir = path.resolve(cwd, opts.reviewsDir ?? REVIEWS_DIR);
+  fs.mkdirSync(reviewsDir, { recursive: true });
+  const jsonPath = path.join(reviewsDir, `${built.fileBase}.json`);
+
+  if (fs.existsSync(jsonPath)) {
+    return { exitCode: 1, message: `refusing to overwrite existing report: ${jsonPath}` };
+  }
+
+  fs.writeFileSync(jsonPath, `${JSON.stringify(built.report, null, 2)}\n`, 'utf8');
+
+  const message = [
+    `Scaffolded review: ${jsonPath}`,
+    `  review_id: ${built.reviewId}`,
+    `  lenses:    ${opts.lenses.join(', ')}`,
+    git.headSha ? `  head_sha:  ${git.headSha}` : '  head_sha:  (git capture skipped)',
+    '',
+    'Next: fill findings in the JSON, then:',
+    `  review render --file ${path.relative(cwd, jsonPath)}`,
+    '  review export',
+  ].join('\n');
+
+  return { exitCode: 0, message, jsonPath };
+}
+
+function printHelp() {
+  console.log(`Usage: review new <scope-slug> [options]
+
+Scaffold a schema-valid review JSON skeleton under .reviews/.
+
+Options:
+  --type <t>          uncommitted | branch | paths | commit_range | file (default: branch)
+  --kind <k>          review | reverify (default: review)
+  --description "..." Human scope description
+  --lenses a,b,c      Comma list of lenses (default: all nine)
+  --paths p1,p2       Comma list of scoped paths
+  --parent <id>       Parent review_id (required for --kind reverify)
+  --base-branch <b>   Merge-base branch for --type branch (default: main)
+  --reviews-dir <dir> Output directory (default: .reviews)
+  --no-git            Skip git SHA capture
+  -h, --help          Show this help
+`);
+}
+
+function main() {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      printHelp();
+      process.exit(0);
+    }
+    const result = runNew(opts, { now: new Date() });
+    console.log(result.message);
+    process.exit(result.exitCode);
+  } catch (err) {
+    console.error(/** @type {Error} */ (err).message);
+    process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMain) {
+  main();
+}

package/src/review/render.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Render the human-readable Markdown report from a review JSON sidecar.
+ *
+ * JSON is the single source of truth; this regenerates the paired `.md` so the
+ * two can never drift. Validates before rendering.
+ *
+ * Usage:
+ *   review render [--file <json>] [--reviews-dir <dir>] [--stdout]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { REVIEWS_DIR, findLatestReviewJson, renderMarkdown, validateReport } from './lib.mjs';
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = { file: null, reviewsDir: REVIEWS_DIR, stdout: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--file') opts.file = argv[++i];
+    else if (arg === '--reviews-dir') opts.reviewsDir = argv[++i];
+    else if (arg === '--stdout') opts.stdout = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return opts;
+}
+
+/**
+ * @param {ReturnType<typeof parseArgs>} opts
+ * @param {string} [cwd]
+ * @returns {{ exitCode: number; message: string }}
+ */
+export function runRender(opts, cwd = process.cwd()) {
+  const reviewsDir = path.resolve(cwd, opts.reviewsDir ?? REVIEWS_DIR);
+  const jsonPath = opts.file
+    ? path.isAbsolute(opts.file)
+      ? opts.file
+      : path.resolve(cwd, opts.file)
+    : findLatestReviewJson(reviewsDir);
+
+  if (!jsonPath) return { exitCode: 1, message: `no review JSON found in ${reviewsDir}` };
+  if (!fs.existsSync(jsonPath)) return { exitCode: 1, message: `file not found: ${jsonPath}` };
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch (err) {
+    return { exitCode: 1, message: `invalid JSON: ${/** @type {Error} */ (err).message}` };
+  }
+
+  const validation = validateReport(parsed);
+  if (!validation.ok) {
+    return {
+      exitCode: 1,
+      message: `validation failed for ${jsonPath}:\n${validation.errors
+        .map((e) => `  - ${e}`)
+        .join('\n')}`,
+    };
+  }
+
+  const md = `${renderMarkdown(validation.report)}\n`;
+  if (opts.stdout) return { exitCode: 0, message: md };
+
+  const mdPath = jsonPath.replace(/\.json$/, '.md');
+  fs.writeFileSync(mdPath, md, 'utf8');
+  return { exitCode: 0, message: `rendered: ${mdPath}` };
+}
+
+function printHelp() {
+  console.log(`Usage: review render [options]
+
+Regenerates the paired Markdown from a review JSON sidecar.
+
+Options:
+  --file <path>       Review JSON (default: latest *-review.json in .reviews/)
+  --reviews-dir <dir> Reviews directory (default: .reviews)
+  --stdout            Print Markdown to stdout instead of writing the .md file
+  -h, --help          Show this help
+`);
+}
+
+function main() {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      printHelp();
+      process.exit(0);
+    }
+    const result = runRender(opts);
+    process.stdout.write(result.message.endsWith('\n') ? result.message : `${result.message}\n`);
+    process.exit(result.exitCode);
+  } catch (err) {
+    console.error(/** @type {Error} */ (err).message);
+    process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMain) {
+  main();
+}