happy-stacks 0.4.0 → 0.5.0

package/scripts/utils/review/chunks.mjs

@@ -0,0 +1,55 @@
+export async function planCommitChunks({ baseCommit, commits, maxFiles, countFilesBetween }) {
+  if (!Array.isArray(commits)) throw new Error('[review] planCommitChunks: commits must be an array');
+  const max = Number(maxFiles);
+  if (!Number.isFinite(max) || max <= 0) throw new Error('[review] planCommitChunks: maxFiles must be a positive number');
+  if (typeof countFilesBetween !== 'function') throw new Error('[review] planCommitChunks: countFilesBetween must be a function');
+
+  const list = commits.map((c) => String(c ?? '').trim()).filter(Boolean);
+  if (!list.length) return [];
+
+  const chunks = [];
+  let base = String(baseCommit ?? '').trim();
+  if (!base) throw new Error('[review] planCommitChunks: baseCommit is required');
+  let startIndex = 0;
+
+  while (startIndex < list.length) {
+    let lo = startIndex;
+    let hi = list.length - 1;
+    let bestIndex = -1;
+    let bestCount = -1;
+
+    while (lo <= hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      const head = list[mid];
+      // eslint-disable-next-line no-await-in-loop
+      const n = await countFilesBetween({ base, head });
+      if (!Number.isFinite(n) || n < 0) throw new Error('[review] planCommitChunks: countFilesBetween returned invalid count');
+
+      if (n <= max) {
+        bestIndex = mid;
+        bestCount = n;
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+
+    // If even the smallest chunk exceeds the limit, emit a single over-limit chunk so the caller can decide what to do.
+    if (bestIndex === -1) {
+      const head = list[startIndex];
+      // eslint-disable-next-line no-await-in-loop
+      const n = await countFilesBetween({ base, head });
+      chunks.push({ base, head, fileCount: n, overLimit: true });
+      base = head;
+      startIndex += 1;
+      continue;
+    }
+
+    const head = list[bestIndex];
+    chunks.push({ base, head, fileCount: bestCount, overLimit: false });
+    base = head;
+    startIndex = bestIndex + 1;
+  }
+
+  return chunks;
+}

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

@@ -0,0 +1,51 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { planCommitChunks } from './chunks.mjs';
+
+test('planCommitChunks greedily selects the largest end commit within maxFiles', async () => {
+  const commits = ['c1', 'c2', 'c3', 'c4'];
+
+  const counts = new Map([
+    ['BASE->c1', 1],
+    ['BASE->c2', 3],
+    ['BASE->c3', 4],
+    ['BASE->c4', 7],
+    ['c2->c3', 2],
+    ['c2->c4', 5],
+    ['c3->c4', 2],
+  ]);
+
+  const chunks = await planCommitChunks({
+    baseCommit: 'BASE',
+    commits,
+    maxFiles: 3,
+    countFilesBetween: async ({ base, head }) => counts.get(`${base}->${head}`),
+  });
+
+  assert.deepEqual(chunks, [
+    { base: 'BASE', head: 'c2', fileCount: 3, overLimit: false },
+    { base: 'c2', head: 'c3', fileCount: 2, overLimit: false },
+    { base: 'c3', head: 'c4', fileCount: 2, overLimit: false },
+  ]);
+});
+
+test('planCommitChunks marks overLimit when a single step exceeds maxFiles', async () => {
+  const commits = ['c1', 'c2'];
+
+  const counts = new Map([
+    ['BASE->c1', 10],
+    ['c1->c2', 2],
+  ]);
+
+  const chunks = await planCommitChunks({
+    baseCommit: 'BASE',
+    commits,
+    maxFiles: 3,
+    countFilesBetween: async ({ base, head }) => counts.get(`${base}->${head}`),
+  });
+
+  assert.deepEqual(chunks, [
+    { base: 'BASE', head: 'c1', fileCount: 10, overLimit: true },
+    { base: 'c1', head: 'c2', fileCount: 2, overLimit: false },
+  ]);
+});

package/scripts/utils/review/findings.mjs

@@ -0,0 +1,165 @@
+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];
+    const trimmed = line.trimEnd();
+
+    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) return [];
+  const jsonText = s.slice(idx + marker.length).trim();
+  if (!jsonText) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .map((x) => ({
+      reviewer: 'codex',
+      severity: x?.severity ?? null,
+      file: x?.file ?? null,
+      title: x?.title ?? null,
+      recommendation: x?.recommendation ?? null,
+      needsDiscussion: Boolean(x?.needsDiscussion),
+    }))
+    .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}`,
+    '',
+    '## 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,85 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { formatTriageMarkdown, parseCodeRabbitPlainOutput, parseCodexReviewText } from './findings.mjs';
+
+test('parseCodeRabbitPlainOutput parses CodeRabbit plain blocks', () => {
+  const out = [
+    '============================================================================',
+    'File: cli/src/utils/spawnHappyCLI.invocation.test.ts',
+    'Line: 17 to 31',
+    'Type: potential_issue',
+    '',
+    'Comment:',
+    'Dynamic imports may be cached, causing test isolation issues.',
+    '',
+    'Some more details.',
+    '',
+    'Prompt for AI Agent:',
+    'Do the thing.',
+    '',
+    '============================================================================',
+    'File: expo-app/sources/app/(app)/_layout.tsx',
+    'Line: 29 to 35',
+    'Type: potential_issue',
+    '',
+    'Comment:',
+    "Hooks order violation: useUnistyles() called after conditional return.",
+    '',
+    'More details.',
+  ].join('\n');
+
+  const findings = parseCodeRabbitPlainOutput(out);
+  assert.equal(findings.length, 2);
+  assert.equal(findings[0].file, '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('parseCodexReviewText extracts findings JSON trailer', () => {
+  const review = [
+    'Overall verdict: looks good.',
+    '',
+    '===FINDINGS_JSON===',
+    JSON.stringify(
+      [
+        {
+          severity: 'major',
+          file: 'server/sources/main.light.ts',
+          title: 'Do not exit after startup',
+          recommendation: 'Remove process.exit(0) on success.',
+        },
+      ],
+      null,
+      2
+    ),
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'server/sources/main.light.ts');
+  assert.equal(findings[0].severity, 'major');
+});
+
+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, /Final decision: \*\*TBD\*\*/);
+  assert.match(md, /Verified in validation worktree:/);
+  assert.match(md, /Commit:/);
+});
+

package/scripts/utils/review/head_slice.mjs

@@ -0,0 +1,153 @@
+import { runCapture } from '../proc/proc.mjs';
+
+function normalizePath(p) {
+  return String(p ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+}
+
+function parseNameStatusZ(buf) {
+  const raw = String(buf ?? '');
+  if (!raw) return [];
+  const parts = raw.split('\0').filter((x) => x.length);
+  const entries = [];
+  let i = 0;
+  while (i < parts.length) {
+    const status = parts[i++];
+    const code = status[0] ?? '';
+    if (!code) break;
+    if (code === 'R' || code === 'C') {
+      const from = parts[i++] ?? '';
+      const to = parts[i++] ?? '';
+      entries.push({ code, status, from, to });
+      continue;
+    }
+    const path = parts[i++] ?? '';
+    entries.push({ code, status, path });
+  }
+  return entries;
+}
+
+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=Happy Review',
+      '-c',
+      'user.email=review@happy.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 };
+}

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

@@ -0,0 +1,91 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { run, runCapture } from '../proc/proc.mjs';
+import { createHeadSliceCommits, getChangedOps } from './head_slice.mjs';
+
+function gitEnv() {
+  const clean = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith('HAPPY_STACKS_') || k.startsWith('HAPPY_LOCAL_')) continue;
+    clean[k] = v;
+  }
+  return {
+    ...clean,
+    GIT_AUTHOR_NAME: 'Test',
+    GIT_AUTHOR_EMAIL: 'test@example.com',
+    GIT_COMMITTER_NAME: 'Test',
+    GIT_COMMITTER_EMAIL: 'test@example.com',
+  };
+}
+
+test('createHeadSliceCommits produces a focused diff while keeping full HEAD code', async (t) => {
+  const repo = await mkdtemp(join(tmpdir(), 'happy-review-head-slice-'));
+  const env = gitEnv();
+
+  const wt = join(repo, 'wt');
+  try {
+    await run('git', ['init', '-q'], { cwd: repo, env });
+    await run('git', ['checkout', '-q', '-b', 'main'], { cwd: repo, env });
+    await mkdir(join(repo, 'expo-app'), { recursive: true });
+    await mkdir(join(repo, 'cli'), { recursive: true });
+    await mkdir(join(repo, 'server'), { recursive: true });
+    await writeFile(join(repo, 'expo-app', 'a.txt'), 'base-a\n', 'utf-8');
+    await writeFile(join(repo, 'cli', 'c.txt'), 'base-c\n', 'utf-8');
+    await writeFile(join(repo, 'server', 'b.txt'), 'base-b\n', 'utf-8');
+    await run('git', ['add', '.'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'chore: base'], { cwd: repo, env });
+
+    // HEAD commit with mixed changes across areas.
+    await writeFile(join(repo, 'expo-app', 'a.txt'), 'head-a\n', 'utf-8');
+    await writeFile(join(repo, 'expo-app', 'new.txt'), 'new\n', 'utf-8');
+    await writeFile(join(repo, 'cli', 'c.txt'), 'head-c\n', 'utf-8');
+    await rm(join(repo, 'server', 'b.txt'));
+    await run('git', ['add', '-A'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'feat: head'], { cwd: repo, env });
+
+    const headCommit = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repo, env })).trim();
+    const baseCommit = (await runCapture('git', ['rev-parse', 'HEAD^'], { cwd: repo, env })).trim();
+
+    // Create an ephemeral worktree to run the slice commit builder in isolation.
+    await run('git', ['worktree', 'add', '--detach', wt, baseCommit], { cwd: repo, env });
+
+    const ops = await getChangedOps({ cwd: repo, baseRef: baseCommit, headRef: headCommit, env });
+    const { baseSliceCommit, headSliceCommit } = await createHeadSliceCommits({
+      cwd: wt,
+      env,
+      baseRef: baseCommit,
+      headCommit,
+      ops,
+      slicePaths: ['expo-app/a.txt', 'expo-app/new.txt'],
+      label: 'expo-app',
+    });
+
+    // Working tree should match full HEAD.
+    const a = await readFile(join(wt, 'expo-app', 'a.txt'), 'utf-8');
+    const c = await readFile(join(wt, 'cli', 'c.txt'), 'utf-8');
+    assert.equal(a, 'head-a\n');
+    assert.equal(c, 'head-c\n');
+    await assert.rejects(async () => await readFile(join(wt, 'server', 'b.txt'), 'utf-8'));
+
+    // Diff between slice commits should include only expo-app changes.
+    const diffNames = (
+      await runCapture('git', ['diff', '--name-only', `${baseSliceCommit}...${headSliceCommit}`], { cwd: wt, env })
+    )
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .sort();
+    assert.deepEqual(diffNames, ['expo-app/a.txt', 'expo-app/new.txt']);
+  } finally {
+    try {
+      await run('git', ['worktree', 'remove', '--force', wt], { cwd: repo, env });
+      await run('git', ['worktree', 'prune'], { cwd: repo, env });
+    } catch {
+      // ignore cleanup errors (best-effort)
+    }
+    await rm(repo, { recursive: true, force: true });
+  }
+});

package/scripts/utils/review/instructions/deep.md

@@ -0,0 +1,20 @@
+You are running a deep, long-form code review.
+
+Goals:
+- Find correctness bugs, edge cases, and regressions vs upstream/main.
+- Find performance problems (big-O, unnecessary allocations, redundant work) and reliability issues.
+- Find security and safety issues (filesystem access, env handling, process spawning, injection risks).
+- Find maintainability issues (duplication, unclear ownership boundaries, inconsistent patterns).
+- Ensure i18n coverage is complete: do not introduce hardcoded user-visible strings.
+
+Constraints:
+- Prefer fixes that are unified/coherent and avoid duplicating logic.
+- Avoid “brittle” tests that assert on wording/phrasing or hardcoded text; test real behavior and observable outcomes.
+- Do not suggest broad refactors unless clearly justified and low-risk.
+- Treat every recommendation as a suggestion: validate against best practices and the existing codebase patterns; do not propose changes that conflict with project invariants.
+- If a recommendation is uncertain, depends on product/UX decisions, or might have hidden tradeoffs, explicitly mark it as "needs discussion".
+
+Output:
+- Provide specific, actionable recommendations with file paths and a brief rationale.
+- Call out any items that are uncertain or require product/UX decisions separately.
+- Be exhaustive: include all findings you notice, not only the highest-signal ones.