nx 23.2.0-beta.7 → 23.2.0-beta.8

package/dist/src/command-line/migrate/run/state-lock.d.ts

@@ -0,0 +1,25 @@
+import { type MigrateRunState } from './run-state';
+/**
+ * Runs `fn` while holding the run's state lock, releasing it afterwards even
+ * if `fn` throws. writeRunState's tmp+rename gives per-write atomicity, but a
+ * writer that reads state, applies an event, then writes still races a second
+ * nx migrate process that read the same state first; this lock serializes
+ * those sequences so the event always applies to the freshest on-disk state.
+ */
+export declare function withRunStateLock<T>(runDirPath: string, fn: () => T): T;
+/**
+ * Serializes active-run discovery and run creation across nx migrate
+ * processes. Two concurrent inits could otherwise both observe "no active
+ * run" and create competing runs against the same workspace; the per-run
+ * state lock cannot cover that window because the run directory does not
+ * exist yet. Callers must redo their active-run check inside `fn`: a check
+ * done before acquiring the lock may predate a concurrent creation.
+ */
+export declare function withRunCreationLock<T>(root: string, fn: () => T): T;
+/**
+ * Reads the run state fresh under the lock, hands it to `apply`, and writes the
+ * result back. `apply` returning null means "no change" and skips the write.
+ * `apply` must be pure and synchronous; a corrupt or newer-format run.json
+ * propagates from the read.
+ */
+export declare function updateRunState(runDirPath: string, apply: (fresh: MigrateRunState) => MigrateRunState | null): MigrateRunState;

package/dist/src/command-line/migrate/run/state-lock.js

@@ -0,0 +1,76 @@
+"use strict";
+// Cross-process mutual exclusion for the migrate run flow, built on the
+// native flock-based FileLock (the same primitive the project graph uses to
+// serialize nx processes): acquisition blocks until the holder releases, and
+// the kernel releases a dead holder's lock automatically, so there is no
+// stale-lock state to detect or clean up. Under WASM the native lock is
+// unavailable and sections run unserialized, matching the project graph's
+// IS_WASM guard for this lock. Not part of run/'s public surface (not
+// re-exported via ./index): import directly within run/.
+//
+// Locked sections must stay synchronous. lock() blocks the whole thread, so
+// if a holder parked on an await while a second in-process caller reached
+// lock(), the holder's continuation could never run to release it. Git and
+// child-process side effects belong outside the lock for the same reason.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRunStateLock = withRunStateLock;
+exports.withRunCreationLock = withRunCreationLock;
+exports.updateRunState = updateRunState;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const native_1 = require("../../../native");
+const run_state_1 = require("./run-state");
+const STATE_LOCK_FILE_NAME = 'run.json.lock';
+const CREATION_LOCK_FILE_NAME = 'init.lock';
+function withFileLock(lockPath, fn) {
+    if (native_1.IS_WASM) {
+        return fn();
+    }
+    const lock = new native_1.FileLock(lockPath);
+    lock.lock();
+    try {
+        return fn();
+    }
+    finally {
+        lock.unlock();
+    }
+}
+/**
+ * Runs `fn` while holding the run's state lock, releasing it afterwards even
+ * if `fn` throws. writeRunState's tmp+rename gives per-write atomicity, but a
+ * writer that reads state, applies an event, then writes still races a second
+ * nx migrate process that read the same state first; this lock serializes
+ * those sequences so the event always applies to the freshest on-disk state.
+ */
+function withRunStateLock(runDirPath, fn) {
+    return withFileLock((0, path_1.join)(runDirPath, STATE_LOCK_FILE_NAME), fn);
+}
+/**
+ * Serializes active-run discovery and run creation across nx migrate
+ * processes. Two concurrent inits could otherwise both observe "no active
+ * run" and create competing runs against the same workspace; the per-run
+ * state lock cannot cover that window because the run directory does not
+ * exist yet. Callers must redo their active-run check inside `fn`: a check
+ * done before acquiring the lock may predate a concurrent creation.
+ */
+function withRunCreationLock(root, fn) {
+    const dir = (0, run_state_1.migrateRunsDir)(root);
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    return withFileLock((0, path_1.join)(dir, CREATION_LOCK_FILE_NAME), fn);
+}
+/**
+ * Reads the run state fresh under the lock, hands it to `apply`, and writes the
+ * result back. `apply` returning null means "no change" and skips the write.
+ * `apply` must be pure and synchronous; a corrupt or newer-format run.json
+ * propagates from the read.
+ */
+function updateRunState(runDirPath, apply) {
+    return withRunStateLock(runDirPath, () => {
+        const fresh = (0, run_state_1.readRunState)(runDirPath);
+        const next = apply(fresh);
+        if (next === null)
+            return fresh;
+        (0, run_state_1.writeRunState)(runDirPath, next);
+        return next;
+    });
+}

