@webpieces/pr-gate 0.4.497 → 0.4.499

package/src/scripts/workflow/diff-basis.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiffBasisResolver = exports.DiffBasis = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const inversify_1 = require("inversify");
+const git_findForkPoint_1 = require("./git-findForkPoint");
+/**
+ * The ONE resolved answer to "what exactly is this branch's diff, and what command reproduces it?"
+ *
+ * It exists because the two halves of the review flow used to disagree. `ChecklistScanner` computes the
+ * changed-FILE set by calling `getChangedFiles` with NO head — base→WORKING TREE, unioning in untracked
+ * files — while `ChecklistInstructionsService` printed `git diff <base> HEAD -- <file>` to every
+ * reviewer. On a dirty tree those are different ranges, and the printed command returns NOTHING: a reviewer
+ * is handed a file list and a command that shows it nothing. That is not hypothetical — a reviewer subagent
+ * on monorepo-nx2 ran the printed command, got empty output, and had to guess its way to `git diff HEAD`.
+ *
+ * So the command is DERIVED from the same basis the file set is, and no caller writes one by hand.
+ *
+ * Data-only (per CLAUDE.md).
+ */
+class DiffBasis {
+    // The 3-point fork point of main. '' when neither origin/main nor main resolves.
+    base;
+    // The REAL sha, never the literal string 'HEAD'. A recorded 'HEAD' is worthless the moment a commit
+    // lands on top of it, and the stage receipt has to compare shas to know the tree moved under a review.
+    headSha;
+    // True when the diff includes staged/unstaged/untracked work, i.e. the range is base→working tree.
+    dirty;
+    // Exactly WHICH paths make it dirty, so a message can name them instead of asserting dirtiness.
+    dirtyFiles;
+    // The command that reproduces the WHOLE diff. Correct for both clean and dirty; see DiffBasisResolver.
+    diffCommand;
+    // The same command with a `-- <file>` tail — what every reviewer instruction prints.
+    fileDiffCommand;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(base = '', headSha = '', dirty = false, dirtyFiles = [], diffCommand = '', fileDiffCommand = '') {
+        this.base = base;
+        this.headSha = headSha;
+        this.dirty = dirty;
+        this.dirtyFiles = dirtyFiles;
+        this.diffCommand = diffCommand;
+        this.fileDiffCommand = fileDiffCommand;
+    }
+    // True when there is no usable base — callers must SAY so rather than print a command that cannot work.
+    get unresolved() {
+        return this.base.trim() === '';
+    }
+}
+exports.DiffBasis = DiffBasis;
+/**
+ * Resolves {@link DiffBasis} for a repo. Injects {@link ForkPoint} so the base is the SAME fork-point
+ * computation the checklist matching uses — never `DiffScope.resolveBase`, which overlays NX_BASE/NX_HEAD
+ * from the environment and would make review coverage depend on an env var.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+let DiffBasisResolver = class DiffBasisResolver {
+    forkPoint;
+    constructor(forkPoint) {
+        this.forkPoint = forkPoint;
+    }
+    /**
+     * Resolve the basis. The command shape is the whole point:
+     *
+     *   clean tree → `git diff <base> <headSha>`   (commit-to-commit; reproducible later, unlike 'HEAD')
+     *   dirty tree → `git diff <base>`             (NO head — this is what includes the working tree)
+     *
+     * Omitting the head on a dirty tree is not a shortcut, it is the only form that shows uncommitted work,
+     * and supplying `HEAD` there is precisely the bug this class exists to make unrepresentable.
+     */
+    resolve(repoRoot) {
+        const base = this.forkPoint.resolveForkPoint(repoRoot);
+        const headSha = this.gitOut(repoRoot, ['rev-parse', 'HEAD']);
+        const dirtyFiles = this.dirtyPaths(repoRoot);
+        const dirty = dirtyFiles.length > 0;
+        if (base === '')
+            return new DiffBasis('', headSha, dirty, dirtyFiles);
+        const whole = dirty ? `git diff ${base}` : `git diff ${base} ${headSha}`;
+        return new DiffBasis(base, headSha, dirty, dirtyFiles, whole, `${whole} -- <file>`);
+    }
+    /**
+     * Every path that makes the tree dirty: tracked modifications/staged changes PLUS untracked files.
+     * Untracked must be included — `git status --porcelain` reports them as `??`, and they are exactly the
+     * files a brand-new migration or terraform rule arrives as, which is when a checklist most wants to fire.
+     */
+    dirtyPaths(repoRoot) {
+        const out = this.gitOut(repoRoot, ['status', '--porcelain', '--untracked-files=all']);
+        if (out === '')
+            return [];
+        const paths = [];
+        for (const line of out.split('\n')) {
+            // Porcelain v1: 2 status chars, a space, then the path. A rename reads `R  old -> new`; the new
+            // name is the one that exists on disk, so it is the one a reviewer can open.
+            const raw = line.slice(3).trim();
+            if (raw === '')
+                continue;
+            const arrow = raw.indexOf(' -> ');
+            paths.push(arrow === -1 ? raw : raw.slice(arrow + 4));
+        }
+        return paths;
+    }
+    gitOut(repoRoot, args) {
+        const result = (0, child_process_1.spawnSync)('git', args, { cwd: repoRoot, encoding: 'utf8' });
+        return result.status === 0 ? (result.stdout ?? '').trim() : '';
+    }
+};
+exports.DiffBasisResolver = DiffBasisResolver;
+exports.DiffBasisResolver = DiffBasisResolver = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [git_findForkPoint_1.ForkPoint])
+], DiffBasisResolver);
+//# sourceMappingURL=diff-basis.js.map

