sequant 2.9.0 → 2.10.0

package/dist/src/lib/merge-check/combined-branch-test.js

@@ -2,10 +2,37 @@
  * Combined branch testing (AC-1)
  *
  * Creates a temporary branch merging all feature branches from a run batch,
- * runs npm test && npm run build on the combined state, and reports results.
+ * reinstalls dependencies when the merge moved a lockfile, then runs the
+ * project's test and build scripts on the combined state and reports results.
  */
 import { spawnSync } from "child_process";
 import { getBranchRef } from "./types.js";
+import { detectPackageManagerSync, resolvePackageManagerConfig, } from "../stacks.js";
+import { toCommandResult, resolveFailureReason, } from "./command-result.js";
+// Re-exported for the existing test suite and any downstream consumer that
+// imported these from here before they moved to ./command-result.js.
+export { resolveFailureReason };
+/**
+ * Lockfile names for the JS package managers we support. Kept in sync with the
+ * equivalent list in `workflow/worktree-manager.ts`.
+ */
+const LOCKFILES = [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "bun.lockb",
+    "bun.lock",
+    "yarn.lock",
+];
+/**
+ * Per-step command timeouts. A dependency install and a full test suite are
+ * both slower than the previous flat 2-minute budget allowed. An expired
+ * timeout kills the process with `status: null` and no captured output, which
+ * showed up as a BLOCKED verdict with no stated reason (#803).
+ */
+const INSTALL_TIMEOUT_MS = 300_000; // 5 min
+const TEST_BUILD_TIMEOUT_MS = 600_000; // 10 min
+/** Ref the combined state is built on top of, and compared against. */
+const BASE_REF = "origin/main";
 /**
  * Run a git command and return the result
  */
@@ -22,23 +49,39 @@ function git(args, cwd) {
     };
 }
 /**
- * Run npm command and return result
+ * Run a package-manager command line (e.g. "npm ci", "pnpm run build").
+ *
+ * @param command Full command line, as stored in PM_CONFIG
+ * @param cwd Working directory
+ * @param timeoutMs Kill the command after this long
+ * @internal Exported for testing
  */
