@paraharness/git 0.0.0-stage → 0.1.0

package/dist/executors/internal/git-worktree-sync-child-and-root.js

@@ -0,0 +1,82 @@
+import { GitSyncReceiptSchema } from '../../schemas/git-receipts.schema.js';
+import { runGitCommand } from './git-cli-runner.js';
+import { gitWorktreeFlushCleanParentChanges } from './git-worktree-flush-and-prune.js';
+import { executeStatelessMergeTree, gitWorktreeMaterializeMerge, synthesizeWorkingTreeCommitOverBase, } from './git-worktree-materialize-merge.js';
+import { resolvePrerequisiteBaseBranch } from './parent-fast-forward.js';
+/**
+ * Rebases/merges uncommitted changes in `pausedChild` onto an updated `parent` worktree via `git merge-tree --write-tree`.
+ *
+ * Preserves dirty edits in `pausedChild` and records any conflicted paths in `pausedChild.unresolvedConflictPaths`.
+ *
+ * @param {GitWorktreeHandle}             parent         - Updated parent worktree handle.
+ * @param {GitWorktreeHandle}             pausedChild    - Suspended child worktree handle being synced.
+ * @param {readonly string[] | undefined} [excludeGlobs] - Optional glob patterns excluded from staging.
+ *
+ * @returns {Promise<ReconcileResult<GitSyncReceipt>>} Clean or conflicted synchronization receipt.
+ */
+export async function gitWorktreeSyncChild(parent, pausedChild, excludeGlobs) {
+    const c0Sha = pausedChild.baseRef;
+    const c1Sha = await gitWorktreeFlushCleanParentChanges(parent, excludeGlobs);
+    const childSynth = await synthesizeWorkingTreeCommitOverBase(pausedChild, c0Sha, excludeGlobs);
+    const mergeOutcome = await executeStatelessMergeTree(pausedChild, c1Sha, childSynth.commitSha);
+    await gitWorktreeMaterializeMerge(pausedChild, {
+        targetHeadSha: c1Sha,
+        mergedTreeSha: mergeOutcome.mergedTreeSha,
+        priorTreeSha: childSynth.treeSha,
+        conflictedPaths: mergeOutcome.conflictedPaths,
+        nextBaseBranch: parent.baseBranch,
+    });
+    const diffOutput = await runGitCommand({ cwd: pausedChild.worktreePath, args: ['diff-tree', '-r', '--name-only', '-z', c0Sha, c1Sha] });
+    const updatedFiles = diffOutput.stdout.split('\0').filter((relPath) => relPath.length > 0);
+    const receipt = GitSyncReceiptSchema.parse({ rebasedOntoRef: c1Sha, baseBranch: parent.baseBranch, updatedFiles });
+    if (mergeOutcome.clean)
+        return { status: 'clean', data: receipt };
+    return {
+        status: 'conflict',
+        conflictedSummary: `syncChild conflict on paths: ${mergeOutcome.conflictedPaths.join(', ')}`,
+        data: receipt,
+    };
+}
+/**
+ * Synchronizes `rootHandle` onto the tip prerequisite receipt in `prerequisiteReceipts` via `git merge-tree --write-tree`.
+ *
+ * Auto-flushes clean dirty edits on `rootHandle`, resolves stacked `baseBranch`, and materializes the 3-way merge.
+ *
+ * @param {GitWorktreeHandle}             rootHandle           - Task root worktree handle.
+ * @param {readonly GitScopeReceipt[]}    prerequisiteReceipts - Terminal scope receipts of completed prerequisites.
+ * @param {readonly string[] | undefined} [excludeGlobs]       - Optional glob patterns excluded from staging.
+ *
+ * @returns {Promise<ReconcileResult<GitSyncReceipt>>} Clean or conflicted synchronization receipt.
+ */
+export async function gitWorktreeSyncRoot(rootHandle, prerequisiteReceipts, excludeGlobs) {
+    const tipReceipt = prerequisiteReceipts[prerequisiteReceipts.length - 1];
+    if (tipReceipt === undefined) {
+        return {
+            status: 'clean',
+            data: GitSyncReceiptSchema.parse({ rebasedOntoRef: rootHandle.baseRef, baseBranch: rootHandle.baseBranch, updatedFiles: [] }),
+        };
+    }
+    const c0Sha = rootHandle.baseRef;
+    await gitWorktreeFlushCleanParentChanges(rootHandle, excludeGlobs);
+    const resolvedBaseBranch = await resolvePrerequisiteBaseBranch(rootHandle, tipReceipt);
+    const rootSynth = await synthesizeWorkingTreeCommitOverBase(rootHandle, c0Sha, excludeGlobs);
+    const mergeOutcome = await executeStatelessMergeTree(rootHandle, tipReceipt.headRef, rootSynth.commitSha);
+    await gitWorktreeMaterializeMerge(rootHandle, {
+        targetHeadSha: tipReceipt.headRef,
+        mergedTreeSha: mergeOutcome.mergedTreeSha,
+        priorTreeSha: rootSynth.treeSha,
+        conflictedPaths: mergeOutcome.conflictedPaths,
+        nextBaseBranch: resolvedBaseBranch,
+    });
+    const diffOutput = await runGitCommand({ cwd: rootHandle.worktreePath, args: ['diff-tree', '-r', '--name-only', '-z', c0Sha, tipReceipt.headRef] });
+    const updatedFiles = diffOutput.stdout.split('\0').filter((relPath) => relPath.length > 0);
+    const receipt = GitSyncReceiptSchema.parse({ rebasedOntoRef: tipReceipt.headRef, baseBranch: resolvedBaseBranch, updatedFiles });
+    if (mergeOutcome.clean)
+        return { status: 'clean', data: receipt };
+    return {
+        status: 'conflict',
+        conflictedSummary: `syncRoot conflict on paths: ${mergeOutcome.conflictedPaths.join(', ')}`,
+        data: receipt,
+    };
+}
+//# sourceMappingURL=git-worktree-sync-child-and-root.js.map

