happy-stacks 0.6.12 → 0.6.13

package/docs/commit-audits/happy/_tools/generate-plans.mjs

@@ -0,0 +1,453 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+const AUDIT_DIR = path.join(ROOT, 'docs', 'commit-audits', 'happy');
+
+const ANALYSIS_PATH = path.join(AUDIT_DIR, 'leeroy-wip.commit-analysis.md');
+const MANUAL_PATH = path.join(AUDIT_DIR, 'leeroy-wip.commit-manual-review.md');
+
+const OUT_INDEX_JSON = path.join(AUDIT_DIR, 'leeroy-wip.commit-index.json');
+const OUT_INDEX_TSV = path.join(AUDIT_DIR, 'leeroy-wip.commit-index.tsv');
+const OUT_BUCKETS_MD = path.join(AUDIT_DIR, 'leeroy-wip.topic-buckets.md');
+const OUT_SPLIT_MD = path.join(AUDIT_DIR, 'leeroy-wip.split-plan.draft.md');
+const OUT_PR_MD = path.join(AUDIT_DIR, 'leeroy-wip.pr-stack-plan.draft.md');
+
+function splitCommitSections(markdown) {
+  // Sections start at: "## 001 ..."
+  const re = /^##\s+(\d{3})\b/mg;
+  const indices = [];
+  let m;
+  while ((m = re.exec(markdown))) {
+    indices.push({ n: Number(m[1]), idx: m.index });
+  }
+  indices.sort((a, b) => a.n - b.n);
+
+  const sections = new Map();
+  for (let i = 0; i < indices.length; i++) {
+    const start = indices[i].idx;
+    const end = i + 1 < indices.length ? indices[i + 1].idx : markdown.length;
+    sections.set(indices[i].n, markdown.slice(start, end));
+  }
+  return sections;
+}
+
+function parseCodeBlock(section, heading) {
+  // Find a heading then the next ```text ... ```
+  const idx = section.indexOf(heading);
+  if (idx < 0) return null;
+  const after = section.slice(idx + heading.length);
+  const fenceStart = after.indexOf('```text');
+  if (fenceStart < 0) return null;
+  const rest = after.slice(fenceStart + '```text'.length);
+  const fenceEnd = rest.indexOf('```');
+  if (fenceEnd < 0) return null;
+  return rest.slice(0, fenceEnd).trimEnd().replace(/^\n/, '');
+}
+
+function parseAnalysisSection(section) {
+  const header = section.match(/^##\s+(\d{3})\s+(\d{4}-\d{2}-\d{2})\s+([0-9a-f]{12,40})/m);
+  const n = header ? Number(header[1]) : null;
+  const date = header?.[2] ?? null;
+  const shaShort = header?.[3]?.slice(0, 12) ?? null;
+
+  const sha = section.match(/^- SHA:\s+([0-9a-f]{40})/m)?.[1] ?? null;
+  const subject = section.match(/^- Subject:\s+(.*)$/m)?.[1]?.trim() ?? null;
+  const topicBucket = section.match(/^- Topic bucket:\s+`([^`]+)`/m)?.[1] ?? null;
+  const touchedAreas = section.match(/^- Touched areas:\s+(.*)$/m)?.[1]?.trim() ?? null;
+  const filesChanged = Number(section.match(/^- Files changed:\s+(\d+)/m)?.[1] ?? '0') || null;
+  const lines = section.match(/^- Lines:\s+\+(\d+)\s+\/\s+-(\d+)/m);
+  const linesAdded = lines ? Number(lines[1]) : null;
+  const linesDeleted = lines ? Number(lines[2]) : null;
+
+  const filesBlock = parseCodeBlock(section, '### Files (name-status)');
+  const files = filesBlock
+    ? filesBlock
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+          const [status, ...rest] = l.split(/\s+/);
+          return { status, path: rest.join(' ') };
+        })
+    : [];
+
+  return {
+    n,
+    date,
+    shaShort,
+    sha,
+    subject,
+    topicBucket,
+    touchedAreas,
+    filesChanged,
+    linesAdded,
+    linesDeleted,
+    files,
+  };
+}
+
+function parseManualSection(section) {
+  const header = section.match(/^##\s+(\d{3})\s+(\d{4}-\d{2}-\d{2})\s+([0-9a-f]{12,40})(?:\s+`([^`]+)`)?/m);
+  const n = header ? Number(header[1]) : null;
+  const date = header?.[2] ?? null;
+  const shaShort = header?.[3]?.slice(0, 12) ?? null;
+  const scopeTag = header?.[4] ?? null;
+
+  const subject = section.match(/^- Subject:\s+(.*)$/m)?.[1]?.trim() ?? null;
+  const verdict = section.match(/^- Keep\/squash\/split\/drop\/reorder:\s+(.*)$/m)?.[1]?.trim() ?? null;
+
+  const pass2 = section.match(/^Pass2FullDiff:\s+CAPTURED.*$/m)?.[0] ?? null;
+  const notesReviewed = pass2?.match(/\bnotesReviewed=(yes|no)\b/)?.[1] ?? null;
+  const reviewedAt = pass2?.match(/\breviewedAt=([0-9T:+-]+)\b/)?.[1] ?? null;
+  const notesUpdated = pass2?.match(/\bnotesUpdated=(yes|no)\b/)?.[1] ?? null;
+
+  const dependsLines = [];
+  for (const line of section.split('\n')) {
+    const m = line.match(/^- Depends on:\s*(.*)$/);
+    if (m) dependsLines.push(m[1].trim());
+  }
+
+  const rewriteBlockIdx = section.indexOf('### Rewrite Commit Message');
+  const rewriteHints =
+    rewriteBlockIdx >= 0
+      ? section
+          .slice(rewriteBlockIdx)
+          .split('\n')
+          .slice(0, 25)
+          .map((l) => l.trim())
+          .filter((l) => l.startsWith('- '))
+          .map((l) => l.replace(/^- /, ''))
+      : [];
+
+  return {
+    n,
+    date,
+    shaShort,
+    scopeTag,
+    subject,
+    verdict,
+    notesReviewed,
+    reviewedAt,
+    notesUpdated,
+    depends: dependsLines,
+    rewriteHints,
+  };
+}
+
+function tsvEscape(value) {
+  if (value == null) return '';
+  return String(value).replace(/\t/g, ' ').replace(/\r?\n/g, ' ');
+}
+
+function buildBucketSummary(commits) {
+  const counts = new Map();
+  for (const c of commits) {
+    const b = c.topicBucket ?? 'unknown';
+    counts.set(b, (counts.get(b) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}
+
+function getVerdictKind(verdict) {
+  if (!verdict) return 'unknown';
+  const lower = verdict.toLowerCase();
+  if (lower.startsWith('split')) return 'split';
+  if (lower.startsWith('drop')) return 'drop';
+  if (lower.startsWith('squash')) return 'squash';
+  if (lower.startsWith('keep')) return 'keep';
+  return lower.split(/[,\s]/)[0] || 'unknown';
+}
+
+function draftPrDefinitions() {
+  // Draft only: you will refine this with humans before rewriting history.
+  return [
+    {
+      id: 'PR01',
+      title: 'Foundations: tooling, deps, test infra',
+      buckets: ['crypto', 'deps', 'config', 'format', 'typecheck', 'dev', 'runtime', 'logging', 'test'],
+    },
+    {
+      id: 'PR02',
+      title: 'Expo web modals + expo-router pin/patch',
+      buckets: ['expo-app', 'expo'],
+      note: 'Draft: later we will split expo-app commits across PRs based on touched files (router/postinstall vs feature UI).',
+    },
+    { id: 'PR03', title: 'i18n structure + localization passes', buckets: ['i18n'] },
+    {
+      id: 'PR04',
+      title: 'UI primitives + navigation/UX surfaces',
+      buckets: ['ui', 'modal', 'popover', 'agent-input', 'a11y', 'web', 'command-palette', 'autocomplete', 'experiments', 'zen'],
+    },
+    { id: 'PR05', title: 'Core storage & persistence primitives', buckets: ['storage', 'persistence', 'settings', 'env', 'auth'] },
+    { id: 'PR06', title: 'Secrets / vault / SecretString', buckets: ['secrets'] },
+    { id: 'PR07', title: 'Profiles + API keys + environment variables UX', buckets: ['profiles', 'api-keys', 'env'] },
+    { id: 'PR08', title: 'New session wizard + session creation UX', buckets: ['new-session', 'new', 'machine'] },
+    { id: 'PR09', title: 'Permissions + tool views', buckets: ['permission', 'tools'] },
+    {
+      id: 'PR10',
+      title: 'CLI/daemon/RPC plumbing + capabilities',
+      buckets: [
+        'capabilities',
+        'cli-detection',
+        'detect-cli',
+        'rpc',
+        'daemon',
+        'socket',
+        'hooks',
+        'happy',
+        'cli',
+        'happy-cli',
+        'app',
+        'common',
+        'utils',
+        'pr107',
+        'reducer',
+      ],
+    },
+    { id: 'PR11', title: 'Terminal/tmux/headless + Ink UX', buckets: ['terminal', 'tmux', 'ink'] },
+    { id: 'PR12', title: 'Message queue V1 + pending/discard flows', buckets: ['queue', 'sync'] },
+    { id: 'PR13', title: 'Resume + session lifecycle', buckets: ['resume', 'session', 'sessions', 'scanner', 'offline'] },
+    { id: 'PR14', title: 'Codex & Claude integration', buckets: ['codex', 'claude', 'gemini', 'fork'] },
+    { id: 'PR15', title: 'Server & server-light: sqlite flavor, schema sync, storage backends', buckets: ['server-light', 'server', 'storage', 'security'] },
+  ];
+}
+
+function assignCommitsToPrs(commits, prDefs) {
+  const bucketToPr = new Map();
+  for (const pr of prDefs) {
+    for (const b of pr.buckets) {
+      // first-wins: later we will refine for overlapping buckets like storage/env/expo-app.
+      if (!bucketToPr.has(b)) bucketToPr.set(b, pr.id);
+    }
+  }
+
+  const byPr = new Map(prDefs.map((p) => [p.id, []]));
+  const unassigned = [];
+
+  for (const c of commits) {
+    const prId = bucketToPr.get(c.topicBucket ?? 'unknown') ?? null;
+    if (!prId) {
+      unassigned.push(c);
+      continue;
+    }
+    byPr.get(prId).push(c);
+  }
+
+  for (const pr of prDefs) {
+    byPr.set(
+      pr.id,
+      (byPr.get(pr.id) ?? []).sort((a, b) => a.n - b.n),
+    );
+  }
+
+  const assignedCount = [...byPr.values()].reduce((sum, list) => sum + list.length, 0);
+  return { byPr, unassigned, assignedCount };
+}
+
+async function main() {
+  const [analysisMd, manualMd] = await Promise.all([
+    fs.readFile(ANALYSIS_PATH, 'utf8'),
+    fs.readFile(MANUAL_PATH, 'utf8'),
+  ]);
+
+  const analysisSections = splitCommitSections(analysisMd);
+  const manualSections = splitCommitSections(manualMd);
+
+  const commits = [];
+  for (let n = 1; n <= 249; n++) {
+    const a = analysisSections.get(n);
+    const m = manualSections.get(n);
+    if (!a || !m) {
+      throw new Error(`Missing section for commit ${String(n).padStart(3, '0')}: analysis=${Boolean(a)} manual=${Boolean(m)}`);
+    }
+    const analysis = parseAnalysisSection(a);
+    const manual = parseManualSection(m);
+    commits.push({
+      n,
+      date: analysis.date ?? manual.date,
+      sha: analysis.sha ?? null,
+      shaShort: analysis.shaShort ?? manual.shaShort,
+      scopeTag: manual.scopeTag,
+      subject: analysis.subject ?? manual.subject,
+      topicBucket: analysis.topicBucket,
+      touchedAreas: analysis.touchedAreas,
+      filesChanged: analysis.filesChanged,
+      linesAdded: analysis.linesAdded,
+      linesDeleted: analysis.linesDeleted,
+      files: analysis.files,
+      verdict: manual.verdict,
+      verdictKind: getVerdictKind(manual.verdict),
+      notesReviewed: manual.notesReviewed,
+      reviewedAt: manual.reviewedAt,
+      notesUpdated: manual.notesUpdated,
+      depends: manual.depends,
+      rewriteHints: manual.rewriteHints,
+    });
+  }
+
+  // Hard guard: pass2 must be complete before we proceed.
+  const notReviewed = commits.filter((c) => c.notesReviewed !== 'yes');
+  if (notReviewed.length) {
+    throw new Error(`Pass2 notesReviewed not complete. Remaining: ${notReviewed.map((c) => c.n).join(', ')}`);
+  }
+
+  await fs.writeFile(OUT_INDEX_JSON, JSON.stringify({ generatedAt: new Date().toISOString(), commits }, null, 2) + '\n', 'utf8');
+
+  const tsvHeader = [
+    'n',
+    'date',
+    'shaShort',
+    'scopeTag',
+    'topicBucket',
+    'subject',
+    'verdictKind',
+    'verdict',
+    'filesChanged',
+    'linesAdded',
+    'linesDeleted',
+    'notesReviewed',
+    'reviewedAt',
+    'notesUpdated',
+  ].join('\t');
+  const tsvRows = commits.map((c) =>
+    [
+      String(c.n).padStart(3, '0'),
+      c.date,
+      c.shaShort,
+      c.scopeTag,
+      c.topicBucket,
+      c.subject,
+      c.verdictKind,
+      c.verdict,
+      c.filesChanged,
+      c.linesAdded,
+      c.linesDeleted,
+      c.notesReviewed,
+      c.reviewedAt,
+      c.notesUpdated,
+    ]
+      .map(tsvEscape)
+      .join('\t'),
+  );
+  await fs.writeFile(
+    OUT_INDEX_TSV,
+    `# GENERATED FILE - do not edit by hand.\n# Regenerate: node docs/commit-audits/happy/_tools/generate-plans.mjs\n${tsvHeader}\n${tsvRows.join('\n')}\n`,
+    'utf8',
+  );
+
+  const bucketSummary = buildBucketSummary(commits);
+  const bucketMd = [
+    '# Topic buckets (auto-triage)',
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+    'Counts:',
+    '',
+    ...bucketSummary.map(([b, count]) => `- \`${b}\`: ${count}`),
+    '',
+    'Notes:',
+    '- These buckets come from `leeroy-wip.commit-analysis.md` and are a starting point, not the final PR grouping.',
+    '- Some buckets (notably `expo-app`, `storage`, `env`, `sync`) will be split across PRs by feature surface during planning.',
+    '',
+  ].join('\n');
+  await fs.writeFile(OUT_BUCKETS_MD, bucketMd, 'utf8');
+
+  const splitCommits = commits.filter((c) => c.verdictKind === 'split');
+  const splitMd = [
+    '# Split plan (draft)',
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+    'This lists commits whose manual-review verdict suggests **splitting** (mixed concerns).',
+    'The “how to split” is captured here as a checklist so we can execute it mechanically during the rewrite (via `cherry-pick -n` + selective staging).',
+    '',
+    ...splitCommits.flatMap((c) => {
+      const head = `## ${String(c.n).padStart(3, '0')} ${c.shaShort} ${c.subject ?? ''}`.trim();
+      const files = c.files?.length ? c.files.map((f) => `- ${f.status} \`${f.path}\``) : ['- (files unavailable)'];
+      const hints = c.rewriteHints?.length ? c.rewriteHints.map((h) => `- ${h}`) : ['- (no rewrite hints captured)'];
+      return [
+        head,
+        '',
+        '- Verdict: split',
+        ...(c.depends?.length ? ['- Depends on:', ...c.depends.map((d) => `  - ${d}`)] : []),
+        '',
+        'Files touched:',
+        ...files,
+        '',
+        'Rewrite hints (from manual review):',
+        ...hints,
+        '',
+      ];
+    }),
+  ].join('\n');
+  await fs.writeFile(OUT_SPLIT_MD, splitMd, 'utf8');
+
+  const prDefs = draftPrDefinitions();
+  const { byPr, unassigned, assignedCount } = assignCommitsToPrs(commits, prDefs);
+  if (unassigned.length) {
+    throw new Error(`PR assignment left ${unassigned.length} commits unassigned.`);
+  }
+  if (assignedCount !== commits.length) {
+    throw new Error(`PR assignment mismatch: assigned=${assignedCount} total=${commits.length}`);
+  }
+
+  const prMdLines = [
+    '# PR stack plan (draft)',
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+    'This is a **draft** proposal to split the `leeroy-wip` changes into ~15 PRs.',
+    'It is derived from the audit metadata (topic buckets + manual verdicts), and must be reviewed/edited by humans before any history rewrite.',
+    '',
+    'Principles:',
+    '- Prefer “final feature state” (squash fixups into the feature commits).',
+    '- Keep commit granularity *within* a PR, but avoid “evolution noise” (back-and-forth) in the rewritten history.',
+    '- Avoid mega-commits: when a commit is marked `split`, execute it as multiple commits by file/feature boundary.',
+    '',
+    'Coverage:',
+    `- Total commits: ${commits.length}`,
+    `- notesReviewed=yes: ${commits.filter((c) => c.notesReviewed === 'yes').length}`,
+    `- Split candidates: ${splitCommits.length}`,
+    `- Assigned to PRs: ${assignedCount}`,
+    '',
+  ];
+
+  for (const pr of prDefs) {
+    const items = byPr.get(pr.id) ?? [];
+    prMdLines.push(`## ${pr.id}: ${pr.title}`);
+    if (pr.note) prMdLines.push(`- Note: ${pr.note}`);
+    prMdLines.push(`- Buckets: ${pr.buckets.map((b) => `\`${b}\``).join(', ')}`);
+    prMdLines.push(`- Commits: ${items.length}`);
+    prMdLines.push('- Commit list:');
+    for (const c of items) {
+      const flags = [];
+      if (c.verdictKind === 'split') flags.push('SPLIT');
+      if (c.verdictKind === 'drop') flags.push('DROP?');
+      if (c.notesUpdated === 'yes') flags.push('notesUpdated');
+      const flagText = flags.length ? ` [${flags.join(',')}]` : '';
+      prMdLines.push(`  - ${String(c.n).padStart(3, '0')} ${c.shaShort} ${c.subject ?? ''}${flagText}`.trimEnd());
+    }
+    prMdLines.push('');
+  }
+
+  await fs.writeFile(OUT_PR_MD, prMdLines.join('\n') + '\n', 'utf8');
+
+  // Small sanity print (for CI/local use)
+  // eslint-disable-next-line no-console
+  console.log(`[audit] wrote: ${path.relative(ROOT, OUT_INDEX_JSON)}`);
+  // eslint-disable-next-line no-console
+  console.log(`[audit] wrote: ${path.relative(ROOT, OUT_INDEX_TSV)}`);
+  // eslint-disable-next-line no-console
+  console.log(`[audit] wrote: ${path.relative(ROOT, OUT_BUCKETS_MD)}`);
+  // eslint-disable-next-line no-console
+  console.log(`[audit] wrote: ${path.relative(ROOT, OUT_SPLIT_MD)}`);
+  // eslint-disable-next-line no-console
+  console.log(`[audit] wrote: ${path.relative(ROOT, OUT_PR_MD)}`);
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exitCode = 1;
+});