@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/review/findings.mjs

@@ -0,0 +1,278 @@
+function parseLineRange(raw) {
+  const s = String(raw ?? '').trim();
+  // Common CodeRabbit format: "17 to 31"
+  const m = s.match(/^(\d+)\s+to\s+(\d+)$/i);
+  if (m) return { start: Number(m[1]), end: Number(m[2]) };
+  const n = s.match(/^(\d+)$/);
+  if (n) {
+    const v = Number(n[1]);
+    return { start: v, end: v };
+  }
+  return null;
+}
+
+export function parseCodeRabbitPlainOutput(text) {
+  const lines = String(text ?? '').split('\n');
+  const findings = [];
+
+  let current = null;
+  let mode = null; // 'comment' | 'prompt' | null
+
+  function flush() {
+    if (!current) return;
+    const comment = (current._commentLines ?? []).join('\n').trim();
+    const prompt = (current._promptLines ?? []).join('\n').trim();
+    const title =
+      current.title ??
+      comment
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)[0] ??
+      '';
+
+    findings.push({
+      reviewer: 'coderabbit',
+      file: current.file ?? '',
+      lines: current.lines ?? null,
+      type: current.type ?? '',
+      title,
+      comment,
+      prompt: prompt || null,
+    });
+    current = null;
+    mode = null;
+  }
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    // The raw log files written by the review runner prefix each line with "[label] ".
+    // Strip that prefix so we can parse both prefixed logs and unprefixed stdout.
+    const trimmed = line.trimEnd().replace(/^\[[^\]]+\]\s*/g, '');
+
+    if (trimmed.startsWith('============================================================================')) {
+      flush();
+      continue;
+    }
+    if (trimmed.startsWith('File: ')) {
+      flush();
+      current = { _commentLines: [], _promptLines: [] };
+      current.file = trimmed.slice('File: '.length).trim();
+      continue;
+    }
+    if (!current) continue;
+
+    if (trimmed.startsWith('Line: ')) {
+      const range = parseLineRange(trimmed.slice('Line: '.length).trim());
+      current.lines = range;
+      continue;
+    }
+    if (trimmed.startsWith('Type: ')) {
+      current.type = trimmed.slice('Type: '.length).trim();
+      continue;
+    }
+    if (trimmed === 'Comment:') {
+      mode = 'comment';
+      continue;
+    }
+    if (trimmed === 'Prompt for AI Agent:') {
+      mode = 'prompt';
+      continue;
+    }
+
+    if (mode === 'comment') {
+      // Title is first non-empty comment line.
+      if (!current.title && trimmed.trim()) current.title = trimmed.trim();
+      current._commentLines.push(trimmed);
+    } else if (mode === 'prompt') {
+      current._promptLines.push(trimmed);
+    }
+  }
+
+  flush();
+  // Drop empty placeholders
+  return findings.filter((f) => f.file && f.title);
+}
+
+export function parseCodexReviewText(reviewText) {
+  const s = String(reviewText ?? '');
+  const marker = '===FINDINGS_JSON===';
+  const idx = s.indexOf(marker);
+  if (idx >= 0) {
+    let jsonText = s.slice(idx + marker.length).trim();
+    if (!jsonText) return [];
+
+    // The raw log files written by the review runner prefix each line with "[label] ".
+    // Strip that prefix so we can parse both prefixed logs and unprefixed stdout.
+    jsonText = jsonText
+      .split('\n')
+      .map((line) => String(line ?? '').replace(/^\[[^\]]+\]\s*/g, ''))
+      .join('\n')
+      .trim();
+
+    // Some reviewers wrap the JSON in a fenced code block:
+    // ===FINDINGS_JSON===
+    // ```json
+    // [...]
+    // ```
+    //
+    // Strip the outer fence so JSON.parse can succeed.
+    const fence = jsonText.match(/^```[a-z0-9_-]*\s*\n([\s\S]*?)\n```/i);
+    if (fence?.[1]) jsonText = fence[1].trim();
+
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonText);
+    } catch {
+      parsed = null;
+    }
+
+    // Some tools append non-JSON metadata after the array (e.g. "Request ID: ...").
+    // As a last resort, try to parse the first top-level JSON array substring.
+    if (!Array.isArray(parsed)) {
+      const firstBracket = jsonText.indexOf('[');
+      const lastBracket = jsonText.lastIndexOf(']');
+      if (firstBracket >= 0 && lastBracket > firstBracket) {
+        try {
+          parsed = JSON.parse(jsonText.slice(firstBracket, lastBracket + 1));
+        } catch {
+          // ignore
+        }
+      }
+    }
+    if (Array.isArray(parsed)) {
+      return parsed
+        .map((x) => ({
+          reviewer: 'codex',
+          severity: x?.severity ?? null,
+          file: x?.file ?? null,
+          lines: x?.lines ?? null,
+          title: x?.title ?? null,
+          recommendation: x?.recommendation ?? null,
+          needsDiscussion: Boolean(x?.needsDiscussion),
+        }))
+        .filter((x) => x.file && x.title);
+    }
+  }
+
+  // Fallback: Codex sometimes returns a human-readable list like:
+  // - [P2] Thing — /abs/path/.project/review-worktrees/codex-.../cli/src/foo.ts:10-12
+  //
+  // Parse these into structured findings so they appear in triage even when the
+  // JSON trailer is missing.
+  const priorityToSeverity = { 1: 'blocker', 2: 'major', 3: 'minor', 4: 'nit' };
+  const lines = s.split('\n');
+  const findings = [];
+  const seen = new Set();
+
+  function stripPrefix(line) {
+    return String(line ?? '').replace(/^\[[^\]]+\]\s*/g, '').trim();
+  }
+
+  function normalizePath(rawPath) {
+    const p = String(rawPath ?? '').trim();
+    const marker2 = '/.project/review-worktrees/';
+    const i = p.indexOf(marker2);
+    if (i < 0) return p;
+    const rest = p.slice(i + marker2.length);
+    const slash = rest.indexOf('/');
+    if (slash < 0) return p;
+    return rest.slice(slash + 1);
+  }
+
+  for (const rawLine of lines) {
+    const line = stripPrefix(rawLine);
+    const m = line.match(/^- \[P([1-4])\]\s+(.+?)\s+—\s+(.+)$/);
+    if (!m) continue;
+
+    const priority = Number(m[1]);
+    const title = String(m[2]).trim();
+    const pathPart = String(m[3]).trim();
+
+    let file = pathPart;
+    let range = null;
+
+    const lastColon = pathPart.lastIndexOf(':');
+    if (lastColon > 0) {
+      const suffix = pathPart.slice(lastColon + 1).trim();
+      const rm = suffix.match(/^(\d+)(?:-(\d+))?$/);
+      if (rm) {
+        const start = Number(rm[1]);
+        const end = Number(rm[2] ?? rm[1]);
+        range = { start, end };
+        file = pathPart.slice(0, lastColon);
+      }
+    }
+
+    const normalizedFile = normalizePath(file);
+    const severity = priorityToSeverity[priority] ?? null;
+    const key = `${normalizedFile}:${range?.start ?? ''}-${range?.end ?? ''}:${title}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    findings.push({
+      reviewer: 'codex',
+      severity,
+      file: normalizedFile,
+      lines: range,
+      title,
+      recommendation: null,
+      needsDiscussion: false,
+    });
+  }
+
+  return findings.filter((x) => x.file && x.title);
+}
+
+export function formatTriageMarkdown({ runLabel, baseRef, findings }) {
+  const items = Array.isArray(findings) ? findings : [];
+  const header = [
+    `# Review triage: ${runLabel}`,
+    '',
+    `- Base ref: ${baseRef ?? ''}`,
+    `- Findings: ${items.length}`,
+    '',
+    '## Trust checklist (READ THIS FIRST)',
+    '',
+    'Before you act on reviewer output:',
+    '1) Load this file into your context (human/LLM) so you follow the workflow end-to-end.',
+    '2) Treat every suggestion as a suggestion: verify against best practices + project invariants.',
+    '3) If you are unsure, do not apply; mark **Needs discussion** and capture rationale.',
+    '4) Do not skip nits by default: apply them when they improve long-term maintainability without risk.',
+    '5) Use web search sparingly when needed to validate best practices, but prefer primary sources/docs.',
+    '',
+    '## Mandatory workflow',
+    '',
+    'For each finding below:',
+    '1) Open the referenced file/lines in the *validation worktree* (committed-only).',
+    '2) Decide if it is a real bug/risk/correctness gap, already fixed, expected behavior, or style preference.',
+    '3) Record a final decision + rationale here (`apply` / `adjust` / `defer`).',
+    '4) If `apply/adjust`: implement in the main worktree as a clean commit (no unrelated changes), then sync that commit to validation.',
+    '',
+    'Notes:',
+    '- Treat reviewer output as suggestions; verify against best practices and codebase invariants before applying.',
+    '- Avoid brittle tests that assert on wording/phrasing/config; test observable behavior.',
+    '',
+  ].join('\n');
+
+  const body = items
+    .map((f) => {
+      const lines = f.lines?.start ? `${f.lines.start}-${f.lines.end ?? f.lines.start}` : '';
+      const meta = [
+        `- [ ] \`${f.id ?? ''}\` reviewer=\`${f.reviewer ?? ''}\`${f.severity ? ` severity=\`${f.severity}\`` : ''}${
+          f.type ? ` type=\`${f.type}\`` : ''
+        } \`${f.file ?? ''}\`${lines ? ` (lines ${lines})` : ''}: ${f.title ?? ''}`,
+        f.sourceLog ? `  - Source log: \`${f.sourceLog}\`` : null,
+        '  - Final decision: **TBD** (apply|adjust|defer)',
+        '  - Verified in validation worktree: **TBD**',
+        '  - Rationale: **TBD**',
+        '  - Action taken: **TBD**',
+        '  - Commit: **TBD**',
+        '  - Needs discussion: **TBD**',
+      ];
+      if (f.comment) meta.push(`  - Reviewer detail: ${String(f.comment).split('\n')[0].trim()}`);
+      if (f.recommendation) meta.push(`  - Reviewer suggested fix: ${String(f.recommendation).split('\n')[0].trim()}`);
+      return meta.filter(Boolean).join('\n');
+    })
+    .join('\n\n');
+
+  return `${header}${body ? `${body}\n` : ''}`;
+}