package/dist/executors/internal/git-worktree-sync-child-and-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-worktree-sync-child-and-root.js","sourceRoot":"","sources":["../../../src/executors/internal/git-worktree-sync-child-and-root.ts"],"names":[],"mappings":"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"}

package/dist/executors/internal/host-repository-head-state.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolved `HEAD` commit SHA and default branch name of a host Git repository.
+ */
+export interface HostRepositoryHeadState {
+    /** Current `HEAD` commit SHA resolved via `git rev-parse HEAD`. */
+    readonly baseRef: string;
+    /** Symbolic branch name of `HEAD` or `'main'` when detached. */
+    readonly baseBranch: string;
+}
+//# sourceMappingURL=host-repository-head-state.d.ts.map

package/dist/executors/internal/host-repository-head-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-repository-head-state.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/host-repository-head-state.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B"}

package/dist/executors/internal/host-repository-head-state.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=host-repository-head-state.js.map

package/dist/executors/internal/host-repository-head-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-repository-head-state.js","sourceRoot":"","sources":["../../../src/executors/internal/host-repository-head-state.ts"],"names":[],"mappings":""}

package/dist/executors/internal/merge-train-candidate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalized candidate branch descriptor queued for a batch merge-train run.
+ *
+ * Identifies the candidate's label (branch name or ref), head commit SHA, and base commit SHA.
+ */
+export interface MergeTrainCandidate {
+    /** Branch name or ref label for diagnostics and result reporting. */
+    readonly label: string;
+    /** Candidate tip commit SHA to rebase onto the merge train. */
+    readonly headSha: string;
+    /** Base commit SHA from which the candidate diverged. */
+    readonly baseSha: string;
+}
+//# sourceMappingURL=merge-train-candidate.d.ts.map

package/dist/executors/internal/merge-train-candidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-candidate.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-candidate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/executors/internal/merge-train-candidate.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=merge-train-candidate.js.map

package/dist/executors/internal/merge-train-candidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-candidate.js","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-candidate.ts"],"names":[],"mappings":""}

package/dist/executors/internal/merge-train-chain-entry.d.ts