package/dist/src/command-line/migrate/run/state-machine.d.ts

@@ -0,0 +1,84 @@
+import type { CommitResult } from '../migrate-commits';
+import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
+import type { StepAction } from '../step-actions';
+export type { StepAction };
+export type StepEvent = {
+    type: 'dispense';
+    stepId: string;
+} | {
+    type: 'start';
+    stepId: string;
+    pid: number;
+    startedAt: string;
+} | {
+    type: 'succeed';
+    stepId: string;
+    finishedAt: string;
+    outcome?: MigrateStepOutcome;
+} | {
+    type: 'fail';
+    stepId: string;
+    finishedAt: string;
+    outcome?: MigrateStepOutcome;
+} | {
+    type: 'awaitPromptOutcome';
+    stepId: string;
+    finishedAt: string;
+} | {
+    type: 'foldPromptOutcome';
+    stepId: string;
+    attempt: number;
+    promptOutcome: MigrateStepPromptOutcome;
+} | {
+    type: 'markGeneratorCompleted';
+    stepId: string;
+} | {
+    type: 'markDied';
+    stepId: string;
+    attempt: number;
+} | {
+    type: 'stepAction';
+    stepId: string;
+    action: StepAction;
+    attempt: number;
+};
+export type ApplyStepEventResult = {
+    kind: 'ok';
+    state: MigrateRunState;
+} | {
+    kind: 'error';
+    reason: string;
+};
+export declare function applyStepEvent(state: MigrateRunState, event: StepEvent): ApplyStepEventResult;
+/**
+ * Records that the run could not install the dependency changes a step left
+ * behind. Not a {@link StepEvent}: it annotates a step instead of moving it,
+ * and every status can carry it, since the orchestrator marks a step it has
+ * just settled while the worker marks one it is about to fail.
+ */
+export declare function markInstallFailed(state: MigrateRunState, stepId: string): MigrateRunState;
+export declare function uncoveredFailedStepIds(state: MigrateRunState): string[];
+/**
+ * A step has commit debt when a 'failed' ledger entry names it and no later
+ * 'landed' entry also names it (checkpoint entries neither create nor cover
+ * debt). There is no per-step commit object; debt is always derived from the
+ * ledger.
+ */
+export declare function hasPendingCommitDebt(state: MigrateRunState): boolean;
+export declare function coveringLandedEntries(state: MigrateRunState, stepId: string): MigrateCommitLedgerEntry[];
+export declare function latestRound(state: MigrateRunState): MigrateRunState['rounds'][number] | undefined;
+export declare function splitMigrationId(id: string): {
+    package: string;
+    name: string;
+};
+export declare function stepsToPendingMigrations(state: MigrateRunState, stepIds: string[]): {
+    package: string;
+    name: string;
+}[];
+/**
+ * Classifies a commit attempt into the ledger entry to record, or null when
+ * there is nothing to record ('no-changes' / 'disabled'). A landed entry
+ * covers the absorbed steps too: the commit's `git add -A` captured their
+ * diffs. A failed entry records only this step's debt.
+ */
+export declare function commitResultToLedgerEntry(result: CommitResult, stepId: string, absorbedStepIds: string[]): MigrateCommitLedgerEntry | null;