package/src/scripts/workflow/diff-basis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-basis.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/diff-basis.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { ForkPoint } from './git-findForkPoint';\n\n/**\n * The ONE resolved answer to \"what exactly is this branch's diff, and what command reproduces it?\"\n *\n * It exists because the two halves of the review flow used to disagree. `ChecklistScanner` computes the\n * changed-FILE set by calling `getChangedFiles` with NO head — base→WORKING TREE, unioning in untracked\n * files — while `ChecklistInstructionsService` printed `git diff <base> HEAD -- <file>` to every\n * reviewer. On a dirty tree those are different ranges, and the printed command returns NOTHING: a reviewer\n * is handed a file list and a command that shows it nothing. That is not hypothetical — a reviewer subagent\n * on monorepo-nx2 ran the printed command, got empty output, and had to guess its way to `git diff HEAD`.\n *\n * So the command is DERIVED from the same basis the file set is, and no caller writes one by hand.\n *\n * Data-only (per CLAUDE.md).\n */\nexport class DiffBasis {\n    // The 3-point fork point of main. '' when neither origin/main nor main resolves.\n    base: string;\n    // The REAL sha, never the literal string 'HEAD'. A recorded 'HEAD' is worthless the moment a commit\n    // lands on top of it, and the stage receipt has to compare shas to know the tree moved under a review.\n    headSha: string;\n    // True when the diff includes staged/unstaged/untracked work, i.e. the range is base→working tree.\n    dirty: boolean;\n    // Exactly WHICH paths make it dirty, so a message can name them instead of asserting dirtiness.\n    dirtyFiles: string[];\n    // The command that reproduces the WHOLE diff. Correct for both clean and dirty; see DiffBasisResolver.\n    diffCommand: string;\n    // The same command with a `-- <file>` tail — what every reviewer instruction prints.\n    fileDiffCommand: string;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(base = '', headSha = '', dirty = false, dirtyFiles: string[] = [], diffCommand = '', fileDiffCommand = '') {\n        this.base = base;\n        this.headSha = headSha;\n        this.dirty = dirty;\n        this.dirtyFiles = dirtyFiles;\n        this.diffCommand = diffCommand;\n        this.fileDiffCommand = fileDiffCommand;\n    }\n\n    // True when there is no usable base — callers must SAY so rather than print a command that cannot work.\n    get unresolved(): boolean {\n        return this.base.trim() === '';\n    }\n}\n\n/**\n * Resolves {@link DiffBasis} for a repo. Injects {@link ForkPoint} so the base is the SAME fork-point\n * computation the checklist matching uses — never `DiffScope.resolveBase`, which overlays NX_BASE/NX_HEAD\n * from the environment and would make review coverage depend on an env var.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class DiffBasisResolver {\n    constructor(private readonly forkPoint: ForkPoint) {}\n\n    /**\n     * Resolve the basis. The command shape is the whole point:\n     *\n     *   clean tree → `git diff <base> <headSha>`   (commit-to-commit; reproducible later, unlike 'HEAD')\n     *   dirty tree → `git diff <base>`             (NO head — this is what includes the working tree)\n     *\n     * Omitting the head on a dirty tree is not a shortcut, it is the only form that shows uncommitted work,\n     * and supplying `HEAD` there is precisely the bug this class exists to make unrepresentable.\n     */\n    resolve(repoRoot: string): DiffBasis {\n        const base = this.forkPoint.resolveForkPoint(repoRoot);\n        const headSha = this.gitOut(repoRoot, ['rev-parse', 'HEAD']);\n        const dirtyFiles = this.dirtyPaths(repoRoot);\n        const dirty = dirtyFiles.length > 0;\n        if (base === '') return new DiffBasis('', headSha, dirty, dirtyFiles);\n        const whole = dirty ? `git diff ${base}` : `git diff ${base} ${headSha}`;\n        return new DiffBasis(base, headSha, dirty, dirtyFiles, whole, `${whole} -- <file>`);\n    }\n\n    /**\n     * Every path that makes the tree dirty: tracked modifications/staged changes PLUS untracked files.\n     * Untracked must be included — `git status --porcelain` reports them as `??`, and they are exactly the\n     * files a brand-new migration or terraform rule arrives as, which is when a checklist most wants to fire.\n     */\n    private dirtyPaths(repoRoot: string): string[] {\n        const out = this.gitOut(repoRoot, ['status', '--porcelain', '--untracked-files=all']);\n        if (out === '') return [];\n        const paths: string[] = [];\n        for (const line of out.split('\\n')) {\n            // Porcelain v1: 2 status chars, a space, then the path. A rename reads `R  old -> new`; the new\n            // name is the one that exists on disk, so it is the one a reviewer can open.\n            const raw = line.slice(3).trim();\n            if (raw === '') continue;\n            const arrow = raw.indexOf(' -> ');\n            paths.push(arrow === -1 ? raw : raw.slice(arrow + 4));\n        }\n        return paths;\n    }\n\n    private gitOut(repoRoot: string, args: string[]): string {\n        const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8' });\n        return result.status === 0 ? (result.stdout ?? '').trim() : '';\n    }\n}\n"]}

package/src/scripts/workflow/diff-materializer.d.ts

@@ -0,0 +1,85 @@
+import { ReviewJsonService } from '@webpieces/rules-config';
+import { DiffBasis } from './diff-basis';
+export declare const FILE_DIFF_MAX_BYTES: number;
+export declare const ALL_DIFF_MAX_BYTES: number;
+/** One materialized file's diff. Data-only (per CLAUDE.md). */
+export declare class DiffManifestEntry {
+    file: string;
+    diffFile: string;
+    status: string;
+    bytes: number;
+    truncated: boolean;
+    constructor(file: string, diffFile: string, status: string, bytes: number, truncated?: boolean);
+}
+/** The authoritative map from a mangled `.diff` name back to its real path, plus what was dropped. */
+export declare class DiffManifest {
+    base: string;
+    head: string;
+    dirty: boolean;
+    diffCommand: string;
+    entries: DiffManifestEntry[];
+    excluded: string[];
+    omittedFromAllDiff: string[];
+    constructor(base: string, head: string, dirty: boolean, diffCommand: string, entries?: DiffManifestEntry[], excluded?: string[], omittedFromAllDiff?: string[]);
+}
+/**
+ * Extracts this branch's diff ONCE, to disk, so a reviewer subagent reads it instead of reconstructing it.
+ *
+ * The motivating measurement: a reviewer on monorepo-nx2 spent 14 of its 26 tool calls on context
+ * archaeology, and the very first `git diff` it was told to run returned nothing (see {@link DiffBasis}).
+ * Handing it a file it can simply open removes both failure modes — the empty range and the shell-out.
+ *
+ * Cost discipline: **two git invocations total, regardless of file count.** One `git diff` for everything,
+ * split on `diff --git` headers, plus one `ls-files --others` for untracked files. A per-file `git diff`
+ * loop would be N spawns for the same bytes.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+export declare class DiffMaterializer {
+    private readonly reviewJsonService;
+    constructor(reviewJsonService: ReviewJsonService);
+    /** The dir this writes into: `.webpieces/pr-review/<feature>/diff`. */
+    diffDirFor(repoRoot: string, featureName: string): string;
+    /**
+     * Write `diff/ALL.diff`, `diff/files/*.diff` and `diff/manifest.json`. Returns the manifest.
+     *
+     * `changedFiles` is the set the CHECKLIST MATCHING used — passed in rather than recomputed, so the diff
+     * a reviewer reads covers exactly the files its checklist matched on. Recomputing here is how the two
+     * would drift apart again.
+     */
+    materialize(repoRoot: string, featureName: string, basis: DiffBasis, changedFiles: readonly string[], excludeGlobs: readonly string[]): DiffManifest;
+    /**
+     * ONE `git diff` for the whole branch, split into per-file patches keyed by repo-relative path.
+     * Untracked files never appear in `git diff`, so they are synthesized as all-added patches — the same
+     * treatment DiffScope.getFileDiff already gives them, kept consistent so a reviewer sees one format.
+     */
+    private captureByFile;
+    /**
+     * The b-side path out of a `diff --git a/x b/x` header. The b-side is the right one: for a rename it is
+     * the name that exists on disk, which is the file a reviewer can actually open.
+     */
+    private pathFromHeader;
+    private untrackedFiles;
+    private syntheticAddedDiff;
+    /** Write ONE file's diff, recording it (or its exclusion) in the manifest. Never drops a file silently. */
+    private writeOne;
+    private statusOf;
+    /**
+     * Truncate to the cap WITH a footer. Never silently: a truncated diff that looks whole is how a reviewer
+     * reports "reviewed" on a tenth of a change — the same trap `formatFileList` states its dropped count for.
+     */
+    private capped;
+    /**
+     * `ALL.diff` — the single Read that answers "what changed on this branch?". Files are appended smallest
+     * first so a cap drops the fewest of them, and anything dropped is named in a footer AND in the manifest.
+     */
+    private writeAllDiff;
+    /**
+     * `a/b/c.ts` → `a__b__c.ts.diff`, reusing the SAME `/`→`__` convention MergeState.perFileContextDir
+     * already uses for 3-point merge context. One mangling scheme in the repo, not two. A real `__` in a
+     * path can collide, so collisions get a numeric suffix and manifest.json stays authoritative.
+     */
+    private safeName;
+    private writeManifest;
+    private gitOut;
+}