-function npm(args, cwd) {
-    const result = spawnSync("npm", args, {
+export function runPackageManagerCommand(command, cwd, timeoutMs) {
+    const [bin, ...args] = command.split(" ");
+    const result = spawnSync(bin, args, {
         cwd,
         stdio: "pipe",
         encoding: "utf-8",
-        timeout: 120_000, // 2 min timeout for test/build
+        timeout: timeoutMs,
+        // On Windows the package managers are `.cmd` shims, which CreateProcess
+        // will not resolve from a bare "npm"/"pnpm". `command` is always a constant
+        // from PM_CONFIG — never user input — so there is nothing to inject here.
+        shell: process.platform === "win32",
     });
-    return {
-        ok: result.status === 0,
-        stdout: result.stdout?.trim() ?? "",
-        stderr: result.stderr?.trim() ?? "",
-    };
+    return toCommandResult(result);
 }
 /**
- * Create temp branch, merge all feature branches, run tests and build.
+ * Whether any lockfile differs between `baseRef` and the current HEAD.
+ *
+ * @internal Exported for testing
+ */
+export function lockfileChanged(repoRoot, baseRef) {
+    const result = git(["diff", "--name-only", baseRef, "HEAD", "--", ...LOCKFILES], repoRoot);
+    return result.ok && result.stdout.length > 0;
+}
+/**
+ * Create temp branch, merge all feature branches, reinstall dependencies if the
+ * lockfile moved, then run tests and build.
  *
  * @param branches - Feature branches to merge
  * @param repoRoot - Path to the git repository root
@@ -49,123 +92,203 @@ export function runCombinedBranchTest(branches, repoRoot) {
     const tempBranch = `merge-check/temp-${Date.now()}`;
     const branchResults = [];
     const batchFindings = [];
-    const mergeAttempts = [];
-    // Save current branch to restore in finally block
+    const pm = detectPackageManagerSync(repoRoot);
+    // Resolved against the repo rather than read straight off PM_CONFIG: yarn's
+    // frozen install differs between classic and berry, and `pm` is "yarn" for
+    // both (#871).
+    //
+    // This resolution describes the PRE-MERGE tree, which is what the restore
+    // install in the `finally` below runs against — it fires after
+    // `git checkout restoreBranch`, so the original branch's yarn major is the
+    // right one there. `runChecks` re-resolves for the combined state, where a
+    // merged branch may have changed the major.
+    const pmConfig = resolvePackageManagerConfig(pm, repoRoot);
+    // Flipped the moment we start installing against the combined lockfile, so
+    // the caller's node_modules can be put back afterwards. A mutable holder
+    // rather than a return value: if runChecks throws, a return value never
+    // arrives and the restore would be skipped precisely when the tree is most
+    // likely to be inconsistent.
+    const installState = { installedCombinedDeps: false };
+    // Save current branch to restore in the cleanup step
     const originalBranch = git(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot);
     try {
-        // Fetch latest from remote
-        git(["fetch", "origin"], repoRoot);
-        // Create temp branch from main
-        const createResult = git(["checkout", "-b", tempBranch, "origin/main"], repoRoot);
-        if (!createResult.ok) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "error",
-                message: `Failed to create temp branch: ${createResult.stderr}`,
-            });
-            return buildResult(branchResults, batchFindings, startTime);
-        }
-        // Merge each feature branch
-        for (const branch of branches) {
-            const mergeResult = git(["merge", "--no-ff", "--no-edit", getBranchRef(branch)], repoRoot);
-            if (mergeResult.ok) {
-                mergeAttempts.push({
-                    issueNumber: branch.issueNumber,
-                    branch: branch.branch,
-                    success: true,
-                });
-                branchResults.push({
-                    issueNumber: branch.issueNumber,
-                    verdict: "PASS",
-                    findings: [
-                        {
-                            check: "combined-branch-test",
-                            severity: "info",
-                            message: `Branch merged cleanly into combined state`,
-                            issueNumber: branch.issueNumber,
-                        },
-                    ],
-                });
-            }
-            else {
-                // Get conflicting files
-                const conflictResult = git(["diff", "--name-only", "--diff-filter=U"], repoRoot);
-                const conflictFiles = conflictResult.stdout
-                    ? conflictResult.stdout.split("\n")
-                    : [];
-                mergeAttempts.push({
-                    issueNumber: branch.issueNumber,
-                    branch: branch.branch,
-                    success: false,
-                    conflictFiles,
-                    error: mergeResult.stderr,
-                });
-                branchResults.push({
-                    issueNumber: branch.issueNumber,
-                    verdict: "FAIL",
-                    findings: [
-                        {
-                            check: "combined-branch-test",
-                            severity: "error",
-                            message: `Merge conflict with ${conflictFiles.length} file(s): ${conflictFiles.join(", ")}`,
-                            issueNumber: branch.issueNumber,
-                        },
-                    ],
+        runChecks(branches, repoRoot, tempBranch, pm, branchResults, batchFindings, installState);
+    }
+    finally {
+        // Restore original branch and delete temp branch
+        const restoreBranch = originalBranch.ok ? originalBranch.stdout : "main";
+        git(["checkout", restoreBranch], repoRoot);
+        git(["branch", "-D", tempBranch], repoRoot);
+        // We installed the combined state's dependency tree into the caller's
+        // node_modules; put it back so the restored branch is not left running
+        // against another branch's dependencies.
+        //
+        // Frozen again, for the same reason as the forward install: a plain
+        // `npm install` normalizes and rewrites the lockfile, which would leave
+        // the user's restored branch with a dirty working tree that this check
+        // never asked them for.
+        if (installState.installedCombinedDeps) {
+            const restoreInstall = runPackageManagerCommand(pmConfig.ciInstall, repoRoot, INSTALL_TIMEOUT_MS);
+            if (!restoreInstall.ok) {
+                batchFindings.push({
+                    check: "combined-branch-test",
+                    severity: "warning",
+                    message: `Dependencies were reinstalled for the combined state but could not be restored for \`${restoreBranch}\`. Run \`${pmConfig.ciInstall}\` to resync node_modules: ${resolveFailureReason(restoreInstall)}`,
                 });
-                // Abort the failed merge and continue
-                git(["merge", "--abort"], repoRoot);
             }
         }
-        // If any merges failed, skip tests but report what we have
-        const failedMerges = mergeAttempts.filter((m) => !m.success);
-        if (failedMerges.length > 0) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "error",
-                message: `${failedMerges.length}/${branches.length} branches had merge conflicts — skipping test/build`,
+    }
+    // Built after cleanup so findings pushed during cleanup are reflected in the
+    // verdict rather than silently arriving too late to affect `passed`.
+    return buildResult(branchResults, batchFindings, startTime);
+}
+/**
+ * Assemble the combined state and run install/test/build against it.
+ *
+ * Mutates `branchResults`, `batchFindings`, and `installState` — the last so
+ * the caller's cleanup can restore node_modules even if this function throws.
+ */
+function runChecks(branches, repoRoot, tempBranch, pm, branchResults, batchFindings, installState) {
+    const mergeAttempts = [];
+    // Fetch latest from remote
+    git(["fetch", "origin"], repoRoot);
+    // Create temp branch from main
+    const createResult = git(["checkout", "-b", tempBranch, BASE_REF], repoRoot);
+    if (!createResult.ok) {
+        batchFindings.push({
+            check: "combined-branch-test",
+            severity: "error",
+            message: `Failed to create temp branch: ${createResult.stderr}`,
+        });
+        return;
+    }
+    // Merge each feature branch
+    for (const branch of branches) {
+        const mergeResult = git(["merge", "--no-ff", "--no-edit", getBranchRef(branch)], repoRoot);
+        if (mergeResult.ok) {
+            mergeAttempts.push({
+                issueNumber: branch.issueNumber,
+                branch: branch.branch,
+                success: true,
             });
-            return buildResult(branchResults, batchFindings, startTime);
-        }
-        // Run npm test
-        const testResult = npm(["test"], repoRoot);
-        if (testResult.ok) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "info",
-                message: "npm test passed on combined state",
+            branchResults.push({
+                issueNumber: branch.issueNumber,
+                verdict: "PASS",
+                findings: [
+                    {
+                        check: "combined-branch-test",
+                        severity: "info",
+                        message: `Branch merged cleanly into combined state`,
+                        issueNumber: branch.issueNumber,
+                    },
+                ],
             });
         }
         else {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "error",
-                message: `npm test failed on combined state: ${testResult.stderr.slice(0, 500)}`,
+            // Get conflicting files
+            const conflictResult = git(["diff", "--name-only", "--diff-filter=U"], repoRoot);
+            const conflictFiles = conflictResult.stdout
+                ? conflictResult.stdout.split("\n")
+                : [];
+            mergeAttempts.push({
+                issueNumber: branch.issueNumber,
+                branch: branch.branch,
+                success: false,
+                conflictFiles,
+                error: mergeResult.stderr,
             });
-        }
-        // Run npm run build
-        const buildResult2 = npm(["run", "build"], repoRoot);
-        if (buildResult2.ok) {
-            batchFindings.push({
-                check: "combined-branch-test",
-                severity: "info",
-                message: "npm run build passed on combined state",
+            branchResults.push({
+                issueNumber: branch.issueNumber,
+                verdict: "FAIL",
+                findings: [
+                    {
+                        check: "combined-branch-test",
+                        severity: "error",
+                        message: `Merge conflict with ${conflictFiles.length} file(s): ${conflictFiles.join(", ")}`,
+                        issueNumber: branch.issueNumber,
+                    },
+                ],
             });
+            // Abort the failed merge and continue
+            git(["merge", "--abort"], repoRoot);
         }
-        else {
+    }
+    // If any merges failed, skip tests but report what we have
+    const failedMerges = mergeAttempts.filter((m) => !m.success);
+    if (failedMerges.length > 0) {
+        batchFindings.push({
+            check: "combined-branch-test",
+            severity: "error",
+            message: `${failedMerges.length}/${branches.length} branches had merge conflicts — skipping test/build`,
+        });
+        return;
+    }
+    // Resolved HERE, after the merges landed, not from the caller's pre-merge
+    // resolution: the commands below run against the combined tree, and a merged
+    // branch can move the yarn major (a `packageManager` bump, a new
+    // `.yarnrc.yml`). Installing the combined state with the pre-merge major's
+    // frozen-install flag would fail on an unknown option and report a false
+    // BLOCKED — the exact failure class #803 added this install to prevent (#871).
+    const pmConfig = resolvePackageManagerConfig(pm, repoRoot);
+    // Reinstall dependencies when the merged branches moved the lockfile (#803).
+    // Without this, test/build run against the node_modules of whatever branch
+    // the user happened to be on, so a batch that merely added a dependency fails
+    // with module-not-found errors — a false BLOCKED on a healthy stack.
+    //
+    // A frozen install is used rather than a plain one: it mirrors what CI does,
+    // it will not rewrite the lockfile (which would dirty the temp branch and
+    // break the checkout during cleanup), and it fails loudly on a lockfile that
+    // is inconsistent with package.json.
+    if (lockfileChanged(repoRoot, BASE_REF)) {
+        // Marked before the install runs, not after: a frozen install deletes
+        // node_modules up front, so even a failed or interrupted one leaves the
+        // caller's tree needing a restore.
+        installState.installedCombinedDeps = true;
+        const installResult = runPackageManagerCommand(pmConfig.ciInstall, repoRoot, INSTALL_TIMEOUT_MS);
+        if (!installResult.ok) {
+            // Surface install failures on their own terms rather than letting them
+            // resurface downstream as an unexplained test failure.
             batchFindings.push({
                 check: "combined-branch-test",
                 severity: "error",
-                message: `npm run build failed on combined state: ${buildResult2.stderr.slice(0, 500)}`,
+                message: `Dependency install failed on combined state (\`${pmConfig.ciInstall}\`) — skipping test/build. The merged lockfile may be inconsistent with package.json: ${resolveFailureReason(installResult)}`,
             });
+            return;
         }
-        return buildResult(branchResults, batchFindings, startTime);
-    }
-    finally {
-        // Clean up: restore original branch and delete temp branch
-        const restoreBranch = originalBranch.ok ? originalBranch.stdout : "main";
-        git(["checkout", restoreBranch], repoRoot);
-        git(["branch", "-D", tempBranch], repoRoot);
+        batchFindings.push({
+            check: "combined-branch-test",
+            severity: "info",
+            message: `Lockfile changed in the combined state — reinstalled dependencies with \`${pmConfig.ciInstall}\``,
+        });
     }
+    // Run the test suite
+    const testCommand = `${pmConfig.run} test`;
+    const testResult = runPackageManagerCommand(testCommand, repoRoot, TEST_BUILD_TIMEOUT_MS);
+    batchFindings.push(testResult.ok
+        ? {
+            check: "combined-branch-test",
+            severity: "info",
+            message: `\`${testCommand}\` passed on combined state`,
+        }
+        : {
+            check: "combined-branch-test",
+            severity: "error",
+            message: `\`${testCommand}\` failed on combined state: ${resolveFailureReason(testResult)}`,
+        });
+    // Run the build
+    const buildCommand = `${pmConfig.run} build`;
+    const buildOutcome = runPackageManagerCommand(buildCommand, repoRoot, TEST_BUILD_TIMEOUT_MS);
+    batchFindings.push(buildOutcome.ok
+        ? {
+            check: "combined-branch-test",
+            severity: "info",
+            message: `\`${buildCommand}\` passed on combined state`,
+        }
+        : {
+            check: "combined-branch-test",
+            severity: "error",
+            message: `\`${buildCommand}\` failed on combined state: ${resolveFailureReason(buildOutcome)}`,
+        });
 }
 export function buildResult(branchResults, batchFindings, startTime) {
     const hasErrors = batchFindings.some((f) => f.severity === "error");

package/dist/src/lib/merge-check/command-result.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Normalized spawn results and never-empty failure reasons (#803)
+ *
+ * Shared by every merge-check module that reports on a spawned command. The
+ * motivating defect: a failure reason built from `stderr` alone renders as
+ * `... failed: ` with nothing after it whenever the command wrote its
+ * diagnostics to stdout — which is where vitest, tsc, and npm put theirs.
+ */
+import type { SpawnSyncReturns } from "child_process";
+/** Max characters of captured output included in a failure message. */
+export declare const REASON_MAX_CHARS = 500;
+/**
+ * Outcome of a spawned command, normalized across success, non-zero exit,
+ * signal termination, and spawn failure.
+ */
+export interface CommandResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    status: number | null;
+    signal: string | null;
+    spawnError?: string;
+}
+/**
+ * Normalize a raw `spawnSync` return into a {@link CommandResult}.
+ */
+export declare function toCommandResult(result: SpawnSyncReturns<string>): CommandResult;
+/**
+ * Produce a human-readable, never-empty reason for a failed command.
+ *
+ * Falls through: stderr → stdout tail → spawn error → signal → exit code. The
+ * stdout *tail* is used because test runners put the failure summary last,
+ * while the stderr *head* is kept because the first error is usually the
+ * proximate cause.
+ */
+export declare function resolveFailureReason(result: CommandResult): string;

package/dist/src/lib/merge-check/command-result.js

@@ -0,0 +1,56 @@
+/**
+ * Normalized spawn results and never-empty failure reasons (#803)
+ *
+ * Shared by every merge-check module that reports on a spawned command. The
+ * motivating defect: a failure reason built from `stderr` alone renders as
+ * `... failed: ` with nothing after it whenever the command wrote its
+ * diagnostics to stdout — which is where vitest, tsc, and npm put theirs.
+ */
+/** Max characters of captured output included in a failure message. */
+export const REASON_MAX_CHARS = 500;
+/**
+ * Normalize a raw `spawnSync` return into a {@link CommandResult}.
+ */
+export function toCommandResult(result) {
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout?.trim() ?? "",
+        stderr: result.stderr?.trim() ?? "",
+        status: result.status ?? null,
+        signal: result.signal ?? null,
+        spawnError: result.error?.message,
+    };
+}
+/**
+ * Produce a human-readable, never-empty reason for a failed command.
+ *
+ * Falls through: stderr → stdout tail → spawn error → signal → exit code. The
+ * stdout *tail* is used because test runners put the failure summary last,
+ * while the stderr *head* is kept because the first error is usually the
+ * proximate cause.
+ */
+export function resolveFailureReason(result) {
+    if (result.stderr) {
+        return truncateHead(result.stderr);
+    }
+    if (result.stdout) {
+        return truncateTail(result.stdout);
+    }
+    if (result.spawnError) {
+        return result.spawnError;
+    }
+    if (result.signal) {
+        return `no output; killed by signal ${result.signal} (likely a timeout)`;
+    }
+    return `no output; exited with code ${result.status ?? "unknown"}`;
+}
+function truncateHead(text) {
+    return text.length > REASON_MAX_CHARS
+        ? `${text.slice(0, REASON_MAX_CHARS)}…`
+        : text;
+}
+function truncateTail(text) {
+    return text.length > REASON_MAX_CHARS
+        ? `…${text.slice(-REASON_MAX_CHARS)}`
+        : text;
+}

package/dist/src/lib/merge-check/index.d.ts

@@ -7,6 +7,10 @@
 import { type RunLog } from "../workflow/run-log-schema.js";
 import type { BranchInfo, CheckResult, MergeCommandOptions, MergeReport } from "./types.js";
 import { formatReportMarkdown, formatBranchReportMarkdown, postReportToGitHub } from "./report.js";
+/**
+ * Resolve log directory path
+ */
+export declare function resolveLogDir(customPath?: string): string;
 /**
  * Find the most recent run log file
  */

package/dist/src/lib/merge-check/index.js

@@ -20,7 +20,7 @@ import { buildReport, formatReportMarkdown, formatBranchReportMarkdown, postRepo
 /**
  * Resolve log directory path
  */
-function resolveLogDir(customPath) {
+export function resolveLogDir(customPath) {
     if (customPath) {
         return customPath.replace("~", os.homedir());
     }

package/dist/src/lib/merge-check/report.js

@@ -5,6 +5,7 @@
  * batch-level verdict. Optionally posts to GitHub as PR comment.
  */
 import { spawnSync } from "child_process";
+import { resolveFailureReason, toCommandResult } from "./command-result.js";
 /**
  * Compute per-issue verdicts from check results
  */
@@ -232,7 +233,10 @@ export function postReportToGitHub(report) {
         const markdown = formatBranchReportMarkdown(report, branch.issueNumber);
         const result = spawnSync("gh", ["pr", "comment", String(branch.prNumber), "--body", markdown], { stdio: "pipe", encoding: "utf-8" });
         if (result.status !== 0) {
-            console.error(`Failed to post comment on PR #${branch.prNumber}: ${result.stderr}`);
+            // Same never-empty reason resolution as the combined-branch test (#803):
+            // `gh` usually writes to stderr, but a killed or unspawnable process
+            // leaves it empty, which would print a message with nothing after it.
+            console.error(`Failed to post comment on PR #${branch.prNumber}: ${resolveFailureReason(toCommandResult(result))}`);
         }
     }
 }

package/dist/src/lib/merge-check/types.d.ts

@@ -171,6 +171,15 @@ export interface MergeCommandOptions {
     json?: boolean;
     /** Enable verbose output */
     verbose?: boolean;
+    /**
+     * Watch mode (#818): poll each resolved PR's CI rollup until every check is
+     * terminal, then run the normal merge-check report. Never merges.
+     */
+    watch?: boolean;
+    /** Watch poll interval in seconds (default 30). Only used with `watch`. */
+    interval?: number;
+    /** Watch give-up timeout in seconds (default 1800). Only used with `watch`. */
+    timeout?: number;
 }
 /**
  * Configuration for paired directories (template mirroring)