package/scripts/utils/review/findings.test.mjs

@@ -0,0 +1,203 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { formatTriageMarkdown, parseCodeRabbitPlainOutput, parseCodexReviewText } from './findings.mjs';
+
+function joinLines(lines) {
+  return lines.join('\n');
+}
+
+function makeCodeRabbitBlock({ file, line, type, commentLines = [], promptLines = [] }) {
+  const lines = [
+    '============================================================================',
+    `File: ${file}`,
+    `Line: ${line}`,
+    `Type: ${type}`,
+    '',
+    'Comment:',
+    ...commentLines,
+  ];
+  if (promptLines.length) {
+    lines.push('', 'Prompt for AI Agent:', ...promptLines);
+  }
+  return lines;
+}
+
+function makeCodexFindingsJsonBlock(findings, { fenced = false } = {}) {
+  const json = JSON.stringify(findings, null, 2);
+  if (!fenced) return ['===FINDINGS_JSON===', json];
+  return ['===FINDINGS_JSON===', '```json', json, '```'];
+}
+
+function withLabelPrefix(lines, label) {
+  return lines.map((line) => `${label}${line}`);
+}
+
+test('parseCodeRabbitPlainOutput parses CodeRabbit plain blocks', () => {
+  const out = joinLines([
+    ...makeCodeRabbitBlock({
+      file: 'apps/cli/src/utils/spawnHappyCLI.invocation.test.ts',
+      line: '17 to 31',
+      type: 'potential_issue',
+      commentLines: ['Dynamic imports may be cached, causing test isolation issues.', '', 'Some more details.'],
+      promptLines: ['Do the thing.'],
+    }),
+    ...makeCodeRabbitBlock({
+      file: 'apps/ui/sources/app/(app)/_layout.tsx',
+      line: '29 to 35',
+      type: 'potential_issue',
+      commentLines: ['Hooks order violation: useUnistyles() called after conditional return.', '', 'More details.'],
+    }),
+  ]);
+
+  const findings = parseCodeRabbitPlainOutput(out);
+  assert.equal(findings.length, 2);
+  assert.equal(findings[0].file, 'apps/cli/src/utils/spawnHappyCLI.invocation.test.ts');
+  assert.deepEqual(findings[0].lines, { start: 17, end: 31 });
+  assert.equal(findings[0].type, 'potential_issue');
+  assert.equal(findings[0].title, 'Dynamic imports may be cached, causing test isolation issues.');
+  assert.match(findings[0].comment, /Some more details/);
+  assert.match(findings[0].prompt, /Do the thing/);
+});
+
+test('parseCodeRabbitPlainOutput supports log-prefixed lines and single-line range', () => {
+  const label = '[monorepo:coderabbit:1/3] ';
+  const out = joinLines(
+    withLabelPrefix(
+      makeCodeRabbitBlock({
+        file: 'apps/stack/scripts/review.mjs',
+        line: '42',
+        type: 'nit',
+        commentLines: ['Prefer a clearer constant name.'],
+      }),
+      label
+    )
+  );
+
+  const findings = parseCodeRabbitPlainOutput(out);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'apps/stack/scripts/review.mjs');
+  assert.deepEqual(findings[0].lines, { start: 42, end: 42 });
+  assert.equal(findings[0].type, 'nit');
+  assert.equal(findings[0].title, 'Prefer a clearer constant name.');
+});
+
+test('parseCodexReviewText extracts findings JSON trailer', () => {
+  const review = joinLines([
+    'Overall verdict: looks good.',
+    '',
+    ...makeCodexFindingsJsonBlock([
+      {
+        severity: 'major',
+        file: 'apps/server/sources/main.light.ts',
+        title: 'Do not exit after startup',
+        recommendation: 'Remove process.exit(0) on success.',
+      },
+    ]),
+  ]);
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'apps/server/sources/main.light.ts');
+  assert.equal(findings[0].severity, 'major');
+});
+
+test('parseCodexReviewText extracts findings JSON trailer even when fenced', () => {
+  const review = joinLines(['All good.', '', ...makeCodexFindingsJsonBlock([
+    {
+      severity: 'minor',
+      file: 'cli/src/foo.ts',
+      title: 'Prefer explicit return type',
+      recommendation: 'Add an explicit return type for clarity.',
+    },
+  ], { fenced: true })]);
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'cli/src/foo.ts');
+  assert.equal(findings[0].severity, 'minor');
+});
+
+test('parseCodexReviewText extracts findings JSON trailer when lines are log-prefixed', () => {
+  const label = '[monorepo:augment:4/39] ';
+  const prefixed = withLabelPrefix(
+    makeCodexFindingsJsonBlock(
+      [
+        {
+          severity: 'major',
+          file: 'cli/src/x.ts',
+          title: 'Fix thing',
+          recommendation: 'Do it.',
+          needsDiscussion: false,
+        },
+      ],
+      { fenced: true }
+    ).concat(['', 'Request ID: abc']),
+    label
+  );
+  const review = joinLines([`${label}some preamble`, ...prefixed]);
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'cli/src/x.ts');
+  assert.equal(findings[0].severity, 'major');
+});
+
+test('parseCodexReviewText falls back to parsing [P#] bullet lines', () => {
+  const review = joinLines([
+    '[monorepo:codex:2/21] Review comment:',
+    '[monorepo:codex:2/21] - [P1] Fix thing one — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/apps/cli/src/foo.ts:10-12',
+    '[monorepo:codex:2/21] - [P3] Fix thing two — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/apps/ui/sources/bar.tsx:7',
+  ]);
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 2);
+  assert.equal(findings[0].file, 'apps/cli/src/foo.ts');
+  assert.deepEqual(findings[0].lines, { start: 10, end: 12 });
+  assert.equal(findings[0].severity, 'blocker');
+  assert.equal(findings[0].title, 'Fix thing one');
+  assert.equal(findings[1].file, 'apps/ui/sources/bar.tsx');
+  assert.deepEqual(findings[1].lines, { start: 7, end: 7 });
+  assert.equal(findings[1].severity, 'minor');
+  assert.equal(findings[1].title, 'Fix thing two');
+});
+
+test('parseCodexReviewText falls back when marker exists but JSON is missing/invalid', () => {
+  const review = joinLines([
+    'instructions...',
+    '===FINDINGS_JSON===',
+    'this is not json',
+    '[monorepo:codex:2/21] - [P2] Fix thing — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/apps/server/src/x.ts:1-2',
+  ]);
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'apps/server/src/x.ts');
+  assert.deepEqual(findings[0].lines, { start: 1, end: 2 });
+  assert.equal(findings[0].severity, 'major');
+});
+
+test('parseCodexReviewText returns empty list when no findings marker/bullets exist', () => {
+  const findings = parseCodexReviewText('No actionable findings.');
+  assert.deepEqual(findings, []);
+});
+
+test('formatTriageMarkdown includes required workflow fields', () => {
+  const md = formatTriageMarkdown({
+    runLabel: 'review-123',
+    baseRef: 'upstream/main',
+    findings: [
+      {
+        reviewer: 'coderabbit',
+        id: 'CR-001',
+        file: 'cli/src/x.ts',
+        title: 'Thing',
+        type: 'potential_issue',
+      },
+    ],
+  });
+  assert.match(md, /Trust checklist/i);
+  assert.match(md, /Final decision: \*\*TBD\*\*/);
+  assert.match(md, /Verified in validation worktree:/);
+  assert.match(md, /Commit:/);
+});

