@teambit/ci 1.0.485 → 1.0.487

package/dist/sync/lane-sync-executor.d.ts

@@ -0,0 +1,256 @@
+import type { Logger } from '@teambit/logger';
+import type { LanesMain } from '@teambit/lanes';
+import type { LaneData } from '@teambit/legacy.scope';
+import type { CiMain } from '../ci.main.runtime';
+import type { CiSyncConfig, LaneTarget } from './sync-config';
+import type { GitHostProvider } from './git-host-provider';
+import type { BranchKeepReason, LaneSyncAction } from './sync-planner';
+/**
+ * Prefix of the summary line for a lane that could not be reconciled. `syncLane` deliberately does
+ * NOT throw on halt — one unreconcilable lane must not abort the rest of the run; the command layer
+ * scans for this prefix to decide the exit code.
+ */
+export declare const HALT_SUMMARY_PREFIX = "HALTED";
+/**
+ * Prefix for a target the reconciler refuses. Unlike a halt, nothing is mid-flight and no PR is
+ * annotated — the run exits non-zero, but the command layer reports a plain refusal rather than a
+ * sync conflict.
+ */
+export declare const REFUSED_SUMMARY_PREFIX = "REFUSED";
+export type LaneSyncDeps = {
+    lanes: LanesMain;
+    /** for snapPrCommit + getDefaultBranchName + switchToLaneForSync */
+    ci: CiMain;
+    logger: Logger;
+    /** undefined => PR operations are logged and skipped; the git half of the sync still runs. */
+    gitHost?: GitHostProvider;
+    cfg: Required<CiSyncConfig>;
+    defaultScope: string;
+};
+/**
+ * Fingerprint of a lane's content — same primitive as `branchStateFingerprint`, so "equal" means
+ * exactly "the branch records every lane component at the lane's head".
+ *
+ * We deliberately do NOT use `LaneData.hash`: that hash is minted randomly at lane-creation time
+ * and does not change when the lane's components advance. This is derived from content instead.
+ */
+export declare function laneHeadFingerprint(components: LaneData['components']): string;
+/**
+ * The lane's components that do not belong to `defaultScope`. A lane may span scopes, and the
+ * reconciler acts on a lane whole (fingerprint, materialize, snap, export), so foreign content is
+ * refused rather than written into this repository. Soft-deleted components and `updateDependents`
+ * entries are deliberately not read — the reconciler never materializes or exports them either.
+ */
+export declare function foreignLaneComponents(components: LaneData['components'], defaultScope: string): string[];
+/**
+ * `entries`, capped at `max`, with a final "…and K more" entry. The bound is on entries, not rendered
+ * length, so a markdown list is never cut mid-line. `overflowPrefix` carries the caller's list marker
+ * onto the summary line.
+ */
+export declare function capEntries(entries: string[], overflowPrefix?: string, max?: number): string[];
+/** The shared clause describing why a lane is cross-scope, used by the skip/refusal/halt outcomes. */
+export declare function crossScopeDescription(foreignIds: string[], defaultScope: string): string;
+/**
+ * A cross-scope lane that was merely enumerated: a skip, and the run stays green — a standing, valid
+ * lane must not turn every scheduled run permanently red.
+ */
+export declare function crossScopeSkipSummary(laneName: string, foreignIds: string[], defaultScope: string): string;
+/**
+ * A cross-scope lane the user named explicitly: exits non-zero with the explanation. A refusal, not a
+ * halt — no PR is labelled, no branch is written. `existingBranch` keeps the closing sentence truthful
+ * when a branch of that name already exists.
+ */
+export declare function crossScopeRefusal(foreignIds: string[], defaultScope: string, existingBranch?: string): string;
+/**
+ * Halt reason for a branch that is the live mirror of a different lane — two lanes with the same name
+ * in different scopes map to the same branch. Names both ids so the human can tell which owns it.
+ */
+export declare function branchMirrorsOtherLaneReason(branch: string, mirroredLaneIdStr: string, laneIdStr: string): string;
+/**
+ * PR comment for the branch-aliasing halt — the one halt whose PR belongs to a DIFFERENT lane. It must
+ * not carry the default "import the lane" steps, which would perform the overwrite the halt prevented.
+ */
+export declare function branchMirrorsOtherLaneNote(mirroredLaneIdStr: string, laneIdStr: string): string;
+/**
+ * A lane that became cross-scope after this repository had already mirrored it onto a branch — the one
+ * cross-scope shape that is a genuine halt: the pair is mid-flight and can no longer converge.
+ */
+export declare function crossScopeMidFlightHaltReason(branch: string, foreignIds: string[], defaultScope: string): string;
+/**
+ * Branches `executeClosePr` refuses to delete whatever the ownership evidence concluded — an
+ * unconditional guard at the one site that deletes remote branches.
+ */
+export declare function isProtectedBranch(branch: string, defaultBranch: string, mainSyncBranch: string): boolean;
+/**
+ * The summary line a dry run reports for a planned action. A planned halt carries the same prefix the
+ * real run would: `summarizeSync` recognizes that prefix and nothing else, so without it a `--dry-run`
+ * exits 0 on a plan that needs a human. Refusals never reach here — they are returned before planning.
+ */
+export declare function dryRunSummaryLine(laneName: string, action: LaneSyncAction): string;
+/** Why each `BranchKeepReason` withheld the deletion — one wording for the PR comment and the summary. */
+export declare const KEPT_BECAUSE: Record<BranchKeepReason, string>;
+export declare class LaneSyncExecutor {
+    private deps;
+    constructor(deps: LaneSyncDeps);
+    /** Every `origin/<ref>` read assumes current remote refs; fetch once per executor, not per lane. */
+    private fetched;
+    /**
+     * Reconcile one lane with its git branch/PR. Returns a summary line (HALT/REFUSED prefixed on
+     * failure) and NEVER throws — the contract the `--all` loop is written against, for every failure
+     * mode: the steps route expected failures to `executeHalt`, this wrapper covers the unexpected ones.
+     */
+    syncLane(target: LaneTarget, opts?: {
+        dryRun?: boolean;
+        /** The user named this lane on the command line; decides how a cross-scope lane is reported. */
+        explicitTarget?: boolean;
+    }): Promise<string>;
+    private reconcileLane;
+    /**
+     * What a cross-scope lane means for this repository: a mid-flight halt when the branch is this
+     * lane's live mirror (checked first — the problem is the state of the pair, not the phrasing of the
+     * request); a refusal when the user named the lane explicitly; otherwise an enumerated skip that
+     * stays green — one standing cross-scope lane must not fail every scheduled run forever.
+     */
+    private crossScopeOutcome;
+    /**
+     * Mirror the remote lane onto the branch: check the branch out, materialize the lane into the
+     * workspace, and commit the result. The committed `.bitmap` IS the record of the branch's state.
+     */
+    private executeImportLane;
+    /**
+     * Push the branch's dev commits back onto the lane: snap+export the branch's tree, then commit the
+     * resulting `.bitmap` back onto the branch so the next run sees the two sides as converged.
+     */
+    private executeExportBranch;
+    /**
+     * Both sides moved since the last sync. Order is load-bearing: (1) merge the lane into the branch's
+     * working tree (`bit checkout head`; conflicts halt or auto-resolve per `sync.onConflict`), (2) snap
+     * + export the merged tree — the snap IS the merge, (3) commit the resulting `.bitmap` back onto the
+     * branch. The merge cannot be skipped: the export path's switch runs under `forceOurs`, which never
+     * touches the filesystem, so a bare export would silently revert every lane-side file edit and then
+     * assert convergence over the loss. Never throws; anything unexpected halts.
+     */
+    private executeMergeDiverged;
+    /**
+     * Snap the workspace's current tree onto the lane and export it; returns the error so the caller can
+     * halt. Snaps WHATEVER is in the workspace (the switch uses `forceOurs` and never merges files), so
+     * a diverged tree must already hold the merged content. `keepLane` preserves the lane's history,
+     * `skipCleanup` keeps the snap's `.bitmap` for the caller to commit, `noDestructiveRecovery` turns
+     * stale-lane recovery (delete + re-fork the remote lane) into a throw. The lane object must be
+     * imported BEFORE delegating: a switch onto the lane the workspace is already on no-ops before any
+     * fetch, so it never warms a cold scope.
+     */
+    private snapAndExportOntoLane;
+    /**
+     * Record on the branch which lane state it now mirrors: re-query the lane (the export just moved it,
+     * so any earlier fingerprint is stale), commit — crucially the `.bitmap` the snap rewrote — and push.
+     * Returns undefined when the lane can no longer be read, in which case the caller halts.
+     */
+    private recordLaneHeadOnBranch;
+    /**
+     * Merge the lane's snaps into the branch's working tree via `bit checkout head` (three-way merge,
+     * base = the branch's `.bitmap` version; `workspaceOnly` must stay false so lane-only components are
+     * added). Returns conflicted ids + file count rather than throwing. Not `mergeLanes.mergeLane`: both
+     * sides here are the same lane id, which `validateMergeFlags` rejects, and `mergeLane` refuses to
+     * run with modified components — exactly the branch's state here.
+     */
+    private mergeLaneIntoBranchWorkingTree;
+    /**
+     * Put the working tree on `branch` at a pristine copy of `startPoint` and reload the `.bitmap` it
+     * brings (see `checkoutPristine`), so no leftover from a previous lane leaks into this lane's sync
+     * commit and the following bit operation resolves against this branch's `.bitmap`. Also the recovery
+     * after a merge attempt: resetting to `origin/<branch>` puts both sides back on the fetched tip.
+     */
+    private checkoutFromRemote;
+    /**
+     * The reachability half of `LaneOwnershipEvidence`; the attribution half lives at the call site.
+     * An unanswerable question resolves to `inherited-or-none` — every other answer permits deleting a
+     * branch, and a failed `merge-base` is not evidence of anything. A foreign-hosted lane's branch
+     * reached by branch name attributes as `inherited-or-none` (scope mismatch), which is the safe
+     * direction: left alone, never retired.
+     */
+    private assessBranchOwnership;
+    /**
+     * The lane is gone from bit.cloud — close its PR, and retire the branch if the claim on it allows.
+     * Deleting the branch is the one irreversible thing this command does; `keepReason` distinguishes
+     * "work that exists nowhere else" from "we did not write the tip".
+     */
+    private executeClosePr;
+    /** Seams for the retirement path, so the one irreversible outcome is unit-testable without a remote. */
+    private currentBranchTip;
+    private pushBranchDeletion;
+    /**
+     * Record a halt without touching the PR on a dry run — `--dry-run` promises no PR writes, and
+     * labelling freezes a lane's syncs. The line stays HALT-prefixed either way. Every pre-planning halt
+     * goes through here so the guard cannot be forgotten at one site.
+     */
+    private haltOrReport;
+    /**
+     * Hand the lane back to a human: label the PR so subsequent runs skip it, and comment the resolution
+     * steps. `commentNote` replaces the default steps for halts where they would be wrong.
+     */
+    private executeHalt;
+    /**
+     * Drive the workspace's filesystem to the remote lane's content; returns the error so the caller can
+     * halt. Two traps make a plain `switchToLane` insufficient: (1) it defaults to `forceOurs`, which
+     * never touches the filesystem — the commit would claim the branch mirrors the lane over the default
+     * branch's files — so `forceOurs` is cleared and `forceTheirs` set; (2) switching onto the lane the
+     * workspace already sits on throws "already checked out", which `switchToLane` swallows as success
+     * and nothing materializes — so step off to main first.
+     */
+    private materializeLane;
+    private fetchOnce;
+    /**
+     * The remote lane's data, or undefined when the lane no longer exists. The remote queried must be
+     * the lane's HOSTING scope: asking `defaultScope` for a lane it does not host answers "was not
+     * found" — the input that drives `close-pr`, which deletes branches.
+     */
+    private getRemoteLane;
+    /**
+     * The open PR for the branch, if any. A git-host API hiccup degrades to "no PR known" rather than
+     * failing the lane — the git side of the sync is still correct and the next run re-reads the PR.
+     */
+    private findPr;
+    /**
+     * The subject of the newest commit on the branch that isn't one of our own sync commits — it's
+     * the developer's own description of the change, and becomes the snap message on the lane.
+     */
+    private lastNonSyncCommitMessage;
+    /**
+     * Stage everything, commit with the annotated sync message, and push. NEVER force-pushes: a rejected
+     * push means someone pushed concurrently and the next run should re-plan rather than clobber.
+     * `--allow-empty` is only insurance against `git commit` failing the lane outright.
+     */
+    private commitAllAndPush;
+    private openPrForLane;
+    /**
+     * Put the workspace back on main with the default branch checked out. Best-effort, warn-only, so a
+     * restore hiccup can't throw out of a `finally` and mask the real error. The checkout is forced
+     * (switching back to main rewrites `.bitmap`); the scoped clean discards files a halted lane
+     * materialized but never committed, which would otherwise be staged onto the NEXT lane's branch;
+     * the reload makes the next lane resolve against the right checkout. This is a checkout, never a
+     * push — and `MainSyncExecutor.restoreWorkspace` must not diverge from it.
+     */
+    private restoreWorkspace;
+}
+/**
+ * The body of the pull request that mirrors a lane onto a branch. The component list is capped so the
+ * body stays inside the git host's size limit however large the lane is; the total is not.
+ */
+export declare function laneSyncPrBody({ laneIdStr, laneUrl, branch, laneHead, components, }: {
+    laneIdStr: string;
+    laneUrl: string;
+    branch: string;
+    laneHead: string;
+    components: LaneData['components'];
+}): string;
+/**
+ * Resolution instructions posted on a halted PR. `note` replaces the default steps for halts where
+ * they do not apply (the branch-aliasing halt, whose PR belongs to a different lane).
+ */
+export declare function haltCommentBody({ reason, branch, laneId, note, }: {
+    reason: string;
+    branch: string;
+    laneId: string;
+    note?: string;
+}): string;