@depup/nx 23.2.1-depup.8 → 23.3.0-depup.0

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

@@ -1,14 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyStepEvent = applyStepEvent;
+exports.discardGeneratorRun = discardGeneratorRun;
+exports.tallySteps = tallySteps;
+exports.runTallies = runTallies;
+exports.unresolvedFailureDetail = unresolvedFailureDetail;
+exports.completionSummaryLines = completionSummaryLines;
+exports.unresolvedCommitName = unresolvedCommitName;
+exports.commitNameForStep = commitNameForStep;
 exports.markInstallFailed = markInstallFailed;
 exports.uncoveredFailedStepIds = uncoveredFailedStepIds;
 exports.hasPendingCommitDebt = hasPendingCommitDebt;
 exports.coveringLandedEntries = coveringLandedEntries;
+exports.markCommitStarted = markCommitStarted;
+exports.clearCommitStarted = clearCommitStarted;
+exports.commitMayBeInHistory = commitMayBeInHistory;
+exports.appendCommit = appendCommit;
+exports.commitReceipt = commitReceipt;
 exports.latestRound = latestRound;
+exports.stepNoun = stepNoun;
+exports.stepLabel = stepLabel;
 exports.splitMigrationId = splitMigrationId;
 exports.stepsToPendingMigrations = stepsToPendingMigrations;
+exports.gitRan = gitRan;
 exports.commitResultToLedgerEntry = commitResultToLedgerEntry;
+const text_1 = require("../text");
 const PROMPT_OUTCOME_TO_STEP_STATUS = {
     completed: 'succeeded',
     skipped: 'skipped',
@@ -68,11 +84,37 @@ function applyStepEvent(state, event) {
                 ...step,
                 status: 'awaiting-prompt-outcome',
                 finishedAt: event.finishedAt,
+                awaitingKind: event.awaitingKind,
+            });
+        case 'parkForFinalValidation':
+            if (step.kind !== 'final-validation') {
+                return {
+                    kind: 'error',
+                    reason: `Cannot apply '${event.type}' to step '${step.id}': it is a ${step.kind} step.`,
+                };
+            }
+            if (step.status !== 'pending')
+                return illegal(step, event.type);
+            return commit(state, index, {
+                ...step,
+                status: 'awaiting-prompt-outcome',
+                dispenseCount: step.dispenseCount + 1,
+                finishedAt: event.finishedAt,
+                awaitingKind: 'final-validation',
             });
         case 'markGeneratorCompleted':
             if (step.status !== 'running')
                 return illegal(step, event.type);
-            return commit(state, index, { ...step, generatorCompleted: true });
+            return commit(state, index, {
+                ...step,
+                generatorCompleted: true,
+                generatorCompletedAtAttempt: step.attempt,
+                ...(event.agenticWaived ? { agenticWaived: true } : {}),
+                ...(event.validationOwed ? { validationOwed: true } : {}),
+                // Written even when false, unlike the conditional spreads above: absent is
+                // reserved for markers an older nx wrote.
+                generatorMadeChanges: event.madeChanges,
+            });
         case 'foldPromptOutcome':
             if (step.status !== 'awaiting-prompt-outcome')
                 return illegal(step, event.type);
