@izkac/forgekit 0.1.0

package/src/review/export.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Export and validate thorough code review JSON sidecars for CI.
+ *
+ * Usage:
+ *   review export [--file <json>] [--out <dir>] [--fail-on critical]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  REVIEWS_DIR,
+  findLatestReviewJson,
+  formatSummary,
+  countOpenAtOrAbove,
+  renderMarkdown,
+  validateReport,
+} from './lib.mjs';
+
+const FAIL_ON_LEVELS = new Set(['critical', 'important', 'minor']);
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = {
+    file: null,
+    out: null,
+    failOn: null,
+    failOnCritical: false,
+    renderMd: false,
+    reviewsDir: REVIEWS_DIR,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--file') {
+      opts.file = argv[++i];
+    } else if (arg === '--out') {
+      opts.out = argv[++i];
+    } else if (arg === '--render-md') {
+      opts.renderMd = true;
+    } else if (arg === '--fail-on') {
+      const level = argv[++i];
+      if (!FAIL_ON_LEVELS.has(level)) {
+        throw new Error(`unsupported --fail-on value: ${level} (expected critical|important|minor)`);
+      }
+      opts.failOn = level;
+      opts.failOnCritical = level === 'critical';
+    } else if (arg === '--reviews-dir') {
+      opts.reviewsDir = argv[++i];
+    } 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 runExport(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 report = validation.report;
+  const lines = [`OK ${jsonPath}`, formatSummary(report)];
+
+  if (opts.renderMd) {
+    const mdPath = jsonPath.replace(/\.json$/, '.md');
+    fs.writeFileSync(mdPath, `${renderMarkdown(report)}\n`, 'utf8');
+    lines.push(`rendered: ${mdPath}`);
+  }
+
+  if (opts.out) {
+    const outDir = path.resolve(cwd, opts.out);
+    fs.mkdirSync(outDir, { recursive: true });
+    const base = path.basename(jsonPath);
+    const mdBase = base.replace(/\.json$/, '.md');
+    const jsonDest = path.join(outDir, base);
+    const mdSrc = path.join(path.dirname(jsonPath), mdBase);
+    fs.copyFileSync(jsonPath, jsonDest);
+    if (fs.existsSync(mdSrc)) {
+      fs.copyFileSync(mdSrc, path.join(outDir, mdBase));
+      lines.push(`copied: ${jsonDest}, ${path.join(outDir, mdBase)}`);
+    } else {
+      lines.push(`copied: ${jsonDest} (no paired .md at ${mdSrc})`);
+    }
+  }
+
+  const failLevel = opts.failOn ?? (opts.failOnCritical ? 'critical' : null);
+  if (failLevel) {
+    const openCount = countOpenAtOrAbove(report, failLevel);
+    if (openCount > 0) {
+      lines.push(`FAIL: ${openCount} open ${failLevel}+ finding(s)`);
+      return { exitCode: 1, message: lines.join('\n') };
+    }
+  }
+
+  return { exitCode: 0, message: lines.join('\n') };
+}
+
+function printHelp() {
+  console.log(`Usage: review export [options]
+
+Options:
+  --file <path>       Review JSON (default: latest *-review.json in .reviews/)
+  --out <dir>         Copy JSON (+ paired .md if present) to directory
+  --render-md         (Re)generate the paired Markdown from the JSON first
+  --fail-on <level>   Exit 1 if any open finding at/above level remains
+                      (critical | important | minor)
+  --reviews-dir <dir> Reviews directory (default: .reviews)
+  -h, --help          Show this help
+`);
+}
+
+function main() {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      printHelp();
+      process.exit(0);
+    }
+    const result = runExport(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();
+}

package/src/review/export.test.mjs