@@ -0,0 +1,13 @@
+import type { MergeTrainCandidate } from './merge-train-candidate.js';
+/**
+ * Speculative cumulative rebase chain entry ($R_i$) in a batch merge train.
+ *
+ * Pairs the original `MergeTrainCandidate` with its cumulatively rebased commit SHA $R_i$.
+ */
+export interface MergeTrainChainEntry {
+    /** Candidate branch included at this step of the cumulative rebase chain. */
+    readonly candidate: MergeTrainCandidate;
+    /** Commit SHA of the cumulative rebase tip $R_i$ after applying `candidate`. */
+    readonly rebasedSha: string;
+}
+//# sourceMappingURL=merge-train-chain-entry.d.ts.map

package/dist/executors/internal/merge-train-chain-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-chain-entry.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-chain-entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B"}

package/dist/executors/internal/merge-train-chain-entry.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=merge-train-chain-entry.js.map

package/dist/executors/internal/merge-train-chain-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-chain-entry.js","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-chain-entry.ts"],"names":[],"mappings":""}

package/dist/executors/internal/merge-train-result.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Outcome of executing a cumulative batch merge-train pass (`git.mergeQueue`).
+ *
+ * Reports the updated `targetBranch` tip commit SHA, landed candidate labels, evicted candidate labels,
+ * and total `verifyWith` executions performed.
+ */
+export interface MergeTrainResult {
+    /** Target upstream branch updated by the merge train. */
+    readonly targetBranch: string;
+    /** Final fast-forwarded commit SHA on `targetBranch`. */
+    readonly headRef: string;
+    /** Ordered list of candidate branch labels that passed verification and landed. */
+    readonly landedBranches: readonly string[];
+    /** Ordered list of offending candidate branch labels isolated and evicted during bisection or conflict. */
+    readonly evictedBranches: readonly string[];
+    /** Total number of `verifyWith` check executions run across the batch. */
+    readonly verificationRuns: number;
+}
+//# sourceMappingURL=merge-train-result.d.ts.map

package/dist/executors/internal/merge-train-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-result.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-result.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,2GAA2G;IAC3G,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC"}

package/dist/executors/internal/merge-train-result.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=merge-train-result.js.map

package/dist/executors/internal/merge-train-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-result.js","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-result.ts"],"names":[],"mappings":""}

package/dist/executors/internal/merge-train-runner.d.ts

@@ -0,0 +1,16 @@
+import type { GitMergeQueueNode, GitWorktreeHandle, StepExecutionContext } from '@paraharness/core';
+import type { MergeTrainCandidate } from './merge-train-candidate.js';
+import type { MergeTrainResult } from './merge-train-result.js';
+/**
+ * Runs the iterative cumulative rebase train and binary bisection loop for `git.mergeQueue`.
+ *
+ * Lands valid candidate prefixes onto `node.targetBranch` and evicts offending candidate branches.
+ *
+ * @param {GitMergeQueueNode<unknown, unknown>}     node       - Merge queue step AST node.
+ * @param {readonly MergeTrainCandidate[]}          candidates - Normalized candidate branches for the batch.
+ * @param {StepExecutionContext<GitWorktreeHandle>} ctx        - Active step execution context.
+ *
+ * @returns {Promise<MergeTrainResult>} Completed batch merge-train outcome.
+ */
+export declare function executeBatchMergeTrainQueue(node: GitMergeQueueNode<unknown, unknown>, candidates: readonly MergeTrainCandidate[], ctx: StepExecutionContext<GitWorktreeHandle>): Promise<MergeTrainResult>;
+//# sourceMappingURL=merge-train-runner.d.ts.map

package/dist/executors/internal/merge-train-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-runner.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAO3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AA2IhE;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,EACzC,UAAU,EAAE,SAAS,mBAAmB,EAAE,EAC1C,GAAG,EAAE,oBAAoB,CAAC,iBAAiB,CAAC,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CAwC3B"}

package/dist/executors/internal/merge-train-runner.js