@@ -114,8 +156,20 @@ function applyStepAction(state, index, step, action) {
                 // 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 'adopt':
+                return commit(state, index, adopt(step));
             case 'skip':
-                return commit(state, index, { ...step, status: 'skipped' });
+            case 'unresolved':
+                if (commitMayBeInHistory(state, step)) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action '${action}' to step '${step.id}': a commit of its changes landed or was started and never recorded, so the ${stepNoun(step)} may be committed. Use 'adopt' to record it as applied once the ${stepNoun(step)} is finished.`,
+                    };
+                }
+                return commit(state, index, {
+                    ...step,
+                    status: action === 'skip' ? 'skipped' : 'unresolved',
+                });
         }
     }
     if (step.status === 'died') {
@@ -131,19 +185,44 @@ function applyStepAction(state, index, step, action) {
                 }
                 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.`,
+                    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 ${commitMayBeInHistory(state, step)
+                        ? `'retry-clean' where offered, or 'adopt'`
+                        : `'retry-clean', 'adopt', 'skip' or 'unresolved'`} instead.`,
                 };
             case 'retry-clean':
                 return commit(state, index, cleanRearm(state, step));
             case 'adopt':
+                return commit(state, index, adopt(step));
+            case 'skip': {
+                if (coveringLandedEntries(state, step.id).length > 0) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action 'skip' to step '${step.id}': a commit of its changes already landed, so the migration is applied. Use 'adopt' to record that.`,
+                    };
+                }
+                if (step.commitStarted === true) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action 'skip' to step '${step.id}': a commit of its changes was started and never recorded, so it may be in history. Use 'adopt' to record the migration as applied.`,
+                    };
+                }
+                // Same as skipping a failure: the tree stays as the worker left it.
+                return commit(state, index, { ...step, status: 'skipped' });
+            }
+            case 'unresolved':
+                if (commitMayBeInHistory(state, step)) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action 'unresolved' to step '${step.id}': a commit of its changes landed or was started and never recorded, so the migration may be committed. Use 'adopt' to record it as applied once the migration is finished.`,
+                    };
+                }
+                // A death records no outcome, so the failure given up on is the death
+                // itself.
                 return commit(state, index, {
                     ...step,
-                    status: 'succeeded',
-                    outcome: { ...step.outcome, summary: adoptedSummary(step) },
+                    status: 'unresolved',
+                    outcome: { summary: workerDiedSummary(step) },
                 });
-            case 'skip':
-                // Same as skipping a failure: the tree stays as the worker left it.
-                return commit(state, index, { ...step, status: 'skipped' });
         }
     }
     return {
@@ -151,6 +230,9 @@ function applyStepAction(state, index, step, action) {
         reason: `Cannot apply action '${action}' to step '${step.id}' in status '${step.status}'.`,
     };
 }
+function workerDiedSummary(step) {
+    return `the worker process${step.pid === undefined ? '' : ` (pid ${step.pid})`} died before recording an outcome`;
+}
 // 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