package/src/scripts/workflow/diff-materializer.js

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiffMaterializer = exports.DiffManifest = exports.DiffManifestEntry = exports.ALL_DIFF_MAX_BYTES = exports.FILE_DIFF_MAX_BYTES = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+// Per-file cap. Over it, the file's diff is truncated WITH a footer naming the command that gets the rest.
+exports.FILE_DIFF_MAX_BYTES = 256 * 1024;
+// Cap for the combined ALL.diff. Over it, whole files are omitted — again, named, never silently.
+exports.ALL_DIFF_MAX_BYTES = 2 * 1024 * 1024;
+/** One materialized file's diff. Data-only (per CLAUDE.md). */
+class DiffManifestEntry {
+    file; // repo-relative source path
+    diffFile; // repo-relative path of the .diff under diff/files/
+    status; // 'M' | 'A' | 'D' | 'U' (untracked) | 'X' (excluded by config)
+    bytes;
+    truncated;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(file, diffFile, status, bytes, truncated = false) {
+        this.file = file;
+        this.diffFile = diffFile;
+        this.status = status;
+        this.bytes = bytes;
+        this.truncated = truncated;
+    }
+}
+exports.DiffManifestEntry = DiffManifestEntry;
+/** The authoritative map from a mangled `.diff` name back to its real path, plus what was dropped. */
+class DiffManifest {
+    base;
+    head;
+    dirty;
+    diffCommand;
+    entries;
+    excluded; // matched pr-gate.reviewDiffExclude — present, stubbed, NOT materialized
+    omittedFromAllDiff; // too big for ALL.diff; their per-file .diff still exists
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(base, head, dirty, diffCommand, entries = [], excluded = [], omittedFromAllDiff = []) {
+        this.base = base;
+        this.head = head;
+        this.dirty = dirty;
+        this.diffCommand = diffCommand;
+        this.entries = entries;
+        this.excluded = excluded;
+        this.omittedFromAllDiff = omittedFromAllDiff;
+    }
+}
+exports.DiffManifest = DiffManifest;
+/**
+ * Extracts this branch's diff ONCE, to disk, so a reviewer subagent reads it instead of reconstructing it.
+ *
+ * The motivating measurement: a reviewer on monorepo-nx2 spent 14 of its 26 tool calls on context
+ * archaeology, and the very first `git diff` it was told to run returned nothing (see {@link DiffBasis}).
+ * Handing it a file it can simply open removes both failure modes — the empty range and the shell-out.
+ *
+ * Cost discipline: **two git invocations total, regardless of file count.** One `git diff` for everything,
+ * split on `diff --git` headers, plus one `ls-files --others` for untracked files. A per-file `git diff`
+ * loop would be N spawns for the same bytes.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.
+ */
+let DiffMaterializer = class DiffMaterializer {
+    reviewJsonService;
+    constructor(reviewJsonService) {
+        this.reviewJsonService = reviewJsonService;
+    }
+    /** The dir this writes into: `.webpieces/pr-review/<feature>/diff`. */
+    diffDirFor(repoRoot, featureName) {
+        return path.join(this.reviewJsonService.prDirFor(repoRoot, featureName), 'diff');
+    }
+    /**
+     * Write `diff/ALL.diff`, `diff/files/*.diff` and `diff/manifest.json`. Returns the manifest.
+     *
+     * `changedFiles` is the set the CHECKLIST MATCHING used — passed in rather than recomputed, so the diff
+     * a reviewer reads covers exactly the files its checklist matched on. Recomputing here is how the two
+     * would drift apart again.
+     */
+    materialize(repoRoot, featureName, basis, changedFiles, excludeGlobs) {
+        const dir = this.diffDirFor(repoRoot, featureName);
+        const filesDir = path.join(dir, 'files');
+        fs.rmSync(dir, { recursive: true, force: true }); // a stale diff read as current is worse than none
+        fs.mkdirSync(filesDir, { recursive: true });
+        const manifest = new DiffManifest(basis.base, basis.headSha, basis.dirty, basis.diffCommand);
+        if (basis.unresolved)
+            return this.writeManifest(dir, manifest);
+        const byFile = this.captureByFile(repoRoot, basis);
+        const used = new Set();
+        for (const file of [...changedFiles].sort()) {
+            this.writeOne(repoRoot, filesDir, file, byFile, used, excludeGlobs, manifest);
+        }
+        this.writeAllDiff(dir, filesDir, manifest);
+        return this.writeManifest(dir, manifest);
+    }
+    /**
+     * ONE `git diff` for the whole branch, split into per-file patches keyed by repo-relative path.
+     * Untracked files never appear in `git diff`, so they are synthesized as all-added patches — the same
+     * treatment DiffScope.getFileDiff already gives them, kept consistent so a reviewer sees one format.
+     */
+    captureByFile(repoRoot, basis) {
+        const args = basis.dirty ? ['diff', basis.base] : ['diff', basis.base, basis.headSha];
+        const out = this.gitOut(repoRoot, args);
+        const byFile = new Map();
+        // Split BEFORE each `diff --git` header while keeping the header on its chunk.
+        for (const chunk of out.split(/\n(?=diff --git )/)) {
+            if (!chunk.startsWith('diff --git '))
+                continue;
+            const file = this.pathFromHeader(chunk);
+            if (file !== '')
+                byFile.set(file, chunk.endsWith('\n') ? chunk : `${chunk}\n`);
+        }
+        for (const file of this.untrackedFiles(repoRoot, basis)) {
+            if (!byFile.has(file))
+                byFile.set(file, this.syntheticAddedDiff(repoRoot, file));
+        }
+        return byFile;
+    }
+    /**
+     * The b-side path out of a `diff --git a/x b/x` header. The b-side is the right one: for a rename it is
+     * the name that exists on disk, which is the file a reviewer can actually open.
+     */
+    pathFromHeader(chunk) {
+        const header = chunk.slice(0, chunk.indexOf('\n') === -1 ? chunk.length : chunk.indexOf('\n'));
+        const match = header.match(/^diff --git a\/(.+) b\/(.+)$/);
+        return match ? match[2] : '';
+    }
+    untrackedFiles(repoRoot, basis) {
+        if (!basis.dirty)
+            return [];
+        const out = this.gitOut(repoRoot, ['ls-files', '--others', '--exclude-standard']);
+        return out === '' ? [] : out.split('\n').filter((f) => f.trim() !== '');
+    }
+    syntheticAddedDiff(repoRoot, file) {
+        const abs = path.join(repoRoot, file);
+        if (!fs.existsSync(abs))
+            return '';
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable/binary untracked file yields a note, never a crash
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const body = fs.readFileSync(abs, 'utf8').split('\n').map((l) => `+${l}`).join('\n');
+            return `diff --git a/${file} b/${file}\nnew file (untracked)\n--- /dev/null\n+++ b/${file}\n${body}\n`;
+        }
+        catch (err) {
+            const error = (0, rules_config_1.toError)(err);
+            void error; // a binary/unreadable untracked file gets a NOTE, never a crash
+            return `diff --git a/${file} b/${file}\nnew file (untracked, unreadable as text)\n`;
+        }
+    }
+    /** Write ONE file's diff, recording it (or its exclusion) in the manifest. Never drops a file silently. */
+    // eslint-disable-next-line @typescript-eslint/max-params
+    writeOne(repoRoot, filesDir, file, byFile, used, excludeGlobs, manifest) {
+        const name = this.safeName(file, used);
+        const abs = path.join(filesDir, name);
+        const rel = path.relative(repoRoot, abs);
+        // Excluded files stay in the manifest and keep a stub. Dropping them entirely would read as "this
+        // file did not change"; they are noise to READ, not facts to hide — and they still match checklists.
+        if (excludeGlobs.length > 0 && (0, rules_config_1.isPathExcluded)(file, [...excludeGlobs])) {
+            const stub = `[excluded from materialization by pr-gate.reviewDiffExclude]\nIf you need it:  git diff ${manifest.base} -- ${file}\n`;
+            fs.writeFileSync(abs, stub);
+            manifest.excluded.push(file);
+            manifest.entries.push(new DiffManifestEntry(file, rel, 'X', stub.length));
+            return;
+        }
+        const raw = byFile.get(file) ?? '';
+        const status = this.statusOf(file, raw, repoRoot);
+        const body = this.capped(raw, file, manifest.base);
+        fs.writeFileSync(abs, body);
+        manifest.entries.push(new DiffManifestEntry(file, rel, status, body.length, body !== raw));
+    }
+    statusOf(file, raw, repoRoot) {
+        if (raw.includes('\nnew file (untracked)'))
+            return 'U';
+        if (raw.includes('\nnew file mode '))
+            return 'A';
+        if (raw.includes('\ndeleted file mode '))
+            return 'D';
+        return fs.existsSync(path.join(repoRoot, file)) ? 'M' : 'D';
+    }
+    /**
+     * Truncate to the cap WITH a footer. Never silently: a truncated diff that looks whole is how a reviewer
+     * reports "reviewed" on a tenth of a change — the same trap `formatFileList` states its dropped count for.
+     */
+    capped(raw, file, base) {
+        if (raw.length <= exports.FILE_DIFF_MAX_BYTES)
+            return raw;
+        return `${raw.slice(0, exports.FILE_DIFF_MAX_BYTES)}\n` +
+            `\n… TRUNCATED at ${exports.FILE_DIFF_MAX_BYTES} bytes (full diff is ${raw.length} bytes).\n` +
+            `   Read the rest with:  git diff ${base} -- ${file}\n`;
+    }
+    /**
+     * `ALL.diff` — the single Read that answers "what changed on this branch?". Files are appended smallest
+     * first so a cap drops the fewest of them, and anything dropped is named in a footer AND in the manifest.
+     */
+    writeAllDiff(dir, filesDir, manifest) {
+        const ordered = [...manifest.entries].sort((a, b) => a.bytes - b.bytes);
+        const parts = [];
+        let total = 0;
+        for (const entry of ordered) {
+            const body = fs.readFileSync(path.join(filesDir, path.basename(entry.diffFile)), 'utf8');
+            if (total + body.length > exports.ALL_DIFF_MAX_BYTES) {
+                manifest.omittedFromAllDiff.push(entry.file);
+                continue;
+            }
+            parts.push(body);
+            total += body.length;
+        }
+        let out = parts.join('\n');
+        if (manifest.omittedFromAllDiff.length > 0) {
+            out += `\n\n… ${manifest.omittedFromAllDiff.length} file(s) OMITTED from this combined view (it hit the ` +
+                `${exports.ALL_DIFF_MAX_BYTES}-byte cap). Each still has its own diff under files/ — see manifest.json:\n` +
+                manifest.omittedFromAllDiff.map((f) => `   ${f}`).join('\n') + '\n';
+        }
+        fs.writeFileSync(path.join(dir, 'ALL.diff'), out);
+    }
+    /**
+     * `a/b/c.ts` → `a__b__c.ts.diff`, reusing the SAME `/`→`__` convention MergeState.perFileContextDir
+     * already uses for 3-point merge context. One mangling scheme in the repo, not two. A real `__` in a
+     * path can collide, so collisions get a numeric suffix and manifest.json stays authoritative.
+     */
+    safeName(file, used) {
+        const flat = `${file.replace(/\//g, '__')}.diff`;
+        if (!used.has(flat)) {
+            used.add(flat);
+            return flat;
+        }
+        for (let n = 2;; n++) {
+            const candidate = `${file.replace(/\//g, '__')}-${n}.diff`;
+            if (!used.has(candidate)) {
+                used.add(candidate);
+                return candidate;
+            }
+        }
+    }
+    writeManifest(dir, manifest) {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+        return manifest;
+    }
+    gitOut(repoRoot, args) {
+        // maxBuffer: a monorepo diff routinely exceeds node's 1MB default, and the failure mode is a
+        // truncated capture that looks like a complete one.
+        const result = (0, child_process_1.spawnSync)('git', args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+        return result.status === 0 ? (result.stdout ?? '') : '';
+    }
+};
+exports.DiffMaterializer = DiffMaterializer;
+exports.DiffMaterializer = DiffMaterializer = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [rules_config_1.ReviewJsonService])
+], DiffMaterializer);
+//# sourceMappingURL=diff-materializer.js.map