@@ -0,0 +1,141 @@
+import { runGitCommand } from './git-cli-runner.js';
+import { buildCumulativeRebaseChain, evaluateWorktreeCheck, gitMergeTrainBisect, } from './git-merge-train-bisect.js';
+/**
+ * Fetches `origin` and resolves the current commit SHA of `targetBranch` (preferring `refs/remotes/origin/<targetBranch>`).
+ *
+ * @param {string}            cwd          - Worktree directory path.
+ * @param {string}            targetBranch - Target branch name configured on `GitMergeQueueNode`.
+ * @param {GitWorktreeHandle} handle       - Active worktree handle providing fallback `baseRef`.
+ *
+ * @returns {Promise<string>} Resolved initial target branch commit SHA.
+ */
+async function resolveMergeTrainTargetSha(cwd, targetBranch, handle) {
+    await runGitCommand({ cwd, args: ['fetch', 'origin'], allowNonZeroExit: true });
+    const targetLookup = await runGitCommand({
+        cwd,
+        args: ['rev-parse', '--verify', `refs/remotes/origin/${targetBranch}`],
+        allowNonZeroExit: true,
+    });
+    if (targetLookup.exitCode === 0) {
+        return targetLookup.stdout.trim();
+    }
+    const localBranchLookup = await runGitCommand({
+        cwd,
+        args: ['rev-parse', targetBranch],
+        allowNonZeroExit: true,
+    });
+    return localBranchLookup.stdout.trim() || handle.baseRef;
+}
+/**
+ * Verifies the tip of a cumulative speculative rebase chain `params.chain`, or binary-bisects `params.chain` on failure
+ * to land the valid prefix and evict the first offending candidate.
+ *
+ * @param {VerifyOrBisectMergeTrainChainParams} params - Chain verification and bisection parameters and mutable queue state.
+ *
+ * @returns {Promise<void>} Resolves once `params` queue state is updated for the completed chain iteration.
+ */
+async function verifyOrBisectMergeTrainChain(params) {
+    const { node, ctx, chain, conflictedIdx, landedBranches, evictedBranches } = params;
+    const cwd = ctx.scopeHandle.worktreePath;
+    const tipEntry = chain[chain.length - 1];
+    if (tipEntry === undefined) {
+        const first = params.queue[0];
+        if (first !== undefined)
+            evictedBranches.push(first.label);
+        params.queue = params.queue.slice(1);
+        return;
+    }
+    await runGitCommand({ cwd, args: ['reset', '--hard', tipEntry.rebasedSha] });
+    params.verificationRuns += 1;
+    const tipCheck = await evaluateWorktreeCheck(node.verifyWith, ctx);
+    if (tipCheck.ok) {
+        params.currentTargetSha = tipEntry.rebasedSha;
+        for (const entry of chain)
+            landedBranches.push(entry.candidate.label);
+        const conflictedCandidate = conflictedIdx >= 0 ? params.queue[conflictedIdx] : undefined;
+        if (conflictedCandidate !== undefined) {
+            evictedBranches.push(conflictedCandidate.label);
+        }
+        params.queue =
+            conflictedIdx >= 0 ? params.queue.slice(conflictedIdx + 1) : [];
+        return;
+    }
+    const [badIdx, bisectRuns] = await gitMergeTrainBisect(chain, node.verifyWith, ctx);
+    params.verificationRuns += bisectRuns;
+    const priorEntry = badIdx > 0 ? chain[badIdx - 1] : undefined;
+    if (priorEntry !== undefined) {
+        params.currentTargetSha = priorEntry.rebasedSha;
+    }
+    for (let j = 0; j < badIdx; j += 1) {
+        const prefixEntry = chain[j];
+        if (prefixEntry !== undefined)
+            landedBranches.push(prefixEntry.candidate.label);
+    }
+    const badEntry = chain[badIdx];
+    if (badEntry !== undefined)
+        evictedBranches.push(badEntry.candidate.label);
+    params.queue = params.queue.slice(badIdx + 1);
+}
+/**
+ * Resets the worktree to `targetSha`, fast-forwards `refs/heads/<targetBranch>`, and pushes to `origin`.
+ *
+ * @param {string} cwd          - Worktree directory path.
+ * @param {string} targetBranch - Target branch name configured on `GitMergeQueueNode`.
+ * @param {string} targetSha    - Final verified commit SHA to fast-forward onto.
+ *
+ * @returns {Promise<void>} Resolves once the local and remote target branch refs are updated.
+ */
+async function fastForwardAndPushMergeTrainTarget(cwd, targetBranch, targetSha) {
+    await runGitCommand({ cwd, args: ['reset', '--hard', targetSha] });
+    await runGitCommand({
+        cwd,
+        args: ['update-ref', `refs/heads/${targetBranch}`, targetSha],
+        allowNonZeroExit: true,
+    });
+    await runGitCommand({
+        cwd,
+        args: ['push', 'origin', `${targetSha}:refs/heads/${targetBranch}`],
+        allowNonZeroExit: true,
+    });
+}
+/**
+ * Runs the iterative cumulative rebase train and binary bisection loop for `git.mergeQueue`.
+ *
+ * Lands valid candidate prefixes onto `node.targetBranch` and evicts offending candidate branches.
+ *
+ * @param {GitMergeQueueNode<unknown, unknown>}     node       - Merge queue step AST node.
+ * @param {readonly MergeTrainCandidate[]}          candidates - Normalized candidate branches for the batch.
+ * @param {StepExecutionContext<GitWorktreeHandle>} ctx        - Active step execution context.
+ *
+ * @returns {Promise<MergeTrainResult>} Completed batch merge-train outcome.
+ */
+export async function executeBatchMergeTrainQueue(node, candidates, ctx) {
+    const cwd = ctx.scopeHandle.worktreePath;
+    const initialTargetSha = await resolveMergeTrainTargetSha(cwd, node.targetBranch, ctx.scopeHandle);
+    const state = {
+        node,
+        ctx,
+        chain: [],
+        conflictedIdx: -1,
+        landedBranches: [],
+        evictedBranches: [],
+        currentTargetSha: initialTargetSha,
+        queue: [...candidates],
+        verificationRuns: 0,
+    };
+    while (state.queue.length > 0) {
+        const [chain, conflictedIdx] = await buildCumulativeRebaseChain(cwd, state.currentTargetSha, state.queue);
+        state.chain = chain;
+        state.conflictedIdx = conflictedIdx;
+        await verifyOrBisectMergeTrainChain(state);
+    }
+    await fastForwardAndPushMergeTrainTarget(cwd, node.targetBranch, state.currentTargetSha);
+    return {
+        targetBranch: node.targetBranch,
+        headRef: state.currentTargetSha,
+        landedBranches: state.landedBranches,
+        evictedBranches: state.evictedBranches,
+        verificationRuns: state.verificationRuns,
+    };
+}
+//# sourceMappingURL=merge-train-runner.js.map

