@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/review/base_ref.mjs

@@ -0,0 +1,82 @@
+import { inferRemoteNameForOwner, parseGithubOwner } from '../git/worktrees.mjs';
+import { gitCapture, gitOk, normalizeRemoteName, resolveRemoteDefaultBranch, ensureRemoteRefAvailable } from '../git/git.mjs';
+
+async function currentBranchName({ cwd }) {
+  const branch = (await gitCapture({ cwd, args: ['branch', '--show-current'] }).catch(() => '')).trim();
+  return branch;
+}
+
+function branchOwnerPrefix(branch) {
+  const b = String(branch ?? '').trim();
+  if (!b || !b.includes('/')) return '';
+  return b.split('/')[0] ?? '';
+}
+
+async function inferRemoteFromBranchOwner({ cwd }) {
+  const branch = await currentBranchName({ cwd });
+  const owner = branchOwnerPrefix(branch);
+  if (!owner) return '';
+
+  // Confirm this "owner" is plausible (matches at least one remote's GitHub owner).
+  for (const remoteName of ['upstream', 'origin', 'fork']) {
+    try {
+      const url = (await gitCapture({ cwd, args: ['remote', 'get-url', remoteName] })).trim();
+      const parsedOwner = parseGithubOwner(url);
+      if (parsedOwner && parsedOwner === owner) {
+        return remoteName;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // Fall back to the generic inference helper (it checks remotes in priority order).
+  return await inferRemoteNameForOwner({ repoDir: cwd, owner });
+}
+
+export async function resolveBaseRef({
+  cwd,
+  baseRefOverride = '',
+  baseRemoteOverride = '',
+  baseBranchOverride = '',
+  stackRemoteFallback = '',
+} = {}) {
+  const repoDir = String(cwd ?? '').trim();
+  if (!repoDir) {
+    throw new Error('[review] missing cwd for base resolution');
+  }
+
+  if (!(await gitOk({ cwd: repoDir, args: ['rev-parse', '--is-inside-work-tree'] }))) {
+    throw new Error(`[review] not a git repository: ${repoDir}`);
+  }
+
+  const explicitRef = String(baseRefOverride ?? '').trim();
+  if (explicitRef) {
+    return { baseRef: explicitRef, remote: '', branch: '' };
+  }
+
+  const stackFallback = String(stackRemoteFallback ?? '').trim();
+  const inferredRemote = await inferRemoteFromBranchOwner({ cwd: repoDir });
+  const remoteCandidates = [];
+  for (const name of [String(baseRemoteOverride ?? '').trim(), inferredRemote, stackFallback, 'upstream', 'origin', 'fork']) {
+    if (!name || remoteCandidates.includes(name)) continue;
+    remoteCandidates.push(name);
+  }
+
+  for (const candidate of remoteCandidates) {
+    const remote = await normalizeRemoteName({ cwd: repoDir, remote: candidate });
+    const branch = String(baseBranchOverride ?? '').trim() || (await resolveRemoteDefaultBranch({ cwd: repoDir, remote }));
+    const ok = await ensureRemoteRefAvailable({ cwd: repoDir, remote, branch });
+    if (ok) {
+      return { baseRef: `${remote}/${branch}`, remote, branch };
+    }
+  }
+
+  const first = remoteCandidates[0] || 'upstream';
+  const remote = await normalizeRemoteName({ cwd: repoDir, remote: first });
+  const branch = String(baseBranchOverride ?? '').trim() || (await resolveRemoteDefaultBranch({ cwd: repoDir, remote }));
+  throw new Error(
+    `[review] unable to resolve base ref refs/remotes/${remote}/${branch} in ${repoDir}\n` +
+      `[review] hint: ensure remote "${remote}" exists and has a configured HEAD/default branch (or pass --base-ref).`
+  );
+}

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

@@ -0,0 +1,89 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCapture } from '../proc/proc.mjs';
+import { resolveBaseRef } from './base_ref.mjs';
+
+async function runGit(cwd, args) {
+  await runCapture('git', args, { cwd });
+}
+
+async function makeRepoWithRemoteHead(remoteName = 'upstream') {
+  const root = await mkdtemp(join(tmpdir(), 'hs-review-base-ref-'));
+  const remote = join(root, 'remote.git');
+  const local = join(root, 'local');
+
+  await runGit(root, ['init', '--bare', remote]);
+  await runGit(root, ['init', '-b', 'main', local]);
+  await runGit(local, ['config', 'user.email', 'test@example.com']);
+  await runGit(local, ['config', 'user.name', 'Test User']);
+  await writeFile(join(local, 'file.txt'), 'hello\n', 'utf-8');
+  await runGit(local, ['add', '.']);
+  await runGit(local, ['commit', '-m', 'initial']);
+  await runGit(local, ['remote', 'add', remoteName, remote]);
+  await runGit(local, ['push', '-u', remoteName, 'main']);
+  // In CI, `git init --bare` may default HEAD to `master`, and `remote set-head --auto` fails
+  // with "Cannot determine remote HEAD" if that branch doesn't exist. Make it deterministic.
+  await runGit(remote, ['symbolic-ref', 'HEAD', 'refs/heads/main']);
+  // Ensure refs/remotes/<remote>/HEAD exists.
+  await runGit(local, ['remote', 'set-head', remoteName, '--auto']);
+
+  return { root, local };
+}
+
+test('resolveBaseRef uses explicit --base-ref override', async () => {
+  const { root, local } = await makeRepoWithRemoteHead();
+  try {
+    const res = await resolveBaseRef({ cwd: local, baseRefOverride: 'upstream/main' });
+    assert.equal(res.baseRef, 'upstream/main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolveBaseRef infers default branch from refs/remotes/<remote>/HEAD', async () => {
+  const { root, local } = await makeRepoWithRemoteHead();
+  try {
+    const res = await resolveBaseRef({ cwd: local, baseRemoteOverride: 'upstream' });
+    assert.equal(res.baseRef, 'upstream/main');
+    assert.equal(res.remote, 'upstream');
+    assert.equal(res.branch, 'main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolveBaseRef uses stack remote fallback when no override is passed', async () => {
+  const { root, local } = await makeRepoWithRemoteHead('origin');
+  try {
+    const res = await resolveBaseRef({ cwd: local, stackRemoteFallback: 'origin' });
+    assert.equal(res.baseRef, 'origin/main');
+    assert.equal(res.remote, 'origin');
+    assert.equal(res.branch, 'main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolveBaseRef falls back to origin when upstream is unavailable', async () => {
+  const { root, local } = await makeRepoWithRemoteHead('origin');
+  try {
+    const res = await resolveBaseRef({ cwd: local });
+    assert.equal(res.baseRef, 'origin/main');
+    assert.equal(res.remote, 'origin');
+    assert.equal(res.branch, 'main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolveBaseRef throws for non-git directory', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-review-base-ref-non-git-'));
+  try {
+    await assert.rejects(async () => await resolveBaseRef({ cwd: dir }), /not a git repository/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

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,107 @@
+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 },
+  ]);
+});
+
+test('planCommitChunks validates options and handles empty commit input', async () => {
+  await assert.rejects(
+    async () =>
+      await planCommitChunks({
+        baseCommit: 'BASE',
+        commits: 'not-an-array',
+        maxFiles: 3,
+        countFilesBetween: async () => 1,
+      }),
+    /commits must be an array/
+  );
+
+  await assert.rejects(
+    async () =>
+      await planCommitChunks({
+        baseCommit: 'BASE',
+        commits: ['c1'],
+        maxFiles: 0,
+        countFilesBetween: async () => 1,
+      }),
+    /maxFiles must be a positive number/
+  );
+
+  await assert.rejects(
+    async () =>
+      await planCommitChunks({
+        baseCommit: 'BASE',
+        commits: ['c1'],
+        maxFiles: 3,
+        countFilesBetween: null,
+      }),
+    /countFilesBetween must be a function/
+  );
+
+  const chunks = await planCommitChunks({
+    baseCommit: 'BASE',
+    commits: [' ', ''],
+    maxFiles: 3,
+    countFilesBetween: async () => 1,
+  });
+  assert.deepEqual(chunks, []);
+});
+
+test('planCommitChunks rejects invalid countFilesBetween results', async () => {
+  await assert.rejects(
+    async () =>
+      await planCommitChunks({
+        baseCommit: 'BASE',
+        commits: ['c1'],
+        maxFiles: 3,
+        countFilesBetween: async () => Number.NaN,
+      }),
+    /returned invalid count/
+  );
+});

package/scripts/utils/review/detached_worktree.mjs

@@ -0,0 +1,61 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { ensureDir } from '../fs/ops.mjs';
+import { runCapture } from '../proc/proc.mjs';
+
+function sanitizeLabel(raw) {
+  return String(raw ?? 'worktree')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function defaultNonce() {
+  const rand = Math.random().toString(16).slice(2, 10);
+  return `${process.pid}-${Date.now()}-${rand}`;
+}
+
+export function computeDetachedWorktreeDir({ repoRootDir, label, headCommit, nonce } = {}) {
+  const root = String(repoRootDir ?? '').trim();
+  if (!root) throw new Error('[review] computeDetachedWorktreeDir: missing repoRootDir');
+
+  const safeLabel = sanitizeLabel(label);
+  const short = String(headCommit ?? '').slice(0, 12);
+  const n = String(nonce ?? defaultNonce()).trim();
+  return join(root, '.project', 'review-worktrees', `${safeLabel}-${short}-${n}`);
+}
+
+/**
+ * Create a detached git worktree for `headCommit`, run `fn(worktreeDir)`, then clean up.
+ *
+ * Notes:
+ * - The worktree directory name includes a nonce to avoid collisions when a prior run crashed
+ *   and left behind a directory, or when multiple review runs happen in parallel.
+ * - We do best-effort cleanup even if `fn` throws.
+ */
+export async function withDetachedWorktree({ repoDir, headCommit, label, env, nonce }, fn) {
+  const root = (await runCapture('git', ['rev-parse', '--show-toplevel'], { cwd: repoDir, env })).toString().trim();
+  if (!root) throw new Error('[review] failed to resolve git toplevel');
+
+  const worktreesRoot = join(root, '.project', 'review-worktrees');
+  await ensureDir(worktreesRoot);
+  const dir = computeDetachedWorktreeDir({ repoRootDir: root, label, headCommit, nonce });
+
+  // Extremely defensive: should not happen with nonced dirs, but avoid surprising errors.
+  if (existsSync(dir)) {
+    throw new Error(`[review] detached worktree dir already exists: ${dir}`);
+  }
+
+  try {
+    await runCapture('git', ['worktree', 'add', '--detach', dir, headCommit], { cwd: repoDir, env });
+    return await fn(dir);
+  } finally {
+    try {
+      await runCapture('git', ['worktree', 'remove', '--force', dir], { cwd: repoDir, env });
+      await runCapture('git', ['worktree', 'prune'], { cwd: repoDir, env });
+    } catch {
+      // best-effort cleanup; leave an orphaned worktree if needed
+    }
+  }
+}
+

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

@@ -0,0 +1,61 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { run, runCapture } from '../proc/proc.mjs';
+import { computeDetachedWorktreeDir, withDetachedWorktree } from './detached_worktree.mjs';
+
+function gitEnv() {
+  const clean = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith('HAPPIER_STACK_')) 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('computeDetachedWorktreeDir includes nonce to avoid collisions', () => {
+  const dir1 = computeDetachedWorktreeDir({ repoRootDir: '/repo', label: 'coderabbit-1-of-21', headCommit: 'abcdef0123456789', nonce: 'n1' });
+  const dir2 = computeDetachedWorktreeDir({ repoRootDir: '/repo', label: 'coderabbit-1-of-21', headCommit: 'abcdef0123456789', nonce: 'n2' });
+  assert.notEqual(dir1, dir2);
+  assert.ok(dir1.includes('coderabbit-1-of-21-abcdef012345-n1'));
+  assert.ok(dir2.includes('coderabbit-1-of-21-abcdef012345-n2'));
+});
+
+test('withDetachedWorktree can be called repeatedly without directory collisions', async () => {
+  const repo = await mkdtemp(join(tmpdir(), 'happy-review-wt-'));
+  const env = gitEnv();
+
+  try {
+    await run('git', ['init', '-q'], { cwd: repo, env });
+    await run('git', ['checkout', '-q', '-b', 'main'], { cwd: repo, env });
+    await mkdir(join(repo, 'x'), { recursive: true });
+    await writeFile(join(repo, 'x', 'a.txt'), 'a\n', 'utf-8');
+    await run('git', ['add', '.'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'base'], { cwd: repo, env });
+
+    const head = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repo, env })).trim();
+
+    const seen = [];
+    await withDetachedWorktree({ repoDir: repo, headCommit: head, label: 'test', env, nonce: 'one' }, async (dir) => {
+      seen.push(dir);
+      assert.equal((await runCapture('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, env })).trim(), 'true');
+    });
+    await withDetachedWorktree({ repoDir: repo, headCommit: head, label: 'test', env, nonce: 'two' }, async (dir) => {
+      seen.push(dir);
+      assert.equal((await runCapture('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, env })).trim(), 'true');
+    });
+
+    assert.equal(seen.length, 2);
+    assert.notEqual(seen[0], seen[1]);
+  } finally {
+    await rm(repo, { recursive: true, force: true });
+  }
+});