package/dist/src/command-line/migrate/run/state-machine.js

@@ -0,0 +1,315 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyStepEvent = applyStepEvent;
+exports.markInstallFailed = markInstallFailed;
+exports.uncoveredFailedStepIds = uncoveredFailedStepIds;
+exports.hasPendingCommitDebt = hasPendingCommitDebt;
+exports.coveringLandedEntries = coveringLandedEntries;
+exports.latestRound = latestRound;
+exports.splitMigrationId = splitMigrationId;
+exports.stepsToPendingMigrations = stepsToPendingMigrations;
+exports.commitResultToLedgerEntry = commitResultToLedgerEntry;
+const PROMPT_OUTCOME_TO_STEP_STATUS = {
+    completed: 'succeeded',
+    skipped: 'skipped',
+    failed: 'failed',
+};
+function applyStepEvent(state, event) {
+    const index = state.steps.findIndex((s) => s.id === event.stepId);
+    if (index === -1) {
+        return {
+            kind: 'error',
+            reason: `No step with id '${event.stepId}' in run state.`,
+        };
+    }
+    const step = state.steps[index];
+    switch (event.type) {
+        case 'dispense':
+            // 'failed' and 'died' steps are re-armed to 'pending' by a stepAction
+            // first; this event never dispenses them directly.
+            if (step.status !== 'pending')
+                return illegal(step, event.type);
+            return commit(state, index, {
+                ...step,
+                status: 'dispensed',
+                dispenseCount: step.dispenseCount + 1,
+            });
+        case 'start':
+            if (step.status !== 'dispensed')
+                return illegal(step, event.type);
+            return commit(state, index, {
+                ...step,
+                status: 'running',
+                pid: event.pid,
+                startedAt: event.startedAt,
+            });
+        case 'succeed':
+            if (step.status !== 'running')
+                return illegal(step, event.type);
+            return commit(state, index, {
+                ...step,
+                status: 'succeeded',
+                finishedAt: event.finishedAt,
+                ...(event.outcome ? { outcome: event.outcome } : {}),
+            });
+        case 'fail':
+            if (step.status !== 'running')
+                return illegal(step, event.type);
+            return commit(state, index, {
+                ...step,
+                status: 'failed',
+                finishedAt: event.finishedAt,
+                ...(event.outcome ? { outcome: event.outcome } : {}),
+            });
+        case 'awaitPromptOutcome':
+            if (step.status !== 'running')
+                return illegal(step, event.type);
+            return commit(state, index, {
+                ...step,
+                status: 'awaiting-prompt-outcome',
+                finishedAt: event.finishedAt,
+            });
+        case 'markGeneratorCompleted':
+            if (step.status !== 'running')
+                return illegal(step, event.type);
+            return commit(state, index, { ...step, generatorCompleted: true });
+        case 'foldPromptOutcome':
+            if (step.status !== 'awaiting-prompt-outcome')
+                return illegal(step, event.type);
+            if (step.attempt !== event.attempt)
+                return staleAttempt(step, event.type, event.attempt);
+            return commit(state, index, {
+                ...step,
+                status: PROMPT_OUTCOME_TO_STEP_STATUS[event.promptOutcome.status],
+                promptOutcome: event.promptOutcome,
+            });
+        case 'markDied':
+            // A step awaiting a prompt outcome has no live process left to die;
+            // only a running step can.
+            if (step.status !== 'running')
+                return illegal(step, event.type);
+            if (step.attempt !== event.attempt)
+                return staleAttempt(step, event.type, event.attempt);
+            return commit(state, index, { ...step, status: 'died' });
+        case 'stepAction':
+            if (step.attempt !== event.attempt)
+                return staleAttempt(step, event.type, event.attempt);
+            return applyStepAction(state, index, step, event.action);
+        default: {
+            const exhaustive = event;
+            return exhaustive;
+        }
+    }
+}
+function applyStepAction(state, index, step, action) {
+    if (step.status === 'failed') {
+        switch (action) {
+            case 'retry':
+                // Nothing resets the tree, so the generator's changes are still in it.
+                // A pre-marker retry is additionally gated at the reconcile acceptance
+                // site, which can read the live tree; this pure layer cannot.
+                return commit(state, index, rearm(step, true));
+            case 'retry-clean':
+                // A failed generator can have written before throwing (a direct fs or
+                // exec side effect, or a crash mid-flush), so a reset-backed retry is
+                // offered under the same guard as for a death.
+                return commit(state, index, cleanRearm(state, step));
+            case 'skip':
+                return commit(state, index, { ...step, status: 'skipped' });
+        }
+    }
+    if (step.status === 'died') {
+        switch (action) {
+            case 'retry':
+                // Same no-reset rearm as from 'failed', and legal only once the
+                // generator half is recorded (or the step never had one): that is
+                // what leaves the redispensed worker something to do (a prompt, or
+                // the install and commit) other than reapplying the generator over
+                // its own changes.
+                if (step.generatorCompleted === true || step.hasGenerator === false) {
+                    return commit(state, index, rearm(step, true));
+                }
+                return {
+                    kind: 'error',
+                    reason: `Cannot apply action 'retry' to step '${step.id}': the worker died before recording that its generator ran, so keeping the current tree could apply the migration twice. Use 'retry-clean', 'adopt' or 'skip' instead.`,
+                };
+            case 'retry-clean':
+                return commit(state, index, cleanRearm(state, step));
+            case 'adopt':
+                return commit(state, index, {
+                    ...step,
+                    status: 'succeeded',
+                    outcome: { ...step.outcome, summary: adoptedSummary(step) },
+                });
+            case 'skip':
+                // Same as skipping a failure: the tree stays as the worker left it.
+                return commit(state, index, { ...step, status: 'skipped' });
+        }
+    }
+    return {
+        kind: 'error',
+        reason: `Cannot apply action '${action}' to step '${step.id}' in status '${step.status}'.`,
+    };
+}
+// Re-arms for a retry that resets the tree first. The reset target predates
+// the generator unless a commit of this step's own already carries it, so the
+// marker only survives when such a commit exists; otherwise the reset discards
+// the generator's changes and the retry has to run it again.
+function cleanRearm(state, step) {
+    return rearm(step, coveringLandedEntries(state, step.id).length > 0);
+}
+// An adopted death records how far the worker got, since 'succeeded' alone
+// says the migration was applied and cannot say by what.
+function adoptedSummary(step) {
+    return step.generatorCompleted === true
+        ? "Adopted after the worker died: its generator had run, and the working tree it left was taken as this migration's result."
+        : "Adopted after the worker died before recording that its generator had run; the working tree it left was taken as this migration's result.";
+}
+// Re-arms a step for a fresh attempt. Drops every field the previous attempt
+// wrote (pid, timestamps, git ref, tree state, outcomes) so a later success
+// can't carry a stale failure outcome; dispenseCount stays cumulative across
+// attempts.
+// `keepGeneratorCompleted` says whether the generator's changes reach the new
+// attempt. They do when nothing resets the tree, and when the reset target
+// already contains the commit that landed them; re-running the generator there
+// would apply them twice. They do not when the reset discards them, and
+// keeping the marker then would skip the generator and record a success for a
+// migration that never ran. The step kind is a plan fact, not an attempt's,
+// and always survives. So does the dependency baseline: it tracks
+// the last dependencies that were installed, so dropping it here would leave
+// the retry with nothing to detect the previous attempt's package.json edits.
+function rearm(step, keepGeneratorCompleted) {
+    return {
+        id: step.id,
+        roundIndex: step.roundIndex,
+        migrationId: step.migrationId,
+        status: 'pending',
+        attempt: step.attempt + 1,
+        dispenseCount: step.dispenseCount,
+        ...(step.hasGenerator !== undefined
+            ? { hasGenerator: step.hasGenerator }
+            : {}),
+        ...(step.depsHashAtDispense !== undefined
+            ? { depsHashAtDispense: step.depsHashAtDispense }
+            : {}),
+        ...(keepGeneratorCompleted && step.generatorCompleted
+            ? { generatorCompleted: true }
+            : {}),
+    };
+}
+// A guarded transition whose observation was made against an earlier attempt
+// of the same step: the status recurred, so the observation says nothing about
+// the attempt on disk now.
+function staleAttempt(step, eventType, observedAttempt) {
+    return {
+        kind: 'error',
+        reason: `Cannot apply '${eventType}' to step '${step.id}': it was observed on attempt ${observedAttempt} and the step is now on attempt ${step.attempt}.`,
+    };
+}
+function illegal(step, eventType) {
+    return {
+        kind: 'error',
+        reason: `Cannot apply '${eventType}' to step '${step.id}' in status '${step.status}'.`,
+    };
+}
+function commit(state, index, updatedStep) {
+    const nextSteps = state.steps.slice();
+    nextSteps[index] = updatedStep;
+    return { kind: 'ok', state: { ...state, steps: nextSteps } };
+}
+/**
+ * Records that the run could not install the dependency changes a step left
+ * behind. Not a {@link StepEvent}: it annotates a step instead of moving it,
+ * and every status can carry it, since the orchestrator marks a step it has
+ * just settled while the worker marks one it is about to fail.
+ */
+function markInstallFailed(state, stepId) {
+    return {
+        ...state,
+        steps: state.steps.map((s) => s.id === stepId ? { ...s, installFailed: true } : s),
+    };
+}
+// Step ids named by a 'failed' ledger entry with no later 'landed' entry
+// covering them.
+function uncoveredFailedStepIds(state) {
+    const uncovered = new Set();
+    const { commits } = state;
+    for (let i = 0; i < commits.length; i++) {
+        if (commits[i].kind !== 'failed')
+            continue;
+        for (const stepId of commits[i].stepIds) {
+            const covered = commits
+                .slice(i + 1)
+                .some((c) => c.kind === 'landed' && c.stepIds.includes(stepId));
+            if (!covered)
+                uncovered.add(stepId);
+        }
+    }
+    return [...uncovered];
+}
+/**
+ * A step has commit debt when a 'failed' ledger entry names it and no later
+ * 'landed' entry also names it (checkpoint entries neither create nor cover
+ * debt). There is no per-step commit object; debt is always derived from the
+ * ledger.
+ */
+function hasPendingCommitDebt(state) {
+    return uncoveredFailedStepIds(state).length > 0;
+}
+// The 'landed' ledger entries naming the given step, in ledger order.
+function coveringLandedEntries(state, stepId) {
+    return state.commits.filter((commit) => commit.kind === 'landed' && commit.stepIds.includes(stepId));
+}
+// The round with the highest index.
+function latestRound(state) {
+    return state.rounds.reduce((newest, round) => (!newest || round.index > newest.index ? round : newest), undefined);
+}
+// '<package>:<name>' splits on the first ':', leaving names that contain a ':'
+// intact; a bare id has no package.
+function splitMigrationId(id) {
+    const colon = id.indexOf(':');
+    return colon === -1
+        ? { package: '', name: id }
+        : { package: id.slice(0, colon), name: id.slice(colon + 1) };
+}
+// Maps absorbed step ids to `{package, name}` for the commit body; an id with
+// no matching step, or one whose migration id carries no package, can't be
+// attributed there.
+function stepsToPendingMigrations(state, stepIds) {
+    const pending = [];
+    for (const id of stepIds) {
+        const migrationId = state.steps.find((s) => s.id === id)?.migrationId;
+        if (!migrationId)
+            continue;
+        const { package: pkg, name } = splitMigrationId(migrationId);
+        if (!pkg)
+            continue;
+        pending.push({ package: pkg, name });
+    }
+    return pending;
+}
+/**
+ * Classifies a commit attempt into the ledger entry to record, or null when
+ * there is nothing to record ('no-changes' / 'disabled'). A landed entry
+ * covers the absorbed steps too: the commit's `git add -A` captured their
+ * diffs. A failed entry records only this step's debt.
+ */
+function commitResultToLedgerEntry(result, stepId, absorbedStepIds) {
+    switch (result.status) {
+        case 'committed':
+            return {
+                kind: 'landed',
+                ...(result.sha ? { sha: result.sha } : {}),
+                stepIds: [stepId, ...absorbedStepIds],
+            };
+        case 'failed':
+            return { kind: 'failed', stepIds: [stepId] };
+        case 'no-changes':
+        case 'disabled':
+            return null;
+        default: {
+            const exhaustive = result;
+            return exhaustive;
+        }
+    }
+}