package/src/scripts/workflow/diff-materializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-materializer.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/diff-materializer.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { isPathExcluded, ReviewJsonService, toError } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { DiffBasis } from './diff-basis';\n\n// Per-file cap. Over it, the file's diff is truncated WITH a footer naming the command that gets the rest.\nexport const FILE_DIFF_MAX_BYTES = 256 * 1024;\n// Cap for the combined ALL.diff. Over it, whole files are omitted — again, named, never silently.\nexport const ALL_DIFF_MAX_BYTES = 2 * 1024 * 1024;\n\n/** One materialized file's diff. Data-only (per CLAUDE.md). */\nexport class DiffManifestEntry {\n    file: string;       // repo-relative source path\n    diffFile: string;   // repo-relative path of the .diff under diff/files/\n    status: string;     // 'M' | 'A' | 'D' | 'U' (untracked) | 'X' (excluded by config)\n    bytes: number;\n    truncated: boolean;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(file: string, diffFile: string, status: string, bytes: number, truncated = false) {\n        this.file = file;\n        this.diffFile = diffFile;\n        this.status = status;\n        this.bytes = bytes;\n        this.truncated = truncated;\n    }\n}\n\n/** The authoritative map from a mangled `.diff` name back to its real path, plus what was dropped. */\nexport class DiffManifest {\n    base: string;\n    head: string;\n    dirty: boolean;\n    diffCommand: string;\n    entries: DiffManifestEntry[];\n    excluded: string[];          // matched pr-gate.reviewDiffExclude — present, stubbed, NOT materialized\n    omittedFromAllDiff: string[]; // too big for ALL.diff; their per-file .diff still exists\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        base: string, head: string, dirty: boolean, diffCommand: string,\n        entries: DiffManifestEntry[] = [], excluded: string[] = [], omittedFromAllDiff: string[] = [],\n    ) {\n        this.base = base;\n        this.head = head;\n        this.dirty = dirty;\n        this.diffCommand = diffCommand;\n        this.entries = entries;\n        this.excluded = excluded;\n        this.omittedFromAllDiff = omittedFromAllDiff;\n    }\n}\n\n/**\n * Extracts this branch's diff ONCE, to disk, so a reviewer subagent reads it instead of reconstructing it.\n *\n * The motivating measurement: a reviewer on monorepo-nx2 spent 14 of its 26 tool calls on context\n * archaeology, and the very first `git diff` it was told to run returned nothing (see {@link DiffBasis}).\n * Handing it a file it can simply open removes both failure modes — the empty range and the shell-out.\n *\n * Cost discipline: **two git invocations total, regardless of file count.** One `git diff` for everything,\n * split on `diff --git` headers, plus one `ls-files --others` for untracked files. A per-file `git diff`\n * loop would be N spawns for the same bytes.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type and drawn in the DI design.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class DiffMaterializer {\n    constructor(private readonly reviewJsonService: ReviewJsonService) {}\n\n    /** The dir this writes into: `.webpieces/pr-review/<feature>/diff`. */\n    diffDirFor(repoRoot: string, featureName: string): string {\n        return path.join(this.reviewJsonService.prDirFor(repoRoot, featureName), 'diff');\n    }\n\n    /**\n     * Write `diff/ALL.diff`, `diff/files/*.diff` and `diff/manifest.json`. Returns the manifest.\n     *\n     * `changedFiles` is the set the CHECKLIST MATCHING used — passed in rather than recomputed, so the diff\n     * a reviewer reads covers exactly the files its checklist matched on. Recomputing here is how the two\n     * would drift apart again.\n     */\n    materialize(repoRoot: string, featureName: string, basis: DiffBasis, changedFiles: readonly string[], excludeGlobs: readonly string[]): DiffManifest {\n        const dir = this.diffDirFor(repoRoot, featureName);\n        const filesDir = path.join(dir, 'files');\n        fs.rmSync(dir, { recursive: true, force: true }); // a stale diff read as current is worse than none\n        fs.mkdirSync(filesDir, { recursive: true });\n        const manifest = new DiffManifest(basis.base, basis.headSha, basis.dirty, basis.diffCommand);\n        if (basis.unresolved) return this.writeManifest(dir, manifest);\n        const byFile = this.captureByFile(repoRoot, basis);\n        const used = new Set<string>();\n        for (const file of [...changedFiles].sort()) {\n            this.writeOne(repoRoot, filesDir, file, byFile, used, excludeGlobs, manifest);\n        }\n        this.writeAllDiff(dir, filesDir, manifest);\n        return this.writeManifest(dir, manifest);\n    }\n\n    /**\n     * ONE `git diff` for the whole branch, split into per-file patches keyed by repo-relative path.\n     * Untracked files never appear in `git diff`, so they are synthesized as all-added patches — the same\n     * treatment DiffScope.getFileDiff already gives them, kept consistent so a reviewer sees one format.\n     */\n    private captureByFile(repoRoot: string, basis: DiffBasis): Map<string, string> {\n        const args = basis.dirty ? ['diff', basis.base] : ['diff', basis.base, basis.headSha];\n        const out = this.gitOut(repoRoot, args);\n        const byFile = new Map<string, string>();\n        // Split BEFORE each `diff --git` header while keeping the header on its chunk.\n        for (const chunk of out.split(/\\n(?=diff --git )/)) {\n            if (!chunk.startsWith('diff --git ')) continue;\n            const file = this.pathFromHeader(chunk);\n            if (file !== '') byFile.set(file, chunk.endsWith('\\n') ? chunk : `${chunk}\\n`);\n        }\n        for (const file of this.untrackedFiles(repoRoot, basis)) {\n            if (!byFile.has(file)) byFile.set(file, this.syntheticAddedDiff(repoRoot, file));\n        }\n        return byFile;\n    }\n\n    /**\n     * The b-side path out of a `diff --git a/x b/x` header. The b-side is the right one: for a rename it is\n     * the name that exists on disk, which is the file a reviewer can actually open.\n     */\n    private pathFromHeader(chunk: string): string {\n        const header = chunk.slice(0, chunk.indexOf('\\n') === -1 ? chunk.length : chunk.indexOf('\\n'));\n        const match = header.match(/^diff --git a\\/(.+) b\\/(.+)$/);\n        return match ? match[2] : '';\n    }\n\n    private untrackedFiles(repoRoot: string, basis: DiffBasis): string[] {\n        if (!basis.dirty) return [];\n        const out = this.gitOut(repoRoot, ['ls-files', '--others', '--exclude-standard']);\n        return out === '' ? [] : out.split('\\n').filter((f: string): boolean => f.trim() !== '');\n    }\n\n    private syntheticAddedDiff(repoRoot: string, file: string): string {\n        const abs = path.join(repoRoot, file);\n        if (!fs.existsSync(abs)) return '';\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable/binary untracked file yields a note, never a crash\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const body = fs.readFileSync(abs, 'utf8').split('\\n').map((l: string): string => `+${l}`).join('\\n');\n            return `diff --git a/${file} b/${file}\\nnew file (untracked)\\n--- /dev/null\\n+++ b/${file}\\n${body}\\n`;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error; // a binary/unreadable untracked file gets a NOTE, never a crash\n            return `diff --git a/${file} b/${file}\\nnew file (untracked, unreadable as text)\\n`;\n        }\n    }\n\n    /** Write ONE file's diff, recording it (or its exclusion) in the manifest. Never drops a file silently. */\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private writeOne(\n        repoRoot: string, filesDir: string, file: string, byFile: Map<string, string>,\n        used: Set<string>, excludeGlobs: readonly string[], manifest: DiffManifest,\n    ): void {\n        const name = this.safeName(file, used);\n        const abs = path.join(filesDir, name);\n        const rel = path.relative(repoRoot, abs);\n        // Excluded files stay in the manifest and keep a stub. Dropping them entirely would read as \"this\n        // file did not change\"; they are noise to READ, not facts to hide — and they still match checklists.\n        if (excludeGlobs.length > 0 && isPathExcluded(file, [...excludeGlobs])) {\n            const stub = `[excluded from materialization by pr-gate.reviewDiffExclude]\\nIf you need it:  git diff ${manifest.base} -- ${file}\\n`;\n            fs.writeFileSync(abs, stub);\n            manifest.excluded.push(file);\n            manifest.entries.push(new DiffManifestEntry(file, rel, 'X', stub.length));\n            return;\n        }\n        const raw = byFile.get(file) ?? '';\n        const status = this.statusOf(file, raw, repoRoot);\n        const body = this.capped(raw, file, manifest.base);\n        fs.writeFileSync(abs, body);\n        manifest.entries.push(new DiffManifestEntry(file, rel, status, body.length, body !== raw));\n    }\n\n    private statusOf(file: string, raw: string, repoRoot: string): string {\n        if (raw.includes('\\nnew file (untracked)')) return 'U';\n        if (raw.includes('\\nnew file mode ')) return 'A';\n        if (raw.includes('\\ndeleted file mode ')) return 'D';\n        return fs.existsSync(path.join(repoRoot, file)) ? 'M' : 'D';\n    }\n\n    /**\n     * Truncate to the cap WITH a footer. Never silently: a truncated diff that looks whole is how a reviewer\n     * reports \"reviewed\" on a tenth of a change — the same trap `formatFileList` states its dropped count for.\n     */\n    private capped(raw: string, file: string, base: string): string {\n        if (raw.length <= FILE_DIFF_MAX_BYTES) return raw;\n        return `${raw.slice(0, FILE_DIFF_MAX_BYTES)}\\n` +\n            `\\n… TRUNCATED at ${FILE_DIFF_MAX_BYTES} bytes (full diff is ${raw.length} bytes).\\n` +\n            `   Read the rest with:  git diff ${base} -- ${file}\\n`;\n    }\n\n    /**\n     * `ALL.diff` — the single Read that answers \"what changed on this branch?\". Files are appended smallest\n     * first so a cap drops the fewest of them, and anything dropped is named in a footer AND in the manifest.\n     */\n    private writeAllDiff(dir: string, filesDir: string, manifest: DiffManifest): void {\n        const ordered = [...manifest.entries].sort((a: DiffManifestEntry, b: DiffManifestEntry): number => a.bytes - b.bytes);\n        const parts: string[] = [];\n        let total = 0;\n        for (const entry of ordered) {\n            const body = fs.readFileSync(path.join(filesDir, path.basename(entry.diffFile)), 'utf8');\n            if (total + body.length > ALL_DIFF_MAX_BYTES) {\n                manifest.omittedFromAllDiff.push(entry.file);\n                continue;\n            }\n            parts.push(body);\n            total += body.length;\n        }\n        let out = parts.join('\\n');\n        if (manifest.omittedFromAllDiff.length > 0) {\n            out += `\\n\\n… ${manifest.omittedFromAllDiff.length} file(s) OMITTED from this combined view (it hit the ` +\n                `${ALL_DIFF_MAX_BYTES}-byte cap). Each still has its own diff under files/ — see manifest.json:\\n` +\n                manifest.omittedFromAllDiff.map((f: string): string => `   ${f}`).join('\\n') + '\\n';\n        }\n        fs.writeFileSync(path.join(dir, 'ALL.diff'), out);\n    }\n\n    /**\n     * `a/b/c.ts` → `a__b__c.ts.diff`, reusing the SAME `/`→`__` convention MergeState.perFileContextDir\n     * already uses for 3-point merge context. One mangling scheme in the repo, not two. A real `__` in a\n     * path can collide, so collisions get a numeric suffix and manifest.json stays authoritative.\n     */\n    private safeName(file: string, used: Set<string>): string {\n        const flat = `${file.replace(/\\//g, '__')}.diff`;\n        if (!used.has(flat)) {\n            used.add(flat);\n            return flat;\n        }\n        for (let n = 2; ; n++) {\n            const candidate = `${file.replace(/\\//g, '__')}-${n}.diff`;\n            if (!used.has(candidate)) {\n                used.add(candidate);\n                return candidate;\n            }\n        }\n    }\n\n    private writeManifest(dir: string, manifest: DiffManifest): DiffManifest {\n        fs.mkdirSync(dir, { recursive: true });\n        fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\\n');\n        return manifest;\n    }\n\n    private gitOut(repoRoot: string, args: string[]): string {\n        // maxBuffer: a monorepo diff routinely exceeds node's 1MB default, and the failure mode is a\n        // truncated capture that looks like a complete one.\n        const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });\n        return result.status === 0 ? (result.stdout ?? '') : '';\n    }\n}\n"]}