package/scripts/utils/review/head_slice.mjs

@@ -0,0 +1,132 @@
+import { runCapture } from '../proc/proc.mjs';
+import { parseNameStatusZ } from '../git/parse_name_status_z.mjs';
+
+function normalizePath(p) {
+  return String(p ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+}
+
+export async function getChangedOps({ cwd, baseRef, headRef = 'HEAD', env = process.env } = {}) {
+  const out = await runCapture('git', ['diff', '--name-status', '--find-renames', '-z', `${baseRef}...${headRef}`], { cwd, env });
+  const entries = parseNameStatusZ(out);
+  const checkout = new Set();
+  const remove = new Set();
+  for (const e of entries) {
+    if (e.code === 'A' || e.code === 'M' || e.code === 'T') {
+      checkout.add(normalizePath(e.path));
+      continue;
+    }
+    if (e.code === 'D') {
+      remove.add(normalizePath(e.path));
+      continue;
+    }
+    if (e.code === 'R' || e.code === 'C') {
+      if (e.from) remove.add(normalizePath(e.from));
+      if (e.to) checkout.add(normalizePath(e.to));
+      continue;
+    }
+  }
+  const all = new Set([...checkout, ...remove]);
+  return { checkout, remove, all };
+}
+
+function subset(set, allowed) {
+  const out = new Set();
+  for (const v of set) {
+    if (allowed.has(v)) out.add(v);
+  }
+  return out;
+}
+
+function difference(set, blocked) {
+  const out = new Set();
+  for (const v of set) {
+    if (!blocked.has(v)) out.add(v);
+  }
+  return out;
+}
+
+async function batched(args, batchSize, fn) {
+  const list = Array.from(args);
+  for (let i = 0; i < list.length; i += batchSize) {
+    // eslint-disable-next-line no-await-in-loop
+    await fn(list.slice(i, i + batchSize));
+  }
+}
+
+async function gitCommit({ cwd, env, message }) {
+  await runCapture(
+    'git',
+    [
+      '-c',
+      'user.name=Happier Review',
+      '-c',
+      'user.email=review@happier.local',
+      '-c',
+      'commit.gpgsign=false',
+      'commit',
+      '-q',
+      '--no-verify',
+      '-m',
+      message,
+    ],
+    { cwd, env }
+  );
+  const sha = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd, env })).trim();
+  return sha;
+}
+
+async function applyOpsFromHead({ cwd, env, headCommit, checkoutPaths, removePaths }) {
+  if (removePaths.size) {
+    await batched(Array.from(removePaths), 200, async (batch) => {
+      await runCapture('git', ['rm', '-q', '--ignore-unmatch', '--', ...batch], { cwd, env });
+    });
+  }
+  if (checkoutPaths.size) {
+    // Prefer batching over pathspec-from-file to maximize compatibility.
+    await batched(Array.from(checkoutPaths), 100, async (batch) => {
+      await runCapture('git', ['checkout', headCommit, '--', ...batch], { cwd, env });
+    });
+  }
+  // Stage all changes introduced by the operations.
+  await runCapture('git', ['add', '-A'], { cwd, env });
+}
+
+/**
+ * Create two local commits inside an ephemeral worktree:
+ * - baseSliceCommit: baseRef plus all NON-slice changes from headCommit
+ * - headSliceCommit: baseSliceCommit plus slice changes from headCommit (resulting tree equals headCommit)
+ *
+ * These commits are intended solely for review tooling (CodeRabbit/Codex) so the reviewer sees:
+ * - full, final code at HEAD
+ * - a focused diff for the slice (baseSliceCommit..headSliceCommit)
+ */
+export async function createHeadSliceCommits({
+  cwd,
+  env = process.env,
+  baseRef,
+  headCommit,
+  ops,
+  slicePaths,
+  label = 'slice',
+} = {}) {
+  const sliceSet = new Set((Array.isArray(slicePaths) ? slicePaths : []).map(normalizePath).filter(Boolean));
+  const sliceCheckout = subset(ops.checkout, sliceSet);
+  const sliceRemove = subset(ops.remove, sliceSet);
+  const nonSliceCheckout = difference(ops.checkout, sliceSet);
+  const nonSliceRemove = difference(ops.remove, sliceSet);
+
+  // Start from baseRef.
+  await runCapture('git', ['checkout', '-q', '--detach', baseRef], { cwd, env });
+
+  // Commit non-slice changes.
+  await applyOpsFromHead({ cwd, env, headCommit, checkoutPaths: nonSliceCheckout, removePaths: nonSliceRemove });
+  const baseSliceCommit = await gitCommit({ cwd, env, message: `chore(review): base for ${label}` });
+
+  // Commit slice changes.
+  await applyOpsFromHead({ cwd, env, headCommit, checkoutPaths: sliceCheckout, removePaths: sliceRemove });
+  const headSliceCommit = await gitCommit({ cwd, env, message: `chore(review): ${label}` });
+
+  // Ensure working tree is at the head slice commit for downstream tools.
+  await runCapture('git', ['checkout', '-q', headSliceCommit], { cwd, env });
+  return { baseSliceCommit, headSliceCommit };
+}