@@ -158,31 +240,39 @@ function applyStepAction(state, index, step, action) {
 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 adopt(step) {
+    return {
+        ...step,
+        status: 'succeeded',
+        adopted: true,
+        outcome: { ...step.outcome, summary: adoptedSummary(step) },
+    };
+}
 function adoptedSummary(step) {
+    if (step.status === 'failed') {
+        return `Adopted after the attempt failed: the working tree as it stood was taken as this ${stepNoun(step)}'s result.`;
+    }
     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.
+// Rebuilds the step for a fresh attempt so a stale outcome cannot survive;
+// 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.
+// migration that never ran. The step kind and generator flag are plan facts,
+// not an attempt's, and always survive. 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,
+        ...stepKindFields(step),
         status: 'pending',
         attempt: step.attempt + 1,
         dispenseCount: step.dispenseCount,
@@ -192,11 +282,130 @@ function rearm(step, keepGeneratorCompleted) {
         ...(step.depsHashAtDispense !== undefined
             ? { depsHashAtDispense: step.depsHashAtDispense }
             : {}),
-        ...(keepGeneratorCompleted && step.generatorCompleted
-            ? { generatorCompleted: true }
+        // A reset keeps a commit that landed before this attempt's ref as well.
+        ...(step.commitStarted ? { commitStarted: true } : {}),
+        ...(keepGeneratorCompleted ? generatorRunFields(step) : {}),
+    };
+}
+function generatorRunFields(step) {
+    if (!step.generatorCompleted)
+        return {};
+    return {
+        generatorCompleted: true,
+        ...(step.generatorCompletedAtAttempt !== undefined
+            ? { generatorCompletedAtAttempt: step.generatorCompletedAtAttempt }
+            : {}),
+        ...(step.agenticWaived ? { agenticWaived: true } : {}),
+        ...(step.validationOwed ? { validationOwed: true } : {}),
+        ...(step.generatorMadeChanges !== undefined
+            ? { generatorMadeChanges: step.generatorMadeChanges }
             : {}),
     };
 }
+/**
+ * Forgets the generator run of `stepId`'s current attempt, unless a landed
+ * commit already carries its changes.
+ */
+function discardGeneratorRun(state, stepId) {
+    if (coveringLandedEntries(state, stepId).length > 0)
+        return state;
+    return {
+        ...state,
+        steps: state.steps.map((step) => {
+            if (step.id !== stepId || !step.generatorCompleted)
+                return step;
+            const { generatorCompleted: _completed, generatorCompletedAtAttempt: _atAttempt, agenticWaived: _waived, validationOwed: _owed, generatorMadeChanges: _madeChanges, ...rest } = step;
+            return rest;
+        }),
+    };
+}
+function tallySteps(state) {
+    const tally = {
+        applied: 0,
+        adopted: 0,
+        skipped: 0,
+        unresolved: [],
+        remaining: 0,
+        stalled: 0,
+    };
+    for (const step of state.steps) {
+        switch (step.status) {
+            case 'succeeded':
+                if (step.adopted)
+                    tally.adopted++;
+                else
+                    tally.applied++;
+                break;
+            case 'skipped':
+                tally.skipped++;
+                break;
+            case 'unresolved':
+                tally.unresolved.push(step);
+                break;
+            case 'failed':
+            case 'died':
+                tally.stalled++;
+                tally.remaining++;
+                break;
+            case 'pending':
+            case 'dispensed':
+            case 'running':
+            case 'awaiting-prompt-outcome':
+                tally.remaining++;
+                break;
+            default: {
+                const exhaustive = step.status;
+                throw new Error(`Unhandled step status '${exhaustive}'.`);
+            }
+        }
+    }
+    return tally;
+}
+function runTallies(state) {
+    const tally = tallySteps(state);
+    return {
+        completed: tally.applied + tally.adopted,
+        skipped: tally.skipped,
+        unresolved: tally.unresolved.length,
+        dispenseCount: state.steps.reduce((n, s) => n + s.dispenseCount, 0),
+    };
+}
+// The failure a given-up step is reported with, in the issue ledger and the
+// completion report alike. Agent text is collapsed to one line so a break
+// inside it cannot open a block at a line start; an accepted handoff may carry
+// an empty summary, which gets the fallback.
+function unresolvedFailureDetail(step) {
+    const failure = (0, text_1.singleLine)(step.outcome?.summary ?? step.promptOutcome?.summary ?? '').trim();
+    return failure.length === 0 ? 'no failure detail was recorded' : failure;
+}
+function completionSummaryLines(state) {
+    const tally = tallySteps(state);
+    return [
+        `  applied: ${tally.applied}`,
+        `  adopted: ${tally.adopted}`,
+        `  skipped: ${tally.skipped}`,
+        `  unresolved: ${tally.unresolved.length}`,
+        ...tally.unresolved.map((step) => `    - ${stepLabel(step)}: ${unresolvedFailureDetail(step)}`),
+    ];
+}
+// Suffixed so history does not read the partial result as the migration
+// applied.
+function unresolvedCommitName(step) {
+    return `${commitNameForStep(step)} (unresolved)`;
+}
+// Takes the place after the commit prefix in a step's commits.
+function commitNameForStep(step) {
+    switch (step.kind) {
+        case 'migration':
+            return splitMigrationId(step.migrationId).name;
+        case 'final-validation':
+            return 'final validation';
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unhandled step kind '${exhaustive}'.`);
+        }
+    }
+}
 // 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.
@@ -260,10 +469,96 @@ function hasPendingCommitDebt(state) {
 function coveringLandedEntries(state, stepId) {
     return state.commits.filter((commit) => commit.kind === 'landed' && commit.stepIds.includes(stepId));
 }
+function markCommitStarted(state, stepId) {
+    return {
+        ...state,
+        steps: state.steps.map((step) => step.id === stepId ? { ...step, commitStarted: true } : step),
+    };
+}
+function clearCommitStarted(state, stepId) {
+    return {
+        ...state,
+        steps: state.steps.map((step) => {
+            if (step.id !== stepId || !step.commitStarted)
+                return step;
+            const { commitStarted: _started, ...rest } = step;
+            return rest;
+        }),
+    };
+}
+/**
+ * True when a landed entry names the step, or a commit was started for it
+ * that no entry accounts for. Skipping the step would then report as not
+ * applied a migration whose commit is, or may be, in history.
+ */
+function commitMayBeInHistory(state, step) {
+    return (coveringLandedEntries(state, step.id).length > 0 ||
+        step.commitStarted === true);
+}
+// Every ledger append. Entries are never removed or reordered: step receipts
+// and resolution stamps index into the ledger. A failed entry says nothing
+// about an earlier commit, so only a landed one clears the mark.
+function appendCommit(state, entry) {
+    const accounted = entry.kind === 'landed'
+        ? entry.stepIds.reduce(clearCommitStarted, state)
+        : state;
+    return { ...accounted, commits: [...state.commits, entry] };
+}
+/**
+ * The entry a parent session recorded for this attempt's commit, or undefined
+ * without a receipt. A receipt past the ledger or naming another step is
+ * corrupt run state, so it throws.
+ */
+function commitReceipt(state, step) {
+    const index = step.commitLedgerIndex;
+    if (index === undefined)
+        return undefined;
+    const entry = state.commits[index];
+    if (!entry || !entry.stepIds.includes(step.id)) {
+        throw new Error(`Step ${step.id} records its commit at ledger index ${index}, which ${entry ? 'does not name it' : 'does not exist'}.`);
+    }
+    return { index, entry };
+}
 // The round with the highest index.
 function latestRound(state) {
     return state.rounds.reduce((newest, round) => (!newest || round.index > newest.index ? round : newest), undefined);
 }
+function stepKindFields(step) {
+    switch (step.kind) {
+        case 'migration':
+            return { kind: 'migration', migrationId: step.migrationId };
+        case 'final-validation':
+            return { kind: 'final-validation' };
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unhandled step kind '${exhaustive}'.`);
+        }
+    }
+}
+function stepNoun(step) {
+    switch (step.kind) {
+        case 'migration':
+            return 'migration';
+        case 'final-validation':
+            return 'validation pass';
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unhandled step kind '${exhaustive}'.`);
+        }
+    }
+}
+function stepLabel(step) {
+    switch (step.kind) {
+        case 'migration':
+            return step.migrationId;
+        case 'final-validation':
+            return 'the final validation pass';
+        default: {
+            const exhaustive = step;
+            throw new Error(`Unhandled step kind '${exhaustive}'.`);
+        }
+    }
+}
 // '<package>:<name>' splits on the first ':', leaving names that contain a ':'
 // intact; a bare id has no package.
 function splitMigrationId(id) {
@@ -273,21 +568,39 @@ function splitMigrationId(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.
+// no matching step, a step that ran no migration, 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)
+        const step = state.steps.find((s) => s.id === id);
+        if (step?.kind !== 'migration')
             continue;
-        const { package: pkg, name } = splitMigrationId(migrationId);
+        const { package: pkg, name } = splitMigrationId(step.migrationId);
         if (!pkg)
             continue;
         pending.push({ package: pkg, name });
     }
     return pending;
 }
+// Whether git may have written history for this result. A landed commit's
+// mark is the ledger entry's to clear, and a failure reported once git ran
+// (a hook's output overflowing the subprocess buffer after the commit) cannot
+// vouch that nothing landed, so only the other results release the mark.
+function gitRan(result) {
+    switch (result.status) {
+        case 'committed':
+        case 'failed':
+            return true;
+        case 'no-changes':
+        case 'disabled':
+            return false;
+        default: {
+            const exhaustive = result;
+            throw new Error(`Unhandled commit result: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
 /**
  * Classifies a commit attempt into the ledger entry to record, or null when
  * there is nothing to record ('no-changes' / 'disabled'). A landed entry

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

@@ -1,3 +1,4 @@
+import type { MigrateOutputSink } from '../deferred-output';
 import type { MigrateStep } from './run-state';
 export declare function nowIso(): string;
 /**
@@ -28,7 +29,7 @@ export declare function depsHash(root: string): string | null;
  * 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>;
+export declare function installDepsChangedSinceDispense(root: string, dir: string, step: MigrateStep, skipInstall: boolean, rerunCommand?: string, sink?: MigrateOutputSink): 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
@@ -56,4 +57,5 @@ 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 runMigrationsFlag(migrationsPath: string): string | null;
 export declare function pmInstallCommand(root: string): string;

package/dist/src/command-line/migrate/run/util.js

@@ -9,12 +9,15 @@ exports.isPidAlive = isPidAlive;
 exports.summarizeError = summarizeError;
 exports.warnCommitFailed = warnCommitFailed;
 exports.pmExecPrefix = pmExecPrefix;
+exports.runMigrationsFlag = runMigrationsFlag;
 exports.pmInstallCommand = pmInstallCommand;
 const crypto_1 = require("crypto");
+const shell_quoting_1 = require("../../../utils/shell-quoting");
 const package_manager_1 = require("../../../utils/package-manager");
 const execute_migration_1 = require("../execute-migration");
 const state_lock_1 = require("./state-lock");
 const agent_output_1 = require("./agent-output");
+const text_1 = require("../text");
 function nowIso() {
     return new Date().toISOString();
 }
@@ -49,15 +52,15 @@ function depsHash(root) {
  * started from are unknown rather than unchanged, and skipping there would
  * strand the change with nothing left to detect it.
  */
-async function installDepsChangedSinceDispense(root, dir, step, skipInstall, rerunCommand) {
+async function installDepsChangedSinceDispense(root, dir, step, skipInstall, rerunCommand, sink) {
     const current = depsHash(root);
     if (current !== null && current === step.depsHashAtDispense)
         return;
     if (skipInstall) {
-        (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+        (0, execute_migration_1.logSkippedPostMigrationInstall)(root, sink);
         return;
     }
-    await (0, execute_migration_1.runInstall)(root, 'post-migration', rerunCommand);
+    await (0, execute_migration_1.runInstall)(root, 'post-migration', rerunCommand, sink);
     recordInstallLanded(root, dir, step.id);
 }
 /**
@@ -143,6 +146,24 @@ function pmCommands(root) {
 function pmExecPrefix(root) {
     return pmCommands(root).exec;
 }
+const DEFAULT_MIGRATIONS_FILE = 'migrations.json';
+// The --run-migrations flag a rendered command repeats; null when the path
+// cannot go out as a one-line command for this shell. On Windows the paste
+// target may be cmd.exe or PowerShell, whose quoting and expansion conflict
+// (`%VAR%` expands in cmd, `$(...)` runs in PowerShell).
+function runMigrationsFlag(migrationsPath) {
+    if (migrationsPath === DEFAULT_MIGRATIONS_FILE) {
+        return '--run-migrations';
+    }
+    if ((0, text_1.hasLineBreak)(migrationsPath)) {
+        return null;
+    }
+    const arg = `--run-migrations=${migrationsPath}`;
+    if (process.platform !== 'win32') {
+        return (0, shell_quoting_1.quoteShellArg)(arg);
+    }
+    return !(0, shell_quoting_1.needsShellQuoting)(arg) && !/[%^]/.test(arg) ? arg : null;
+}
 function pmInstallCommand(root) {
     return pmCommands(root).install;
 }