@izkac/forgekit 0.1.0

package/src/review/lib.test.mjs

@@ -0,0 +1,266 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  validateReport,
+  renderMarkdown,
+  buildReviewSkeleton,
+  compactStamp,
+  slugify,
+  countOpenAtOrAbove,
+  countByVerdict,
+} from './lib.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const validFixture = JSON.parse(
+  fs.readFileSync(path.join(__dirname, 'fixtures', 'valid-review.json'), 'utf8'),
+);
+
+// --- stamping / slug ---
+
+test('compactStamp produces a compact UTC review stamp', () => {
+  assert.equal(compactStamp(new Date('2026-06-05T16:00:00.000Z')), '20260605T160000Z');
+});
+
+test('slugify normalizes free text', () => {
+  assert.equal(slugify('Mercury VAT / checkout!'), 'mercury-vat-checkout');
+  assert.equal(slugify('   '), 'review');
+});
+
+// --- buildReviewSkeleton ---
+
+test('buildReviewSkeleton yields a schema-valid review', () => {
+  const { reviewId, fileBase, report } = buildReviewSkeleton({
+    slug: 'mercury-vat',
+    type: 'branch',
+    now: new Date('2026-06-05T16:00:00.000Z'),
+    headSha: 'abc123',
+  });
+  assert.equal(reviewId, '20260605T160000Z-mercury-vat');
+  assert.equal(fileBase, '20260605T160000Z-mercury-vat-review');
+  assert.equal(report.scope.head_sha, 'abc123');
+  const result = validateReport(report);
+  assert.equal(result.ok, true, JSON.stringify(result.errors));
+});
+
+test('buildReviewSkeleton requires parent for reverify', () => {
+  assert.throws(
+    () => buildReviewSkeleton({ slug: 'x', kind: 'reverify', now: new Date('2026-06-05T16:00:00.000Z') }),
+    /reverify/,
+  );
+});
+
+test('buildReviewSkeleton reverify with parent is valid', () => {
+  const { fileBase, report } = buildReviewSkeleton({
+    slug: 'x',
+    kind: 'reverify',
+    parentReport: '20260101T000000Z-x',
+    now: new Date('2026-06-05T16:00:00.000Z'),
+  });
+  assert.ok(fileBase.endsWith('-reverify'));
+  assert.equal(report.parent_report, '20260101T000000Z-x');
+});
+
+// --- hardened validation ---
+
+test('rejects non-ISO created_at', () => {
+  const bad = { ...validFixture, created_at: 'June 5 2026' };
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('created_at')));
+});
+
+test('rejects summary counts that disagree with findings', () => {
+  const bad = { ...validFixture, summary: { ...validFixture.summary, confirmed: 5 } };
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('summary.confirmed')));
+});
+
+test('rejects tentative_count below findings count', () => {
+  const bad = { ...validFixture, summary: { ...validFixture.summary, tentative_count: 1 } };
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('tentative_count')));
+});
+
+test('rejects downgraded finding without original_severity', () => {
+  const bad = {
+    ...validFixture,
+    summary: { tentative_count: 1, downgraded: 1 },
+    findings: [
+      {
+        id: 'F-001',
+        lens: 'security',
+        location: 'a.ts:1',
+        claim: 'x',
+        severity: 'minor',
+        verdict: 'downgraded',
+        verdict_reason: 'lowered',
+      },
+    ],
+  };
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('original_severity')));
+});
+
+test('accepts a finding with a valid second_opinion', () => {
+  const ok = {
+    ...validFixture,
+    summary: { tentative_count: 1, confirmed: 1 },
+    findings: [
+      {
+        id: 'F-001',
+        lens: 'security',
+        location: 'a.ts:1',
+        claim: 'auth bypass',
+        severity: 'critical',
+        verdict: 'confirmed',
+        verdict_reason: 'real',
+        second_opinion: { verdict: 'confirmed', verdict_reason: 'second skeptic agrees', agrees: true },
+      },
+    ],
+  };
+  const result = validateReport(ok);
+  assert.equal(result.ok, true, JSON.stringify(result.errors));
+});
+
+test('rejects a malformed coverage ledger', () => {
+  const bad = {
+    ...validFixture,
+    coverage: { lenses_without_findings: [{ lens: 'not-a-lens', reason: 'x' }] },
+  };
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('lenses_without_findings')));
+});
+
+test('accepts a report with valid stats', () => {
+  const ok = {
+    ...validFixture,
+    stats: {
+      scouts: 3,
+      skeptics_dedicated: 2,
+      skeptics_batched: 4,
+      grounded_skips: 1,
+      carried_forward: 0,
+      second_opinions: 1,
+    },
+  };
+  const result = validateReport(ok);
+  assert.equal(result.ok, true, JSON.stringify(result.errors));
+});
+
+test('report without stats is still valid', () => {
+  const result = validateReport(validFixture);
+  assert.equal(result.ok, true, JSON.stringify(result.errors));
+});
+
+test('rejects an unknown stats key', () => {
+  const bad = { ...validFixture, stats: { scouts: 1, surprise: 2 } };
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('stats.surprise')));
+});
+
+test('rejects non-integer and negative stats values', () => {
+  const nonInteger = validateReport({ ...validFixture, stats: { scouts: 1.5 } });
+  assert.equal(nonInteger.ok, false);
+  assert.ok(nonInteger.errors.some((e) => e.includes('stats.scouts')));
+
+  const negative = validateReport({ ...validFixture, stats: { carried_forward: -1 } });
+  assert.equal(negative.ok, false);
+  assert.ok(negative.errors.some((e) => e.includes('stats.carried_forward')));
+});
+
+test('rejects non-object stats', () => {
+  const result = validateReport({ ...validFixture, stats: [3] });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('stats must be an object')));
+});
+
+// --- graded fail-on ---
+
+test('countOpenAtOrAbove respects the severity threshold', () => {
+  const report = {
+    findings: [
+      { severity: 'important', verdict: 'confirmed' },
+      { severity: 'critical', verdict: 'still_open' },
+      { severity: 'minor', verdict: 'confirmed' },
+      { severity: 'critical', verdict: 'false_positive' },
+    ],
+  };
+  assert.equal(countOpenAtOrAbove(report, 'critical'), 1);
+  assert.equal(countOpenAtOrAbove(report, 'important'), 2);
+  assert.equal(countOpenAtOrAbove(report, 'minor'), 3);
+});
+
+// --- render ---
+
+test('renderMarkdown reflects JSON as the single source of truth', () => {
+  const report = {
+    ...validFixture,
+    summary: {
+      ...validFixture.summary,
+      headline: 'Reviewed 1 file; 1 confirmed, 1 false positive.',
+      top_actions: ['Add empty-cart guard'],
+    },
+  };
+  const md = renderMarkdown(report);
+  assert.ok(md.startsWith('# Code review —'));
+  assert.ok(md.includes('Reviewed 1 file'));
+  assert.ok(md.includes('## Important')); // F-001 important confirmed in main body
+  assert.ok(md.includes('Add empty-cart guard'));
+  assert.ok(md.includes('## Appendix A — Rejected findings')); // F-002 false positive
+  assert.ok(md.includes('F-002'));
+  // false positives never appear in the main severity body
+  const mainBody = md.split('## Appendix A')[0];
+  assert.ok(!mainBody.includes('SQL injection'));
+});
+
+test('renderMarkdown shows downgrade provenance and second opinions', () => {
+  const report = {
+    ...validFixture,
+    summary: { tentative_count: 1, downgraded: 1 },
+    findings: [
+      {
+        id: 'F-001',
+        lens: 'architecture',
+        location: 'a.ts:1',
+        claim: 'coupling',
+        severity: 'minor',
+        original_severity: 'important',
+        verdict: 'downgraded',
+        verdict_reason: 'documented',
+        second_opinion: { verdict: 'downgraded', verdict_reason: 'concur', agrees: true },
+      },
+    ],
+  };
+  const md = renderMarkdown(report);
+  assert.ok(md.includes('minor (was important)'));
+  assert.ok(md.includes('Second skeptic'));
+  assert.ok(md.includes('concur'));
+});
+
+test('renderMarkdown includes pipeline stats when present and omits them otherwise', () => {
+  const md = renderMarkdown({
+    ...validFixture,
+    stats: { scouts: 3, skeptics_batched: 2, second_opinions: 1 },
+  });
+  assert.ok(md.includes('## Pipeline stats'));
+  assert.ok(md.includes('**Scouts:** 3'));
+  assert.ok(md.includes('**Batched skeptics:** 2'));
+  assert.ok(md.includes('**Second opinions:** 1'));
+
+  const withoutStats = renderMarkdown(validFixture);
+  assert.ok(!withoutStats.includes('## Pipeline stats'));
+});
+
+test('countByVerdict zero-fills every verdict bucket', () => {
+  const counts = countByVerdict({ findings: [] });
+  assert.equal(counts.confirmed, 0);
+  assert.equal(counts.regressed, 0);
+});