package/dist/executors/internal/merge-train-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-train-runner.js","sourceRoot":"","sources":["../../../src/executors/internal/merge-train-runner.ts"],"names":[],"mappings":"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"}

package/dist/executors/internal/merge-tree-materializer-params.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parameters for `materializeInFlightMergeIntoWorktree` and `finalizeMaterializedMergeMetadata`.
+ *
+ * Carries the target commit SHA ($C_1$ or $C_{\text{prereq}}$), merged tree SHA ($T_{\text{merged}}$),
+ * prior working-tree SHA ($T_{\text{child}}$ or $T_{\text{root}}$), conflicted paths, and optional updated `baseBranch`.
+ */
+export interface MaterializeInFlightMergeParams {
+    /** Target commit SHA onto which `HEAD`, `.git/index`, and `baseRef` advance. */
+    readonly targetHeadSha: string;
+    /** Top-level tree SHA emitted by `git merge-tree --write-tree`. */
+    readonly mergedTreeSha: string;
+    /** Prior synthesized tree SHA of the child or root worktree before the merge. */
+    readonly priorTreeSha: string;
+    /** Repository-relative paths reported as conflicted by `git merge-tree`. */
+    readonly conflictedPaths: readonly string[];
+    /** Optional updated base branch name (such as a stacked prerequisite branch). */
+    readonly nextBaseBranch?: string;
+}
+//# sourceMappingURL=merge-tree-materializer-params.d.ts.map