package/src/scripts/workflow/git-findForkPoint.d.ts

@@ -19,7 +19,7 @@ export declare class ForkPoint {
      * and works offline. `findForkPoint` below still fetches, because the MERGE flow additionally needs
      * main's CURRENT head as hash point C, which genuinely does require a fetch.
      *
-     * Also writes no files and runs no merge-commit scan, so it cannot throw: `wp-checklist` must always
+     * Also writes no files and runs no merge-commit scan, so it cannot throw: `wp-review-upsert-pr` must always
      * succeed, and a raw merge-from-main is the merge flow's problem to report, not the checklist's.
      */
     resolveForkPoint(repoRoot: string): string;

package/src/scripts/workflow/git-findForkPoint.js

@@ -38,7 +38,7 @@ let ForkPoint = class ForkPoint {
      * and works offline. `findForkPoint` below still fetches, because the MERGE flow additionally needs
      * main's CURRENT head as hash point C, which genuinely does require a fetch.
      *
-     * Also writes no files and runs no merge-commit scan, so it cannot throw: `wp-checklist` must always
+     * Also writes no files and runs no merge-commit scan, so it cannot throw: `wp-review-upsert-pr` must always
      * succeed, and a raw merge-from-main is the merge flow's problem to report, not the checklist's.
      */
     resolveForkPoint(repoRoot) {

package/src/scripts/workflow/git-findForkPoint.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-findForkPoint.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-findForkPoint.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { prDirFor, CliExitError, RepoRootFinder } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from './git-readAiBranchName';\nimport { MergeState } from './merge-state';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/** Computes the 3-point fork point and guards against improper merges-from-main. */\n@injectable(bindingScopeValues.Singleton)\nexport class ForkPoint {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly aiBranchName: AiBranchName,\n        private readonly mergeState: MergeState,\n    ) {}\n\n    // Single source of truth for the per-feature dir fork-point output is written to — the SAME nested\n    // home the readers use (git-gatherInfo / merge-start read updatemain-hashes.json from mergeDirFor;\n    // the review flow reads from prDirFor). Routing the writer through these same helpers is what keeps\n    // them from diverging again — guarded by git-findForkPoint.spec.ts.\n    forkPointOutputDir(repoRoot: string, featureName: string, workflow: string): string {\n        return workflow === 'review' ? prDirFor(repoRoot, featureName) : this.mergeState.mergeDirFor(repoRoot, featureName);\n    }\n\n    /**\n     * The 3-point FORK POINT: where this branch diverged from main. `git merge-base origin/main HEAD`,\n     * falling back to a local `main`, and '' when neither ref resolves.\n     *\n     * Deliberately does NOT fetch. The fork point is ABSOLUTE — advancing main cannot move it, because\n     * merge-base is the most recent common ancestor and main's new commits are not on this branch. (Verified\n     * on this repo: main went f415456 → ba8f674 → 61432d6 while merge-base with one branch stayed f415456\n     * throughout.) So a caller that needs only the fork point — see ChecklistScanner — pays no network cost\n     * and works offline. `findForkPoint` below still fetches, because the MERGE flow additionally needs\n     * main's CURRENT head as hash point C, which genuinely does require a fetch.\n     *\n     * Also writes no files and runs no merge-commit scan, so it cannot throw: `wp-checklist` must always\n     * succeed, and a raw merge-from-main is the merge flow's problem to report, not the checklist's.\n     */\n    resolveForkPoint(repoRoot: string): string {\n        for (const ref of ['origin/main', 'main']) {\n            const result = spawnSync('git', ['merge-base', ref, 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });\n            const sha = (result.stdout ?? '').trim();\n            if (result.status === 0 && sha !== '') return sha;\n        }\n        return '';\n    }\n\n    async findForkPoint(workflow: string): Promise<void> {\n        if (workflow !== 'review' && workflow !== 'merge') {\n            throw new CliExitError(1,\n                'ERROR: Workflow argument required\\n' +\n                'Usage: git-findForkPoint <workflow>\\n' +\n                \"  workflow: 'review' or 'merge'\",\n            );\n        }\n\n        const featureName = this.aiBranchName.getFeatureName();\n        const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n\n        const outputDir = this.forkPointOutputDir(repoRoot, featureName, workflow);\n        const prefix = workflow === 'review' ? 'review-' : 'updatemain-';\n        fs.mkdirSync(outputDir, { recursive: true });\n\n        spawnSync('git', ['fetch', 'origin', 'main'], { stdio: 'ignore' });\n\n        const featureHead = execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();\n        const originMain = execSync('git rev-parse origin/main', { encoding: 'utf8' }).trim();\n\n        process.stderr.write('Finding fork point using git merge-base...\\n');\n\n        // ONE implementation of the fork-point computation, shared with ChecklistScanner. The fetch above is\n        // what this flow needs beyond it (hash point C = main's current head), not the fork point itself.\n        const forkPoint = this.resolveForkPoint(repoRoot);\n\n        if (!forkPoint) {\n            throw new CliExitError(1, 'ERROR: Could not find common ancestor with origin/main');\n        }\n\n        process.stderr.write(`✅ Fork point found: ${forkPoint.slice(0, 7)}\\n`);\n        process.stderr.write('Checking for improper merges from main...\\n');\n\n        const mergeCommitsResult = spawnSync('git', ['log', `${forkPoint}..HEAD`, '--merges', '--format=%H'], { encoding: 'utf8' });\n        const mergeCommitsRaw = (mergeCommitsResult.stdout ?? '').trim();\n        const mergeCommits = mergeCommitsRaw ? mergeCommitsRaw.split('\\n') : [];\n\n        if (mergeCommits.length > 0) {\n            this.checkMergeCommits(mergeCommits, outputDir, prefix, featureName, currentBranch);\n        } else {\n            process.stderr.write('✅ No merge commits found (clean history)\\n');\n        }\n\n        const hashesJson = JSON.stringify({\n            hashForkPoint: forkPoint,\n            hashFeatureHead: featureHead,\n            hashMainHead: originMain,\n            timestamp: new Date().toISOString(),\n        }, null, 2);\n\n        fs.writeFileSync(path.join(outputDir, `${prefix}hashes.json`), hashesJson + '\\n');\n        process.stderr.write(`✅ Hash points written to: ${outputDir}/${prefix}hashes.json\\n`);\n    }\n\n    private checkMergeCommits(mergeCommits: string[], outputDir: string, prefix: string, featureName: string, currentBranch: string): void {\n        process.stderr.write(`Found ${mergeCommits.length} merge commit(s) to check...\\n`);\n\n        for (const commit of mergeCommits) {\n            const parentsResult = spawnSync('git', ['rev-list', '--parents', '-n', '1', commit], { encoding: 'utf8' });\n            const parents = (parentsResult.stdout ?? '').trim().split(' ').slice(1);\n\n            for (const parent of parents) {\n                const ancestorCheck = spawnSync('git', ['merge-base', '--is-ancestor', parent, 'origin/main']);\n                const reverseCheck = spawnSync('git', ['merge-base', '--is-ancestor', 'origin/main', parent]);\n\n                if (ancestorCheck.status === 0 && reverseCheck.status === 0) {\n                    const errorJson = JSON.stringify({\n                        error: 'Merge from main detected',\n                        mergeCommit: commit,\n                        parentFromMain: parent,\n                        timestamp: new Date().toISOString(),\n                    }, null, 2);\n\n                    fs.writeFileSync(path.join(outputDir, `${prefix}forkpoint-error.json`), errorJson + '\\n');\n                    this.printMergeFromMainError(commit, parent, featureName, currentBranch);\n                    throw new CliExitError(1, '');\n                }\n            }\n        }\n        process.stderr.write('✅ No improper merges from main detected\\n');\n    }\n\n    private printMergeFromMainError(commit: string, parent: string, featureName: string, currentBranch: string): void {\n        process.stderr.write('\\n');\n        process.stderr.write(SEP);\n        process.stderr.write('❌ This branch merged main without the gated update (pnpm wp-start-update, or\\n');\n        process.stderr.write('   pnpm wp-start-upsert-pr when a PR is open)\\n');\n        process.stderr.write(SEP);\n        process.stderr.write('\\n');\n        process.stderr.write(`Merge commit detected: ${commit}\\n`);\n        process.stderr.write(`Parent from main:      ${parent}\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write('This prevents clean squash-merge. To recover, follow these steps:\\n');\n        process.stderr.write('\\n');\n        process.stderr.write('1. Fetch the latest main (works on the primary repo AND in a worktree):\\n');\n        process.stderr.write('   git fetch origin main\\n');\n        process.stderr.write('\\n');\n        // The \"do NOT `git checkout main`\" caveat is scoped to the WORKTREE case, where it is true.\n        // Stated unconditionally it forbids a command that is perfectly good in the primary clone —\n        // and that CLAUDE.md's own post-merge cleanup recipe uses — which is how an agent talked\n        // itself into believing a new branch was its only exit.\n        process.stderr.write('2. Create a new branch OFF origin/main (this form works from ANY tree; inside a\\n');\n        process.stderr.write('   worktree do NOT `git checkout main` first — it fatals with \"main is already\\n');\n        process.stderr.write('   checked out at <primary>\"):\\n');\n        process.stderr.write(`   git checkout -b ${featureName}-v2 origin/main\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write('3. Squash merge your old branch — THIS STEP IS FOR THE HUMAN TO RUN:\\n');\n        process.stderr.write(`   git merge --squash ${currentBranch}\\n`);\n        process.stderr.write('   AI: `git merge` is blocked for you (redirect-how-to-merge-main) and you must NOT\\n');\n        process.stderr.write('   work around it. Ask the human to run that one command, and warn them:\\n');\n        process.stderr.write('   \"This is a raw git merge. It is only correct here because the branch is already\\n');\n        process.stderr.write('    broken and is being rebuilt onto origin/main. For a NORMAL update from main,\\n');\n        process.stderr.write('    push back and tell me to use the gated 3-point merge instead: `pnpm wp-start-update`\\n');\n        process.stderr.write('    (paired with `pnpm wp-finish-update`) when no PR is open, or `pnpm wp-start-upsert-pr`\\n');\n        process.stderr.write('    (paired with `pnpm wp-finish-upsert-pr`) when one is.\"\\n');\n        process.stderr.write('\\n');\n        process.stderr.write('4. Commit the squashed changes:\\n');\n        process.stderr.write(`   git add -A && git commit -m \"Squashed from ${currentBranch}\"\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write('5. If you have an existing PR:\\n');\n        process.stderr.write(`   - Create a NEW PR for ${featureName}-v2\\n`);\n        process.stderr.write(`   - Close the old PR for ${currentBranch}\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write(SEP);\n        process.stderr.write('\\n');\n    }\n}\n"]}
+{"version":3,"file":"git-findForkPoint.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-findForkPoint.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { prDirFor, CliExitError, RepoRootFinder } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AiBranchName } from './git-readAiBranchName';\nimport { MergeState } from './merge-state';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/** Computes the 3-point fork point and guards against improper merges-from-main. */\n@injectable(bindingScopeValues.Singleton)\nexport class ForkPoint {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly aiBranchName: AiBranchName,\n        private readonly mergeState: MergeState,\n    ) {}\n\n    // Single source of truth for the per-feature dir fork-point output is written to — the SAME nested\n    // home the readers use (git-gatherInfo / merge-start read updatemain-hashes.json from mergeDirFor;\n    // the review flow reads from prDirFor). Routing the writer through these same helpers is what keeps\n    // them from diverging again — guarded by git-findForkPoint.spec.ts.\n    forkPointOutputDir(repoRoot: string, featureName: string, workflow: string): string {\n        return workflow === 'review' ? prDirFor(repoRoot, featureName) : this.mergeState.mergeDirFor(repoRoot, featureName);\n    }\n\n    /**\n     * The 3-point FORK POINT: where this branch diverged from main. `git merge-base origin/main HEAD`,\n     * falling back to a local `main`, and '' when neither ref resolves.\n     *\n     * Deliberately does NOT fetch. The fork point is ABSOLUTE — advancing main cannot move it, because\n     * merge-base is the most recent common ancestor and main's new commits are not on this branch. (Verified\n     * on this repo: main went f415456 → ba8f674 → 61432d6 while merge-base with one branch stayed f415456\n     * throughout.) So a caller that needs only the fork point — see ChecklistScanner — pays no network cost\n     * and works offline. `findForkPoint` below still fetches, because the MERGE flow additionally needs\n     * main's CURRENT head as hash point C, which genuinely does require a fetch.\n     *\n     * Also writes no files and runs no merge-commit scan, so it cannot throw: `wp-review-upsert-pr` must always\n     * succeed, and a raw merge-from-main is the merge flow's problem to report, not the checklist's.\n     */\n    resolveForkPoint(repoRoot: string): string {\n        for (const ref of ['origin/main', 'main']) {\n            const result = spawnSync('git', ['merge-base', ref, 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });\n            const sha = (result.stdout ?? '').trim();\n            if (result.status === 0 && sha !== '') return sha;\n        }\n        return '';\n    }\n\n    async findForkPoint(workflow: string): Promise<void> {\n        if (workflow !== 'review' && workflow !== 'merge') {\n            throw new CliExitError(1,\n                'ERROR: Workflow argument required\\n' +\n                'Usage: git-findForkPoint <workflow>\\n' +\n                \"  workflow: 'review' or 'merge'\",\n            );\n        }\n\n        const featureName = this.aiBranchName.getFeatureName();\n        const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n\n        const outputDir = this.forkPointOutputDir(repoRoot, featureName, workflow);\n        const prefix = workflow === 'review' ? 'review-' : 'updatemain-';\n        fs.mkdirSync(outputDir, { recursive: true });\n\n        spawnSync('git', ['fetch', 'origin', 'main'], { stdio: 'ignore' });\n\n        const featureHead = execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();\n        const originMain = execSync('git rev-parse origin/main', { encoding: 'utf8' }).trim();\n\n        process.stderr.write('Finding fork point using git merge-base...\\n');\n\n        // ONE implementation of the fork-point computation, shared with ChecklistScanner. The fetch above is\n        // what this flow needs beyond it (hash point C = main's current head), not the fork point itself.\n        const forkPoint = this.resolveForkPoint(repoRoot);\n\n        if (!forkPoint) {\n            throw new CliExitError(1, 'ERROR: Could not find common ancestor with origin/main');\n        }\n\n        process.stderr.write(`✅ Fork point found: ${forkPoint.slice(0, 7)}\\n`);\n        process.stderr.write('Checking for improper merges from main...\\n');\n\n        const mergeCommitsResult = spawnSync('git', ['log', `${forkPoint}..HEAD`, '--merges', '--format=%H'], { encoding: 'utf8' });\n        const mergeCommitsRaw = (mergeCommitsResult.stdout ?? '').trim();\n        const mergeCommits = mergeCommitsRaw ? mergeCommitsRaw.split('\\n') : [];\n\n        if (mergeCommits.length > 0) {\n            this.checkMergeCommits(mergeCommits, outputDir, prefix, featureName, currentBranch);\n        } else {\n            process.stderr.write('✅ No merge commits found (clean history)\\n');\n        }\n\n        const hashesJson = JSON.stringify({\n            hashForkPoint: forkPoint,\n            hashFeatureHead: featureHead,\n            hashMainHead: originMain,\n            timestamp: new Date().toISOString(),\n        }, null, 2);\n\n        fs.writeFileSync(path.join(outputDir, `${prefix}hashes.json`), hashesJson + '\\n');\n        process.stderr.write(`✅ Hash points written to: ${outputDir}/${prefix}hashes.json\\n`);\n    }\n\n    private checkMergeCommits(mergeCommits: string[], outputDir: string, prefix: string, featureName: string, currentBranch: string): void {\n        process.stderr.write(`Found ${mergeCommits.length} merge commit(s) to check...\\n`);\n\n        for (const commit of mergeCommits) {\n            const parentsResult = spawnSync('git', ['rev-list', '--parents', '-n', '1', commit], { encoding: 'utf8' });\n            const parents = (parentsResult.stdout ?? '').trim().split(' ').slice(1);\n\n            for (const parent of parents) {\n                const ancestorCheck = spawnSync('git', ['merge-base', '--is-ancestor', parent, 'origin/main']);\n                const reverseCheck = spawnSync('git', ['merge-base', '--is-ancestor', 'origin/main', parent]);\n\n                if (ancestorCheck.status === 0 && reverseCheck.status === 0) {\n                    const errorJson = JSON.stringify({\n                        error: 'Merge from main detected',\n                        mergeCommit: commit,\n                        parentFromMain: parent,\n                        timestamp: new Date().toISOString(),\n                    }, null, 2);\n\n                    fs.writeFileSync(path.join(outputDir, `${prefix}forkpoint-error.json`), errorJson + '\\n');\n                    this.printMergeFromMainError(commit, parent, featureName, currentBranch);\n                    throw new CliExitError(1, '');\n                }\n            }\n        }\n        process.stderr.write('✅ No improper merges from main detected\\n');\n    }\n\n    private printMergeFromMainError(commit: string, parent: string, featureName: string, currentBranch: string): void {\n        process.stderr.write('\\n');\n        process.stderr.write(SEP);\n        process.stderr.write('❌ This branch merged main without the gated update (pnpm wp-start-update, or\\n');\n        process.stderr.write('   pnpm wp-start-upsert-pr when a PR is open)\\n');\n        process.stderr.write(SEP);\n        process.stderr.write('\\n');\n        process.stderr.write(`Merge commit detected: ${commit}\\n`);\n        process.stderr.write(`Parent from main:      ${parent}\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write('This prevents clean squash-merge. To recover, follow these steps:\\n');\n        process.stderr.write('\\n');\n        process.stderr.write('1. Fetch the latest main (works on the primary repo AND in a worktree):\\n');\n        process.stderr.write('   git fetch origin main\\n');\n        process.stderr.write('\\n');\n        // The \"do NOT `git checkout main`\" caveat is scoped to the WORKTREE case, where it is true.\n        // Stated unconditionally it forbids a command that is perfectly good in the primary clone —\n        // and that CLAUDE.md's own post-merge cleanup recipe uses — which is how an agent talked\n        // itself into believing a new branch was its only exit.\n        process.stderr.write('2. Create a new branch OFF origin/main (this form works from ANY tree; inside a\\n');\n        process.stderr.write('   worktree do NOT `git checkout main` first — it fatals with \"main is already\\n');\n        process.stderr.write('   checked out at <primary>\"):\\n');\n        process.stderr.write(`   git checkout -b ${featureName}-v2 origin/main\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write('3. Squash merge your old branch — THIS STEP IS FOR THE HUMAN TO RUN:\\n');\n        process.stderr.write(`   git merge --squash ${currentBranch}\\n`);\n        process.stderr.write('   AI: `git merge` is blocked for you (redirect-how-to-merge-main) and you must NOT\\n');\n        process.stderr.write('   work around it. Ask the human to run that one command, and warn them:\\n');\n        process.stderr.write('   \"This is a raw git merge. It is only correct here because the branch is already\\n');\n        process.stderr.write('    broken and is being rebuilt onto origin/main. For a NORMAL update from main,\\n');\n        process.stderr.write('    push back and tell me to use the gated 3-point merge instead: `pnpm wp-start-update`\\n');\n        process.stderr.write('    (paired with `pnpm wp-finish-update`) when no PR is open, or `pnpm wp-start-upsert-pr`\\n');\n        process.stderr.write('    (paired with `pnpm wp-finish-upsert-pr`) when one is.\"\\n');\n        process.stderr.write('\\n');\n        process.stderr.write('4. Commit the squashed changes:\\n');\n        process.stderr.write(`   git add -A && git commit -m \"Squashed from ${currentBranch}\"\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write('5. If you have an existing PR:\\n');\n        process.stderr.write(`   - Create a NEW PR for ${featureName}-v2\\n`);\n        process.stderr.write(`   - Close the old PR for ${currentBranch}\\n`);\n        process.stderr.write('\\n');\n        process.stderr.write(SEP);\n        process.stderr.write('\\n');\n    }\n}\n"]}