package/dist/src/command-line/migrate/run/util.d.ts

@@ -1 +1,59 @@
+import type { MigrateStep } from './run-state';
+export declare function nowIso(): string;
+/**
+ * Fingerprints the workspace dependencies so a step can persist what they
+ * looked like and a later actor can still tell whether the migration changed
+ * them. Hashed rather than stored verbatim to keep run.json small; the value
+ * is only ever compared for equality.
+ *
+ * `null` means the probe itself failed. Callers must not read that as
+ * "unchanged": the value is persisted and compared across processes, so a
+ * failed read on either end would otherwise silently skip an install that was
+ * needed.
+ */
+export declare function depsHash(root: string): string | null;
+/**
+ * Installs when the workspace dependencies differ from the step's recorded
+ * baseline, so a prompt applied by another actor, or a retry that only has the
+ * commit left to do, still installs what the changes need. Comparing against
+ * the persisted baseline is what makes that possible: by the time either runs,
+ * the edits are already on disk, so a snapshot taken here would see them as
+ * the starting point and never detect a change.
+ *
+ * The baseline is re-pointed at the current dependencies once the install
+ * lands, so the next actor to compare does not install the same change again.
+ *
+ * Every probe failure installs, on either end of the comparison. A step whose
+ * dispense-time probe failed has no baseline, which says the dependencies it
+ * started from are unknown rather than unchanged, and skipping there would
+ * strand the change with nothing left to detect it.
+ */
+export declare function installDepsChangedSinceDispense(root: string, dir: string, step: MigrateStep, skipInstall: boolean, rerunCommand?: string): Promise<void>;
+/**
+ * Records what an install that just landed means for the run: the installing
+ * step's dependency baseline moves to what is now on disk, and every step's
+ * install-failure mark clears.
+ *
+ * The baseline has to move, or the next actor to compare (the prompt fold, a
+ * retry, the step's own commit) reads the step's own edits as an unapplied
+ * change and pays a second full install. The marks clear because the package
+ * manager installs the whole workspace package.json, so this install also
+ * covers the dependency edits of every earlier step that failed to install its
+ * own.
+ *
+ * A failed probe leaves the baseline alone: an install that runs twice costs
+ * time, one that never runs leaves the workspace inconsistent with its
+ * package.json.
+ *
+ * Never throws. It runs inside callers that treat a throw as "the install
+ * failed", and the install has already succeeded by then. A run state this
+ * cannot read or write is a real problem, but it is reported by the next
+ * mandatory write rather than misattributed here, and the only cost of losing
+ * this one is a redundant install later.
+ */
+export declare function recordInstallLanded(root: string, dir: string, stepId: string): void;
+export declare function isPidAlive(pid: number): boolean;
+export declare function summarizeError(e: unknown): string;
+export declare function warnCommitFailed(name: string, cause?: unknown): void;
 export declare function pmExecPrefix(root: string): string;
+export declare function pmInstallCommand(root: string): string;