package/dist/executors/internal/merge-tree-materializer-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-tree-materializer-params.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/merge-tree-materializer-params.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,8BAA8B;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,iFAAiF;IACjF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC"}

package/dist/executors/internal/merge-tree-materializer-params.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=merge-tree-materializer-params.js.map

package/dist/executors/internal/merge-tree-materializer-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-tree-materializer-params.js","sourceRoot":"","sources":["../../../src/executors/internal/merge-tree-materializer-params.ts"],"names":[],"mappings":""}

package/dist/executors/internal/parent-fast-forward.d.ts

@@ -0,0 +1,47 @@
+import type { GitScopeReceipt, GitWorktreeHandle } from '@paraharness/core';
+/**
+ * Advances `parent` from `c1Sha` to `cTargetSha` using crash-safe `pendingParentHeadSha` and `git read-tree -u -m`.
+ *
+ * Resets any colliding paths in `parent.unresolvedConflictPaths` or untracked working tree files to match `c1Sha` first.
+ *
+ * @param {GitWorktreeHandle} parent     - Target parent worktree handle.
+ * @param {string}            c1Sha      - Current `parent.HEAD` commit SHA before advancing.
+ * @param {string}            cTargetSha - Merged target commit SHA to advance `parent` onto.
+ *
+ * @returns {Promise<void>} Resolves once `parent` working tree, index, `HEAD`, and `harness-meta.json` are updated.
+ */
+export declare function fastForwardParentToTargetCommit(parent: GitWorktreeHandle, c1Sha: string, cTargetSha: string): Promise<void>;
+/**
+ * Pins `refs/harness/candidates/<run-id>/<branch-index>` in the host object store when `handle` is a child fork worktree.
+ *
+ * Extracts `<run-id>` and `<branch-index>` from `<dir>/forks/<runId>/<forkId>` worktree paths.
+ *
+ * @param {GitWorktreeHandle} handle  - Worktree handle being inspected.
+ * @param {string}            headRef - Synthesized or current commit SHA to pin.
+ *
+ * @returns {Promise<void>} Resolves once candidate refs are updated.
+ */
+export declare function pinCandidateRefIfSpeculativeBranch(handle: GitWorktreeHandle, headRef: string): Promise<void>;
+/**
+ * Scans dirty/untracked files and committed diffs (`baseRef..HEAD`) on `handle` for paired conflict markers.
+ *
+ * Returns all repository-relative file paths containing `<<<<<<<` / `=======` / `>>>>>>>` marker blocks.
+ *
+ * @param {GitWorktreeHandle}             handle         - Worktree handle to scan.
+ * @param {readonly string[] | undefined} [excludeGlobs] - Optional glob patterns excluded from scanning.
+ *
+ * @returns {Promise<readonly string[]>} List of file paths containing paired conflict markers.
+ */
+export declare function findWorktreeConflictMarkerPaths(handle: GitWorktreeHandle, excludeGlobs?: readonly string[]): Promise<readonly string[]>;
+/**
+ * Resolves the stacked-PR `baseBranch` for `rootHandle` when syncing onto `tipReceipt`.
+ *
+ * Runs `git fetch origin` (ignoring missing remotes) and checks whether `tipReceipt.branchName` is already merged into `origin/main`.
+ *
+ * @param {GitWorktreeHandle} rootHandle - Root worktree handle being synced.
+ * @param {GitScopeReceipt}   tipReceipt - Terminal scope receipt of the tip prerequisite run.
+ *
+ * @returns {Promise<string>} Resolved base branch name (`tipReceipt.branchName` when unmerged, or `'main'`).
+ */
+export declare function resolvePrerequisiteBaseBranch(rootHandle: GitWorktreeHandle, tipReceipt: GitScopeReceipt): Promise<string>;
+//# sourceMappingURL=parent-fast-forward.d.ts.map