@@ -0,0 +1,197 @@
+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 { fileURLToPath } from 'node:url';
+import {
+  validateReport,
+  findLatestReviewJson,
+  countOpenCritical,
+  formatSummary,
+} from './lib.mjs';
+import { parseArgs, runExport } from './export.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixturePath = path.join(__dirname, 'fixtures', 'valid-review.json');
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+const validFixture = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+
+test('validateReport accepts valid fixture', () => {
+  const result = validateReport(validFixture);
+  assert.equal(result.ok, true);
+});
+
+test('validateReport rejects missing review_id', () => {
+  const bad = { ...validFixture };
+  delete bad.review_id;
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('review_id')));
+});
+
+test('validateReport rejects reverify without parent_report', () => {
+  const bad = {
+    ...validFixture,
+    kind: 'reverify',
+    findings: [
+      {
+        ...validFixture.findings[0],
+        verdict: 'still_open',
+      },
+    ],
+  };
+  const result = validateReport(bad);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes('parent_report')));
+});
+
+test('countOpenCritical counts confirmed critical only', () => {
+  const withCritical = {
+    ...validFixture,
+    findings: [
+      {
+        id: 'F-001',
+        lens: 'security',
+        location: 'a.ts:1',
+        claim: 'x',
+        severity: 'critical',
+        verdict: 'confirmed',
+        verdict_reason: 'real',
+      },
+    ],
+  };
+  assert.equal(countOpenCritical(withCritical), 1);
+  assert.equal(countOpenCritical(validFixture), 0);
+});
+
+test('parseArgs handles --fail-on critical', () => {
+  const opts = parseArgs(['--file', 'x.json', '--fail-on', 'critical']);
+  assert.equal(opts.failOnCritical, true);
+  assert.equal(opts.file, 'x.json');
+});
+
+test('runExport succeeds on fixture', () => {
+  const result = runExport({ file: fixturePath, out: null, failOnCritical: false });
+  assert.equal(result.exitCode, 0);
+  assert.ok(result.message.includes('OK'));
+  assert.ok(result.message.includes('review_id'));
+});
+
+test('runExport --fail-on critical fails when critical confirmed', () => {
+  const tmpDir = tmp('review-export-');
+  try {
+    const criticalReport = {
+      ...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: 'missing check',
+        },
+      ],
+    };
+    const jsonPath = path.join(tmpDir, '20260605-smoke-review.json');
+    fs.writeFileSync(jsonPath, JSON.stringify(criticalReport));
+
+    const result = runExport(
+      { file: jsonPath, out: null, failOnCritical: true, reviewsDir: '.reviews' },
+      tmpDir,
+    );
+    assert.equal(result.exitCode, 1);
+    assert.ok(result.message.includes('open critical'));
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('parseArgs accepts --fail-on important and --render-md', () => {
+  const opts = parseArgs(['--fail-on', 'important', '--render-md']);
+  assert.equal(opts.failOn, 'important');
+  assert.equal(opts.failOnCritical, false);
+  assert.equal(opts.renderMd, true);
+});
+
+test('parseArgs rejects an unsupported --fail-on level', () => {
+  assert.throws(() => parseArgs(['--fail-on', 'nope']), /unsupported --fail-on/);
+});
+
+test('runExport --fail-on important catches an open important finding', () => {
+  const tmpDir = tmp('review-important-');
+  try {
+    const report = {
+      ...validFixture,
+      summary: { tentative_count: 1, confirmed: 1 },
+      findings: [
+        {
+          id: 'F-001',
+          lens: 'correctness',
+          location: 'a.ts:1',
+          claim: 'edge case',
+          severity: 'important',
+          verdict: 'confirmed',
+          verdict_reason: 'no guard',
+        },
+      ],
+    };
+    const jsonPath = path.join(tmpDir, '20260605-imp-review.json');
+    fs.writeFileSync(jsonPath, JSON.stringify(report));
+
+    // critical gate passes (no critical), important gate fails
+    assert.equal(runExport({ file: jsonPath, failOn: 'critical' }, tmpDir).exitCode, 0);
+    const imp = runExport({ file: jsonPath, failOn: 'important' }, tmpDir);
+    assert.equal(imp.exitCode, 1);
+    assert.ok(imp.message.includes('open important+'));
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('runExport --render-md regenerates the paired markdown', () => {
+  const tmpDir = tmp('review-rendermd-');
+  try {
+    const jsonPath = path.join(tmpDir, '20260605-r-review.json');
+    fs.writeFileSync(jsonPath, JSON.stringify(validFixture));
+    const result = runExport({ file: jsonPath, renderMd: true }, tmpDir);
+    assert.equal(result.exitCode, 0, result.message);
+    assert.ok(fs.existsSync(jsonPath.replace(/\.json$/, '.md')));
+    assert.ok(result.message.includes('rendered:'));
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('findLatestReviewJson picks newest non-reverify file', () => {
+  const tmpDir = tmp('review-find-');
+  try {
+    const older = path.join(tmpDir, '20260101-old-review.json');
+    const newer = path.join(tmpDir, '20260201-new-review.json');
+    const reverify = path.join(tmpDir, '20260202-scope-reverify.json');
+    fs.writeFileSync(older, '{}');
+    fs.writeFileSync(newer, '{}');
+    fs.writeFileSync(reverify, '{}');
+
+    const olderTime = Date.now() - 10_000;
+    const newerTime = Date.now();
+    fs.utimesSync(older, olderTime / 1000, olderTime / 1000);
+    fs.utimesSync(newer, newerTime / 1000, newerTime / 1000);
+
+    assert.equal(findLatestReviewJson(tmpDir), newer);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('formatSummary includes scope and counts', () => {
+  const text = formatSummary(validFixture);
+  assert.ok(text.includes('checkout-sessions'));
+  assert.ok(text.includes('confirmed: 1'));
+});

package/src/review/fixtures/valid-review.json

@@ -0,0 +1,42 @@
+{
+  "review_id": "20260605T160000Z-mercury-checkout-smoke",
+  "kind": "review",
+  "created_at": "2026-06-05T16:00:00.000Z",
+  "scope": {
+    "type": "paths",
+    "description": "services/mercury/src/services/checkout-sessions.ts",
+    "paths": ["services/mercury/src/services/checkout-sessions.ts"]
+  },
+  "lenses": ["security", "correctness"],
+  "summary": {
+    "tentative_count": 2,
+    "confirmed": 1,
+    "false_positive": 1,
+    "downgraded": 0,
+    "needs_decision": 0
+  },
+  "findings": [
+    {
+      "id": "F-001",
+      "lens": "correctness",
+      "location": "services/mercury/src/services/checkout-sessions.ts:42",
+      "claim": "Edge case not handled for empty cart",
+      "evidence": "snippet",
+      "severity": "important",
+      "phase1_confidence": "medium",
+      "verdict": "confirmed",
+      "verdict_reason": "No guard before total calculation; tests absent."
+    },
+    {
+      "id": "F-002",
+      "lens": "security",
+      "location": "services/mercury/src/services/checkout-sessions.ts:10",
+      "claim": "SQL injection via session id",
+      "evidence": "snippet",
+      "severity": "critical",
+      "phase1_confidence": "low",
+      "verdict": "false_positive",
+      "verdict_reason": "ORM parameterizes query; no raw SQL."
+    }
+  ]
+}