package/src/review/merge-tentative.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+/**
+ * Merge tentative scout findings from a directory of per-scout JSON files
+ * into a single deduplicated `merged.json`.
+ *
+ * Every `*.json` file in the directory (except `merged.json`) is read; each
+ * must have shape `{ findings: [...] }` where a finding carries the scout
+ * tentative fields (`id`, `lens`, `location`, `claim`, `evidence`, optional
+ * `context`/`related`, `tentative_severity`, `confidence`).
+ *
+ * Two findings are duplicates when they point at the same location FILE
+ * (line suffix stripped), their first line numbers are within ±5 (a finding
+ * without a line number only dupes another no-line finding in the same
+ * file), and they share the same `lens`. The survivor is the one with the
+ * higher `tentative_severity` (critical > important > minor), tie-broken by
+ * higher `confidence` (high > medium > low), tie-broken by first
+ * encountered; the discarded finding's original id is appended to the
+ * survivor's `related` array.
+ *
+ * Survivors are renumbered `F-001`, `F-002`, ... in stable order sorted by
+ * (location file, first line number ascending, original id) and written to
+ * `<dir>/merged.json` as `{ findings: [...] }`.
+ *
+ * A malformed input file (invalid JSON, or no `findings` array) exits 1
+ * naming the offending file, and merged.json is NOT written.
+ *
+ * Usage:
+ *   review merge --dir <path>
+ *
+ * Options:
+ *   --dir <path>  Directory of scout tentative JSON files (required),
+ *                 e.g. .reviews/<id>-tentative/
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const LINE_WINDOW = 5;
+
+/** @type {Record<string, number>} */
+const SEVERITY_RANK = { critical: 3, important: 2, minor: 1 };
+
+/** @type {Record<string, number>} */
+const CONFIDENCE_RANK = { high: 3, medium: 2, low: 1 };
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = {
+    dir: null,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--dir') opts.dir = argv[++i];
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+
+  return opts;
+}
+
+/**
+ * Extract the file path from a finding location by stripping a trailing
+ * `:line` or `:start-end` suffix.
+ *
+ * @param {string} location
+ * @returns {string}
+ */
+export function locationFile(location) {
+  return String(location).replace(/:\d+(-\d+)?$/, '');
+}
+
+/**
+ * First line number of a finding location (`a.ts:42` → 42, `a.ts:10-20` →
+ * 10), or null when the location has no line suffix.
+ *
+ * @param {string} location
+ * @returns {number | null}
+ */
+export function firstLineNumber(location) {
+  const m = /:(\d+)(-\d+)?$/.exec(String(location));
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Whether two findings are duplicates: same location file, same lens, and
+ * first line numbers within ±LINE_WINDOW. A finding without a line number
+ * only dupes another no-line finding in the same file.
+ *
+ * @param {{ location?: unknown, lens?: unknown }} a
+ * @param {{ location?: unknown, lens?: unknown }} b
+ * @returns {boolean}
+ */
+export function isDuplicate(a, b) {
+  if (a.lens !== b.lens) return false;
+  const fileA = locationFile(/** @type {string} */ (a.location ?? ''));
+  const fileB = locationFile(/** @type {string} */ (b.location ?? ''));
+  if (fileA !== fileB) return false;
+  const lineA = firstLineNumber(/** @type {string} */ (a.location ?? ''));
+  const lineB = firstLineNumber(/** @type {string} */ (b.location ?? ''));
+  if (lineA === null || lineB === null) return lineA === lineB;
+  return Math.abs(lineA - lineB) <= LINE_WINDOW;
+}
+
+/**
+ * @param {{ tentative_severity?: unknown, confidence?: unknown }} finding
+ * @returns {[number, number]} [severityRank, confidenceRank]
+ */
+function rank(finding) {
+  return [
+    SEVERITY_RANK[/** @type {string} */ (finding.tentative_severity)] ?? 0,
+    CONFIDENCE_RANK[/** @type {string} */ (finding.confidence)] ?? 0,
+  ];
+}
+
+/**
+ * Union of related-id arrays plus the discarded finding's own id, preserving
+ * first-seen order without duplicates.
+ *
+ * @param {Record<string, unknown>} winner
+ * @param {Record<string, unknown>} loser
+ * @returns {string[]}
+ */
+function mergedRelated(winner, loser) {
+  const out = [];
+  const seen = new Set();
+  const winnerRelated = Array.isArray(winner.related) ? winner.related : [];
+  const loserRelated = Array.isArray(loser.related) ? loser.related : [];
+  for (const id of [...winnerRelated, ...loserRelated, loser.id]) {
+    if (id === undefined || seen.has(id)) continue;
+    seen.add(id);
+    out.push(/** @type {string} */ (id));
+  }
+  return out;
+}
+
+/**
+ * Collapse duplicate findings (in encounter order). Each newcomer is
+ * compared against the current survivors; on a duplicate the higher-ranked
+ * finding survives and absorbs the loser's original id (and any prior
+ * `related` entries) into its `related` array.
+ *
+ * @param {Array<Record<string, unknown>>} findings In encounter order.
+ * @returns {{ survivors: Array<Record<string, unknown>>, collapsed: number }}
+ */
+export function dedupeFindings(findings) {
+  /** @type {Array<Record<string, unknown>>} */
+  const survivors = [];
+  let collapsed = 0;
+
+  for (const finding of findings) {
+    const candidate = { ...finding };
+    const index = survivors.findIndex((s) => isDuplicate(s, candidate));
+    if (index === -1) {
+      survivors.push(candidate);
+      continue;
+    }
+
+    collapsed += 1;
+    const incumbent = survivors[index];
+    const [sevA, confA] = rank(incumbent);
+    const [sevB, confB] = rank(candidate);
+    const candidateWins = sevB > sevA || (sevB === sevA && confB > confA);
+    const winner = candidateWins ? candidate : incumbent;
+    const loser = candidateWins ? incumbent : candidate;
+    winner.related = mergedRelated(winner, loser);
+    survivors[index] = winner;
+  }
+
+  return { survivors, collapsed };
+}
+
+/**
+ * Renumber findings `F-001`, `F-002`, ... in stable order sorted by
+ * (location file, first line number ascending — no-line first, original id).
+ *
+ * @param {Array<Record<string, unknown>>} findings
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function renumberFindings(findings) {
+  const sorted = [...findings].sort((a, b) => {
+    const locA = /** @type {string} */ (a.location ?? '');
+    const locB = /** @type {string} */ (b.location ?? '');
+    const fileCmp = locationFile(locA).localeCompare(locationFile(locB));
+    if (fileCmp !== 0) return fileCmp;
+    const lineA = firstLineNumber(locA) ?? -1;
+    const lineB = firstLineNumber(locB) ?? -1;
+    if (lineA !== lineB) return lineA - lineB;
+    return String(a.id ?? '').localeCompare(String(b.id ?? ''));
+  });
+  return sorted.map((finding, i) => ({
+    ...finding,
+    id: `F-${String(i + 1).padStart(3, '0')}`,
+  }));
+}
+
+/**
+ * @param {{ dir?: string | null }} opts
+ * @param {string} [cwd]
+ * @returns {{ exitCode: number; message: string }}
+ */
+export function runMerge(opts, cwd = process.cwd()) {
+  if (!opts.dir) {
+    return { exitCode: 1, message: '--dir <path> is required' };
+  }
+
+  const dir = path.isAbsolute(opts.dir) ? opts.dir : path.resolve(cwd, opts.dir);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return { exitCode: 1, message: `not a directory: ${dir}` };
+  }
+
+  const inputNames = fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith('.json') && name !== 'merged.json')
+    .sort();
+  if (inputNames.length === 0) {
+    return { exitCode: 1, message: `no input *.json files in ${dir}` };
+  }
+
+  /** @type {Array<Record<string, unknown>>} */
+  const allFindings = [];
+  const lines = [];
+  for (const name of inputNames) {
+    const full = path.join(dir, name);
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
+    } catch (err) {
+      return {
+        exitCode: 1,
+        message: `invalid JSON in ${full}: ${/** @type {Error} */ (err).message}`,
+      };
+    }
+    if (!parsed || !Array.isArray(parsed.findings)) {
+      return { exitCode: 1, message: `no findings array in ${full}` };
+    }
+    allFindings.push(...parsed.findings);
+    lines.push(`${name}: ${parsed.findings.length} findings`);
+  }
+
+  const { survivors, collapsed } = dedupeFindings(allFindings);
+  const merged = renumberFindings(survivors);
+
+  const outPath = path.join(dir, 'merged.json');
+  fs.writeFileSync(outPath, `${JSON.stringify({ findings: merged }, null, 2)}\n`, 'utf8');
+
+  lines.push('');
+  lines.push(`duplicates collapsed: ${collapsed}`);
+  lines.push(`final: ${merged.length} findings`);
+  lines.push(`wrote: ${outPath}`);
+  return { exitCode: 0, message: lines.join('\n') };
+}
+
+function printHelp() {
+  console.log(`Usage: review merge --dir <path>
+
+Merge tentative scout findings from every *.json file in the directory
+(except merged.json) into a deduplicated, renumbered <dir>/merged.json.
+
+Options:
+  --dir <path>  Directory of scout tentative JSON files (required),
+                e.g. .reviews/<id>-tentative/
+  -h, --help    Show this help
+`);
+}
+
+function main() {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      printHelp();
+      process.exit(0);
+    }
+    const result = runMerge(opts);
+    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();
+}