package/dist/executors/internal/parent-fast-forward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent-fast-forward.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/parent-fast-forward.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAW5E;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;;;;;;;GASG;AACH,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,iBAAiB,EACzB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAC/B,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAkB5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,iBAAiB,EAC7B,UAAU,EAAE,eAAe,GAC1B,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/dist/executors/internal/parent-fast-forward.js

@@ -0,0 +1,138 @@
+import { readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { listTreePaths } from './checkpoint-staging-and-integrity.js';
+import { gitCheckpointStatusMap } from './git-checkpoint-status-map.js';
+import { readHarnessMeta, runGitCommand, updateWorktreeHandleInPlace, writeHarnessMeta, } from './git-cli-runner.js';
+import { hasPairedConflictMarkers } from './git-worktree-flush-and-prune.js';
+/**
+ * Advances `parent` from `c1Sha` to `cTargetSha` using crash-safe `pendingParentHeadSha` and `git read-tree -u -m`.
+ *
+ * Resets any colliding paths in `parent.unresolvedConflictPaths` or untracked working tree files to match `c1Sha` first.
+ *
+ * @param {GitWorktreeHandle} parent     - Target parent worktree handle.
+ * @param {string}            c1Sha      - Current `parent.HEAD` commit SHA before advancing.
+ * @param {string}            cTargetSha - Merged target commit SHA to advance `parent` onto.
+ *
+ * @returns {Promise<void>} Resolves once `parent` working tree, index, `HEAD`, and `harness-meta.json` are updated.
+ */
+export async function fastForwardParentToTargetCommit(parent, c1Sha, cTargetSha) {
+    const meta = await readHarnessMeta(parent.gitDirPath);
+    const diffRes = await runGitCommand({
+        cwd: parent.worktreePath,
+        args: ['diff-tree', '-r', '--name-only', '-z', c1Sha, cTargetSha],
+    });
+    const touchedPaths = diffRes.stdout.split('\0').filter((p) => p.length > 0);
+    const pathsToReset = new Set([...touchedPaths, ...Object.keys(meta.unresolvedConflictPaths)]);
+    const c1Paths = await listTreePaths(parent.worktreePath, c1Sha);
+    for (const relPath of pathsToReset) {
+        if (c1Paths.has(relPath)) {
+            await runGitCommand({ cwd: parent.worktreePath, args: ['checkout-index', '-f', '--', relPath], allowNonZeroExit: true });
+        }
+        else {
+            await rm(path.join(parent.worktreePath, relPath), { force: true });
+        }
+    }
+    await writeHarnessMeta(parent.gitDirPath, { ...meta, pendingParentHeadSha: cTargetSha });
+    await runGitCommand({ cwd: parent.worktreePath, args: ['read-tree', '-u', '-m', c1Sha, cTargetSha] });
+    await runGitCommand({ cwd: parent.worktreePath, args: ['update-ref', 'HEAD', cTargetSha, c1Sha] });
+    const nextConflicts = {};
+    for (const [relPath, digest] of Object.entries(meta.unresolvedConflictPaths)) {
+        if (!pathsToReset.has(relPath))
+            nextConflicts[relPath] = digest;
+    }
+    const frozenConflicts = Object.freeze(nextConflicts);
+    await writeHarnessMeta(parent.gitDirPath, {
+        ...meta,
+        pendingParentHeadSha: undefined,
+        unresolvedConflictPaths: frozenConflicts,
+    });
+    updateWorktreeHandleInPlace(parent, {
+        headRef: cTargetSha,
+        unresolvedConflictPaths: frozenConflicts,
+    });
+}
+/**
+ * Pins `refs/harness/candidates/<run-id>/<branch-index>` in the host object store when `handle` is a child fork worktree.
+ *
+ * Extracts `<run-id>` and `<branch-index>` from `<dir>/forks/<runId>/<forkId>` worktree paths.
+ *
+ * @param {GitWorktreeHandle} handle  - Worktree handle being inspected.
+ * @param {string}            headRef - Synthesized or current commit SHA to pin.
+ *
+ * @returns {Promise<void>} Resolves once candidate refs are updated.
+ */
+export async function pinCandidateRefIfSpeculativeBranch(handle, headRef) {
+    const runDir = path.dirname(handle.worktreePath);
+    const forksDir = path.dirname(runDir);
+    if (path.basename(forksDir) !== 'forks')
+        return;
+    const runId = path.basename(runDir);
+    const forkName = path.basename(handle.worktreePath);
+    const numericMatch = /(\d+)$/.exec(forkName);
+    if (numericMatch?.[1] !== undefined) {
+        await runGitCommand({
+            cwd: handle.worktreePath,
+            args: ['update-ref', `refs/harness/candidates/${runId}/${numericMatch[1]}`, headRef],
+        });
+    }
+    await runGitCommand({
+        cwd: handle.worktreePath,
+        args: ['update-ref', `refs/harness/candidates/${runId}/${forkName}`, headRef],
+        allowNonZeroExit: true,
+    });
+}
+/**
+ * Scans dirty/untracked files and committed diffs (`baseRef..HEAD`) on `handle` for paired conflict markers.
+ *
+ * Returns all repository-relative file paths containing `<<<<<<<` / `=======` / `>>>>>>>` marker blocks.
+ *
+ * @param {GitWorktreeHandle}             handle         - Worktree handle to scan.
+ * @param {readonly string[] | undefined} [excludeGlobs] - Optional glob patterns excluded from scanning.
+ *
+ * @returns {Promise<readonly string[]>} List of file paths containing paired conflict markers.
+ */
+export async function findWorktreeConflictMarkerPaths(handle, excludeGlobs) {
+    const snap = await gitCheckpointStatusMap(handle.worktreePath, { excludeGlobs });
+    const diffRes = await runGitCommand({
+        cwd: handle.worktreePath,
+        args: ['diff', '--name-only', '-z', handle.baseRef, 'HEAD'],
+        allowNonZeroExit: true,
+    });
+    const candidatePaths = new Set([
+        ...Object.keys(snap.statusMap),
+        ...diffRes.stdout.split('\0').filter((p) => p.length > 0),
+    ]);
+    const markerPaths = [];
+    for (const relPath of candidatePaths) {
+        if (snap.statusMap[relPath] === 'DELETED')
+            continue;
+        const content = await readFile(path.join(handle.worktreePath, relPath), 'utf8').catch(() => '');
+        if (hasPairedConflictMarkers(content))
+            markerPaths.push(relPath);
+    }
+    return Object.freeze(markerPaths);
+}
+/**
+ * Resolves the stacked-PR `baseBranch` for `rootHandle` when syncing onto `tipReceipt`.
+ *
+ * Runs `git fetch origin` (ignoring missing remotes) and checks whether `tipReceipt.branchName` is already merged into `origin/main`.
+ *
+ * @param {GitWorktreeHandle} rootHandle - Root worktree handle being synced.
+ * @param {GitScopeReceipt}   tipReceipt - Terminal scope receipt of the tip prerequisite run.
+ *
+ * @returns {Promise<string>} Resolved base branch name (`tipReceipt.branchName` when unmerged, or `'main'`).
+ */
+export async function resolvePrerequisiteBaseBranch(rootHandle, tipReceipt) {
+    await runGitCommand({ cwd: rootHandle.worktreePath, args: ['fetch', 'origin'], allowNonZeroExit: true });
+    const prereqBranch = tipReceipt.branchName;
+    if (prereqBranch === undefined || prereqBranch.length === 0) {
+        return rootHandle.baseBranch;
+    }
+    const isAncestor = await runGitCommand({
+        cwd: rootHandle.worktreePath,
+        args: ['merge-base', '--is-ancestor', tipReceipt.headRef, 'origin/main'],
+        allowNonZeroExit: true,
+    });
+    return isAncestor.exitCode === 0 ? 'main' : prereqBranch;
+}
+//# sourceMappingURL=parent-fast-forward.js.map

package/dist/executors/internal/parent-fast-forward.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent-fast-forward.js","sourceRoot":"","sources":["../../../src/executors/internal/parent-fast-forward.ts"],"names":[],"mappings":"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"}