@nx/devkit 23.2.0-beta.11 → 23.2.0-beta.12

package/dist/src/generators/plugin-migrations/batch-conversion-session.d.ts

@@ -0,0 +1,131 @@
+import { type CreateNodes, type ExpandedPluginConfiguration, type ProjectGraphProjectNode, type Tree, logger as devkitLogger } from 'nx/src/devkit-exports';
+import type { ResidualByProject } from './executor-to-plugin-migrator';
+/**
+ * The evidence one deferred engine invocation stages for the batch finalize
+ * pass. Everything is captured by value at staging time (see `stagePlan`)
+ * because later children in the batch keep mutating the Tree and their own
+ * caches; the only live references kept are the plugin's `createNodes`
+ * functions, which the finalize verification pass needs to run.
+ */
+export interface DeferredConversionPlan {
+    pluginPath: string;
+    createNodes: CreateNodes | undefined;
+    createNodesV2: CreateNodes | undefined;
+    logger: typeof devkitLogger | undefined;
+    /**
+     * Whether the plugin was registered in nx.json before this conversion wrote
+     * its registrations. Gates dead executor-keyed target-default cleanup, as in
+     * the inline engine path.
+     */
+    pluginPreRegistered: boolean;
+    /** Per-(project, target) residuals + equivalence-oracle baselines (Phase 2). */
+    residualByProject: ResidualByProject;
+    /** project name -> project root for every migrated project. */
+    rootByProject: Map<string, string>;
+    /**
+     * project name -> pre-migration graph node for every migrated project. The
+     * finalize target-default preflight resolves `filter.projects` entries
+     * through the production reader, which matches against the project's node.
+     */
+    graphNodeByProject: Map<string, ProjectGraphProjectNode>;
+    /**
+     * Every project root in the pre-migration graph. With the plans' Phase 1
+     * inferred roots, these are the known owners the finalize pass attributes
+     * errored config files to (closest root wins).
+     */
+    graphRoots: Set<string>;
+    /**
+     * `"<project>\t<target>"` -> the effective executor the pair resolves to
+     * after migration (the inferred target's; a `command` resolves to
+     * `nx:run-commands`). Input to the finalize target-default preflight.
+     */
+    inferredExecutorByPair: Map<string, string | undefined>;
+    /** Every effective executor the plugin's Phase 1 inference emitted. */
+    inferredExecutors: Set<string>;
+    /** Every root the plugin's Phase 1 inference produced a project for. */
+    inferredRoots: Set<string>;
+    /** Config files matched by the plugin's glob and owned by an inferred root. */
+    matchedConfigFiles: string[];
+    /** Config files the Phase 1 inference could not load. */
+    erroredConfigFiles: string[];
+    /** The migrated executors (Phase 0 scope): dead-default cleanup candidates. */
+    migratedExecutors: string[];
+    /**
+     * `"<project>\t<target>"` -> executor from the pre-migration project graph.
+     * Feeds the batch-global liveness scan: a pair no plan migrated still
+     * resolves its graph executor, keeping that executor's defaults live.
+     */
+    graphExecutorByPair: Map<string, string>;
+}
+/**
+ * One child generator run inside the batch: the `nx.json` `plugins` snapshots
+ * around it and the plans its engine invocations staged. A registration delta
+ * that no staged plan's plugin accounts for is an opaque barrier for the
+ * finalize planner (e.g. a converter that bypasses the engine entirely, or
+ * registers an unrelated plugin).
+ */
+export interface BatchChildRecord {
+    pluginsBefore: (string | ExpandedPluginConfiguration)[];
+    pluginsAfter: (string | ExpandedPluginConfiguration)[];
+    plans: DeferredConversionPlan[];
+}
+/** The engine-facing slice of the session: stage a plan for the running child. */
+export interface BatchConversionStaging {
+    stagePlan(plan: DeferredConversionPlan): void;
+}
+/**
+ * A batch of convert-to-inferred generator runs against one Tree
+ * (`infer-targets` with several plugins selected). While a child runs inside
+ * `runChild`, the engine defers centralization: it writes full residuals,
+ * skips the hoist / dead-default cleanup / verification pass, and stages a
+ * {@link DeferredConversionPlan} here instead. The staged evidence is committed
+ * only when the child generator resolves, so a failed child contributes
+ * nothing. A finalize pass consumes the committed records after the batch loop.
+ *
+ * Open with {@link openBatchConversionSession} and always `close()` in a
+ * `finally` so the Tree's engine invocations return to the inline path.
+ */
+export declare class BatchConversionSession {
+    private readonly tree;
+    private readonly children;
+    private pendingPlans;
+    private closed;
+    constructor(tree: Tree);
+    /** The committed child records, in batch order. */
+    get records(): readonly BatchChildRecord[];
+    /**
+     * Run one child generator with deferred centralization. Commits the plans
+     * its engine invocations staged only when `fn` resolves; a rejection (a
+     * failed child, or `NoTargetsToMigrateError`) discards them.
+     */
+    runChild<T>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Stage a deferred plan for the running child (engine-facing; reach it via
+     * {@link getActiveBatchStaging}). Clones every mutable structure so the
+     * staged evidence is immune to later Tree/cache mutations; the `createNodes`
+     * references are kept live for the finalize verification pass.
+     */
+    stagePlan(plan: DeferredConversionPlan): void;
+    private hasRunningChild;
+    /**
+     * End the session: engine invocations on the Tree return to the inline path.
+     * Rejected while a child is running; otherwise a still-running child would
+     * fall back to inline centralization mid-batch, or stage its plan into a
+     * session opened after this one. `runChild` always settles its child before
+     * returning or throwing, so a `finally { session.close() }` never hits this.
+     */
+    close(): void;
+    /** @internal module-level accessor for {@link getActiveBatchStaging}. */
+    static activeStagingFor(tree: Tree): BatchConversionStaging | undefined;
+}
+/**
+ * Open a batch conversion session for `tree`. Throws when one is already open:
+ * sessions do not nest (each child in a batch must observe the same session).
+ */
+export declare function openBatchConversionSession(tree: Tree): BatchConversionSession;
+/**
+ * The staging handle for `tree`, or `undefined` when no batch child is
+ * currently running (no session, or the session is between children). The
+ * engine checks this to decide between the inline path and deferred staging.
+ */
+export declare function getActiveBatchStaging(tree: Tree): BatchConversionStaging | undefined;

package/dist/src/generators/plugin-migrations/batch-conversion-session.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchConversionSession = void 0;
+exports.openBatchConversionSession = openBatchConversionSession;
+exports.getActiveBatchStaging = getActiveBatchStaging;
+const devkit_exports_1 = require("nx/src/devkit-exports");
+// Keyed by Tree identity so a session cannot leak into another generator
+// invocation. At most one session per Tree.
+const activeSessions = new WeakMap();
+/**
+ * A batch of convert-to-inferred generator runs against one Tree
+ * (`infer-targets` with several plugins selected). While a child runs inside
+ * `runChild`, the engine defers centralization: it writes full residuals,
+ * skips the hoist / dead-default cleanup / verification pass, and stages a
+ * {@link DeferredConversionPlan} here instead. The staged evidence is committed
+ * only when the child generator resolves, so a failed child contributes
+ * nothing. A finalize pass consumes the committed records after the batch loop.
+ *
+ * Open with {@link openBatchConversionSession} and always `close()` in a
+ * `finally` so the Tree's engine invocations return to the inline path.
+ */
+class BatchConversionSession {
+    constructor(tree) {
+        this.tree = tree;
+        this.children = [];
+        this.closed = false;
+    }
+    /** The committed child records, in batch order. */
+    get records() {
+        return this.children;
+    }
+    /**
+     * Run one child generator with deferred centralization. Commits the plans
+     * its engine invocations staged only when `fn` resolves; a rejection (a
+     * failed child, or `NoTargetsToMigrateError`) discards them.
+     */
+    async runChild(fn) {
+        if (this.closed) {
+            throw new Error('The convert-to-inferred batch session has been closed; open a new one to run more conversions.');
+        }
+        if (this.pendingPlans) {
+            throw new Error('A convert-to-inferred batch child is already running; batch children must run sequentially.');
+        }
+        const pluginsBefore = structuredClone((0, devkit_exports_1.readNxJson)(this.tree)?.plugins ?? []);
+        this.pendingPlans = [];
+        try {
+            const result = await fn();
+            this.children.push({
+                pluginsBefore,
+                pluginsAfter: structuredClone((0, devkit_exports_1.readNxJson)(this.tree)?.plugins ?? []),
+                plans: this.pendingPlans,
+            });
+            return result;
+        }
+        finally {
+            this.pendingPlans = undefined;
+        }
+    }
+    /**
+     * Stage a deferred plan for the running child (engine-facing; reach it via
+     * {@link getActiveBatchStaging}). Clones every mutable structure so the
+     * staged evidence is immune to later Tree/cache mutations; the `createNodes`
+     * references are kept live for the finalize verification pass.
+     */
+    stagePlan(plan) {
+        if (!this.pendingPlans) {
+            throw new Error('Cannot stage a conversion plan: no batch child is running.');
+        }
+        const residualByProject = new Map();
+        for (const [projectName, targetMap] of plan.residualByProject) {
+            const clonedTargetMap = new Map();
+            for (const [targetName, entry] of targetMap) {
+                clonedTargetMap.set(targetName, structuredClone(entry));
+            }
+            residualByProject.set(projectName, clonedTargetMap);
+        }
+        const graphNodeByProject = new Map();
+        for (const [projectName, node] of plan.graphNodeByProject) {
+            graphNodeByProject.set(projectName, structuredClone(node));
+        }
+        this.pendingPlans.push({
+            ...plan,
+            residualByProject,
+            rootByProject: new Map(plan.rootByProject),
+            graphNodeByProject,
+            graphRoots: new Set(plan.graphRoots),
+            inferredExecutorByPair: new Map(plan.inferredExecutorByPair),
+            inferredExecutors: new Set(plan.inferredExecutors),
+            inferredRoots: new Set(plan.inferredRoots),
+            matchedConfigFiles: [...plan.matchedConfigFiles],
+            erroredConfigFiles: [...plan.erroredConfigFiles],
+            migratedExecutors: [...plan.migratedExecutors],
+            graphExecutorByPair: new Map(plan.graphExecutorByPair),
+        });
+    }
+    hasRunningChild() {
+        return this.pendingPlans !== undefined;
+    }
+    /**
+     * End the session: engine invocations on the Tree return to the inline path.
+     * Rejected while a child is running; otherwise a still-running child would
+     * fall back to inline centralization mid-batch, or stage its plan into a
+     * session opened after this one. `runChild` always settles its child before
+     * returning or throwing, so a `finally { session.close() }` never hits this.
+     */
+    close() {
+        if (this.pendingPlans) {
+            throw new Error('Cannot close the convert-to-inferred batch session while a child conversion is running.');
+        }
+        this.closed = true;
+        if (activeSessions.get(this.tree) === this) {
+            activeSessions.delete(this.tree);
+        }
+    }
+    /** @internal module-level accessor for {@link getActiveBatchStaging}. */
+    static activeStagingFor(tree) {
+        const session = activeSessions.get(tree);
+        return session?.hasRunningChild() ? session : undefined;
+    }
+}
+exports.BatchConversionSession = BatchConversionSession;
+/**
+ * Open a batch conversion session for `tree`. Throws when one is already open:
+ * sessions do not nest (each child in a batch must observe the same session).
+ */
+function openBatchConversionSession(tree) {
+    if (activeSessions.has(tree)) {
+        throw new Error('A convert-to-inferred batch session is already open for this Tree.');
+    }
+    const session = new BatchConversionSession(tree);
+    activeSessions.set(tree, session);
+    return session;
+}
+/**
+ * The staging handle for `tree`, or `undefined` when no batch child is
+ * currently running (no session, or the session is between children). The
+ * engine checks this to decide between the inline path and deferred staging.
+ */
+function getActiveBatchStaging(tree) {
+    return BatchConversionSession.activeStagingFor(tree);
+}

package/dist/src/generators/plugin-migrations/conversion-warnings.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Warning messages the inline hoist (`executor-to-plugin-migrator`) and the
+ * batch finalize (`batch-conversion-finalize`) emit for the same outcomes. One
+ * builder per message so both paths stay word for word identical.
+ */
+import type { TargetConfiguration } from 'nx/src/devkit-exports';
+/** Which package.json signal authors a target's identity. */
+export type PackageJsonIdentitySource = 'script' | 'nxTargets' | 'unparseable';
+/** A migrated target was left untouched because package.json authors its identity. */
+export declare function keptPreMigrationTargetWarning(targetName: string, projectName: string, source: PackageJsonIdentitySource): string;
+/** A target's centralization was skipped before writing anything. */
+export declare function retainedResidualsWarning(targetNames: string[], reason: string): string;
+/** Projects whose target identity lives outside the plugin were not hoisted. */
+export declare function excludedProjectsWarning(projectNames: string[], targetNames: string[]): string;
+/** A hoisted target was reverted because it reached a non-migrated root. */
+export declare function revertedTargetsWarning(targetNames: string[], errors: string[]): string;
+/** A pair the verification pass did not infer at all. */
+export interface MissingPair {
+    pair: string;
+    root: string;
+    /** The target no longer exists once the residual is restored. */
+    removed: boolean;
+}
+/** Whether Nx drops an explicit target with this configuration (target normalization). */
+export declare function isDroppedTarget(target: TargetConfiguration): boolean;
+export declare function unverifiedPairsWarning(divergent: string[], missing: MissingPair[], errors: string[]): string;
+/** Verification errors that neither a revert nor a fallback warning carried. */
+export declare function verificationErrorsWarning(errors: string[], anyFallback: boolean): string;

package/dist/src/generators/plugin-migrations/conversion-warnings.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Warning messages the inline hoist (`executor-to-plugin-migrator`) and the
+ * batch finalize (`batch-conversion-finalize`) emit for the same outcomes. One
+ * builder per message so both paths stay word for word identical.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keptPreMigrationTargetWarning = keptPreMigrationTargetWarning;
+exports.retainedResidualsWarning = retainedResidualsWarning;
+exports.excludedProjectsWarning = excludedProjectsWarning;
+exports.revertedTargetsWarning = revertedTargetsWarning;
+exports.isDroppedTarget = isDroppedTarget;
+exports.unverifiedPairsWarning = unverifiedPairsWarning;
+exports.verificationErrorsWarning = verificationErrorsWarning;
+/** A migrated target was left untouched because package.json authors its identity. */
+function keptPreMigrationTargetWarning(targetName, projectName, source) {
+    const cause = {
+        script: `an included package.json script named "${targetName}" would replace the inferred target with nx:run-script once the explicit executor is removed. Rename or exclude the script`,
+        nxTargets: `the package.json nx.targets entry for "${targetName}" (next to project.json) would replace the inferred target once the explicit executor is removed. Remove that entry`,
+        unparseable: `its package.json could not be parsed, so a same-name script that would replace the inferred target cannot be ruled out. Fix the file`,
+    }[source];
+    return `convert-to-inferred kept the pre-migration configuration of target "${targetName}" in project "${projectName}": ${cause}, then rerun the migration to convert it. The target keeps the same behavior as before the migration.`;
+}
+function withCauses(errors) {
+    return errors.length > 0
+        ? ` The verification pass reported errors: ${errors.join('; ')}`
+        : '';
+}
+/** A target's centralization was skipped before writing anything. */
+function retainedResidualsWarning(targetNames, reason) {
+    return `convert-to-inferred retained full per-project configuration for target(s) ${targetNames.join(', ')} because ${reason}; no configuration was lost, but shared configuration remains duplicated.`;
+}
+/** Projects whose target identity lives outside the plugin were not hoisted. */
+function excludedProjectsWarning(projectNames, targetNames) {
+    return `convert-to-inferred kept per-project configuration for ${projectNames.length} project(s) (${projectNames.join(', ')}) on target(s) ${targetNames.join(', ')} instead of centralizing it: their target identity is authored outside the plugin (a project.json executor/command, or a package.json script/nx.targets entry), so a plugin-scoped default would not resolve for them. Those projects keep their full per-project configuration; review them if you expected shared configuration.`;
+}
+/** A hoisted target was reverted because it reached a non-migrated root. */
+function revertedTargetsWarning(targetNames, errors) {
+    return `convert-to-inferred kept per-project configuration for target(s) ${targetNames.join(', ')} instead of centralizing it: other projects inferred by this plugin would have inherited the centralized configuration (or the verification pass could not confirm they would not). The migrated projects keep the same output as before centralization.${withCauses(errors)}`;
+}
+/** Whether Nx drops an explicit target with this configuration (target normalization). */
+function isDroppedTarget(target) {
+    return (!target.executor &&
+        !target.command &&
+        !(target.dependsOn && target.dependsOn.length > 0));
+}
+function unverifiedPairsWarning(divergent, missing, errors) {
+    const pairs = [...divergent, ...missing.map((m) => m.pair)];
+    let message = `convert-to-inferred restored the pre-centralization migration output for ${pairs.length} target(s) that could not be verified as equivalent after migration: ${pairs.join(', ')}.`;
+    if (divergent.length > 0) {
+        message += ` Centralized nx.json defaults are shadowed where their keys overlap, but the live inferred configuration may differ from the pre-migration behavior for ${divergent.join(', ')}.`;
+    }
+    if (missing.length > 0) {
+        message += ` The plugin did not infer ${missing
+            .map((m) => `${m.pair} (root ${m.root})`)
+            .join(', ')} on the verification pass.`;
+        const removed = missing.filter((m) => m.removed);
+        if (removed.length > 0) {
+            message += ` The following targets no longer exist because each restored configuration has no executor, command or dependsOn: ${removed
+                .map((m) => m.pair)
+                .join(', ')}.`;
+        }
+    }
+    return `${message} Review these targets manually.${withCauses(errors)}`;
+}
+/** Verification errors that neither a revert nor a fallback warning carried. */
+function verificationErrorsWarning(errors, anyFallback) {
+    const outcome = anyFallback
+        ? ' Review any workspace configuration the errors reference.'
+        : ' The migrated targets matched their pre-migration output, but review any workspace configuration the errors reference.';
+    return `convert-to-inferred could not fully verify the migration: the verification inference pass reported errors: ${errors.join('; ')}.${outcome}`;
+}

package/dist/src/generators/plugin-migrations/executor-to-plugin-migrator.d.ts

@@ -1,5 +1,7 @@
 import type { ProjectConfiguration } from 'nx/src/config/workspace-json-project-json';
-import { type CreateNodes, type NxJsonConfiguration, type ProjectGraph, type TargetConfiguration, type Tree, logger as devkitLogger } from 'nx/src/devkit-exports';
+import { type CreateNodes, type ExpandedPluginConfiguration, type NxJsonConfiguration, type ProjectGraph, type ProjectGraphProjectNode, type TargetConfiguration, type TargetDefaultArrayEntry, type Tree, logger as devkitLogger } from 'nx/src/devkit-exports';
+import { ProjectConfigurationsError } from 'nx/src/devkit-internals';
+import { type PackageJsonIdentitySource } from './conversion-warnings';
 export type InferredTargetConfiguration = TargetConfiguration & {
     name: string;
 };
@@ -9,6 +11,185 @@ type PostTargetTransformer = (targetConfiguration: TargetConfiguration, tree: Tr
 }, inferredTargetConfiguration: InferredTargetConfiguration) => TargetConfiguration | Promise<TargetConfiguration>;
 type SkipTargetFilter = (targetOptions: Record<string, unknown>, projectConfiguration: ProjectConfiguration) => false | string;
 type SkipProjectFilter = (projectConfiguration: ProjectConfiguration) => false | string;
+type MigrationDefinition<T> = {
+    executors: string[];
+    targetPluginOptionMapper: (targetName: string) => Partial<T>;
+    postTargetTransformer: PostTargetTransformer;
+    skipProjectFilter?: SkipProjectFilter;
+    skipTargetFilter?: SkipTargetFilter;
+    /**
+     * Let several targets of a project map different target names through the
+     * same plugin option (last write wins) instead of keeping the later targets
+     * executor-based. Only for migrations that reconcile the resulting
+     * registration afterwards, like the detox one.
+     */
+    allowSharedOptionOverwrite?: boolean;
+};
+/**
+ * A distinct plugin-option set used to infer targets (Phase 1). `options` is the
+ * value passed to the plugin's `createNodes` (i.e. `targetPluginOptionMapper`'s
+ * output) and `targetNames` are the migrated target names that option set is
+ * responsible for producing.
+ */
+interface InferenceOptionSet<T> {
+    /** Stable id used to keep inference results isolated by option set. */
+    id: number;
+    /**
+     * The object handed to the plugin's `createNodes`: the raw
+     * `targetPluginOptionMapper` output. The engine never merges its own
+     * `defaultPluginOptions` into it (that is why `derivePluginFilledDefaults`
+     * skips keys already in the defaults). NOTE: the plugin itself may mutate this
+     * object in place during Phase 1 (e.g. `options.devTargetName ??= 'dev'`);
+     * `derivePluginFilledDefaults` relies on exactly that mutation, so after
+     * Phase 1 this can carry the plugin's own fills too.
+     */
+    options: Partial<T>;
+    targetNames: Set<string>;
+    /**
+     * Roots of the projects migrated under this option set. Phase 1 retains
+     * cloned inferred targets only for these roots (Phase 2 reads no others), so
+     * retention scales with the migrated projects instead of every inferred root
+     * times every option set.
+     */
+    migratedRoots: Set<string>;
+}
+interface ExecutorScope<T> {
+    executor: string;
+    migration: MigrationDefinition<T>;
+    targetAndProjects: Map<string, Set<string>>;
+    inferenceOptionSetIdsByTarget: Map<string, number>;
+}
+/**
+ * The result of Phase 0 (Collect). Built by folding `forEachExecutorOptions`
+ * over every migration/executor into one scope object, replacing the
+ * per-executor scope derivation the migrator used to do internally.
+ */
+export interface MigrationScope<T> {
+    /** project -> resolved plugin registration options (defaults + mappers) */
+    pluginOptionsByProject: Map<string, T>;
+    /** distinct inference option sets paired with the target names they infer */
+    optionSetGroups: InferenceOptionSet<T>[];
+    /** per (migration, executor) slice used to drive residual computation */
+    executorScopes: ExecutorScope<T>[];
+}
+export declare function stableStringify(value: unknown): string;
+/**
+ * Phase 0: Collect (once). Fold `forEachExecutorOptions` over every
+ * migration/executor into a single scope object, applying the skip filters with
+ * the exact same warn-vs-throw semantics the migrator used before (a
+ * `specificProjectToMigrate` skip throws instead of warning). This is the single
+ * authority for filtering; downstream phases only read the returned maps.
+ */
+export declare function collectMigrationScope<T>(tree: Tree, projectGraph: ProjectGraph, migrations: MigrationDefinition<T>[], defaultPluginOptions: T, specificProjectToMigrate?: string, logger?: typeof devkitLogger): MigrationScope<T>;
+/** The per-project residual and the equivalence oracle baseline for a target. */
+export interface ResidualEntry {
+    /** Byte-for-byte what the previous engine writes into project.json. */
+    residual: TargetConfiguration;
+    /**
+     * The migrated (command-based) effective config the previous engine yields:
+     * the full inferred target with the residual layered on top. Used in Phase 4
+     * as the equivalence oracle.
+     */
+    baselineFinal: TargetConfiguration;
+    /**
+     * The explicit target as authored before the migration. Restored when
+     * package.json turns out to author the target's identity (see
+     * `writeResidualTarget`, and the batch finalize for identities that appear
+     * after the write).
+     */
+    preMigrationTarget: TargetConfiguration;
+    /**
+     * Set by the write phase when the pre-migration target was kept untouched
+     * (see `writeResidualTarget`); the verification phase then leaves it alone.
+     */
+    keptPreMigration?: boolean;
+}
+/** project name -> (target name -> residual entry) */
+export type ResidualByProject = Map<string, Map<string, ResidualEntry>>;
+export type InferredTargetsByRoot = Map<string, Map<string, TargetConfiguration>>;
+export type InferredTargetsByOptionSet = Map<number, InferredTargetsByRoot>;
+/**
+ * Phase 2: Per-project residual (in-memory, no inference). For each
+ * `(project, target)` computes the residual exactly as the previous engine did
+ * (`mergeTargetConfigurations` with the executor target defaults ->
+ * `deleteMatchingProperties` -> input merge -> the plugin's
+ * `postTargetTransformer`), plus `baselineFinal = merge(residual, inferred)` as
+ * the equivalence oracle. Does NOT write project.json.
+ */
+export declare function computeResidualByProject<T>(tree: Tree, projectGraph: ProjectGraph, scope: MigrationScope<T>, inferredTargetsByOptionSet: InferredTargetsByOptionSet, nxJson: NxJsonConfiguration, projectConfigsByName?: Map<string, ProjectConfiguration>): Promise<ResidualByProject>;
+/**
+ * Phase 3: the strict-common residual across ALL migrated projects for a
+ * target: the values that are deep-equal across every project's residual.
+ * Granularity: whole value for top-level target props (`inputs`, `outputs`,
+ * `cache`, `dependsOn`, `configurations`, ...); per-key for `options`. A key is
+ * common only when EVERY residual carries it with an identical value.
+ */
+export declare function computeStrictCommon(residuals: TargetConfiguration[]): TargetConfiguration;
+/** `residual` with every property that the strict-common config carries removed. */
+export declare function subtractCommon(residual: TargetConfiguration, common: TargetConfiguration): TargetConfiguration;
+/**
+ * Remove the now-dead executor-keyed target default that Phase 2 inlined into
+ * every migrated project (mirrors `readTargetDefaultsForExecutor`'s match: the
+ * unfiltered entry keyed directly by the executor string).
+ */
+export declare function removeDeadExecutorTargetDefault(nxJson: NxJsonConfiguration, executor: string): void;
+/**
+ * Append the hoisted common as a plugin-scoped entry after whatever value the
+ * key already holds. Existing entries, the workspace catch-all and any
+ * user-authored filtered entries, are never modified, so targets outside this
+ * plugin resolve exactly what they resolved before the migration. The entry is
+ * appended (never merged into an existing one) so the verification pass can
+ * revert precisely this entry and nothing else.
+ */
+export declare function appendPluginScopedTargetDefault(nxJson: NxJsonConfiguration, targetName: string, pluginPath: string, common: TargetConfiguration): TargetDefaultArrayEntry;
+/**
+ * Remove a previously appended plugin-scoped entry, collapsing the value back
+ * to the plain object form when only a lone unfiltered entry remains. The
+ * appended entry survives an `updateNxJson`/`readNxJson` round trip only by
+ * value, so the last deep-equal occurrence (append order puts ours last) is
+ * the one removed.
+ */
+export declare function removeHoistedTargetDefault(nxJson: NxJsonConfiguration, targetName: string, entry: TargetDefaultArrayEntry): void;
+/**
+ * Which `package.json` signal, if any, authors an identity for `targetName` in
+ * the DEFAULT plugin layer. The package-json plugin turns every included script into
+ * an `nx:run-script` target and honors `nx.targets`; either way the target gains
+ * an `executor`/`command` in a default layer, which makes Nx's
+ * `resolveSourcePlugin` refuse a `filter: { plugin }` targetDefault for it.
+ * The hoist uses this to keep the full residual per project instead of silently
+ * dropping the centralized keys; the residual write uses it to keep the
+ * pre-migration target instead of letting the package.json identity take the
+ * target over.
+ *
+ * Read through the Tree so this sees the same in-memory package.json the rest of
+ * the generator reads and writes, rather than a possibly-stale copy on disk.
+ */
+export declare function packageJsonAuthorsTargetIdentity(tree: Tree, root: string | undefined, targetName: string): PackageJsonIdentitySource | undefined;
+export declare function isRegistrationOfPlugin(registration: string | ExpandedPluginConfiguration, pluginPath: string): boolean;
+/**
+ * Whether appending the plugin-scoped `targetDefaults[targetName]` entry would
+ * change what the existing target defaults resolve to for any eligible migrated
+ * pair. Two hazards, both invisible to the Phase 4 verification (it merges no
+ * target defaults):
+ *
+ * - Key displacement: an exact target-name key takes precedence over a glob
+ *   key (`build-*`), so appending one can silently stop a glob default from
+ *   contributing to the migrated targets.
+ * - Executor masking: an executor-keyed default for the plugin's INFERRED
+ *   executor (e.g. `nx:run-commands` for command-based inferred targets) takes
+ *   precedence over the exact key, so the appended entry would never resolve
+ *   and its keys would be silently dropped.
+ *
+ * The check resolves the defaults for each pair without and with the
+ * hypothetical entry, through the production reader. The hoist is a pure
+ * "residual moved into a default" only when the with-entry resolution equals
+ * the without-entry resolution with the common merged on top; anything else
+ * changes behavior, so the target keeps its full residuals.
+ */
+export declare function hoistChangesExistingTargetDefaults(targetDefaults: NxJsonConfiguration['targetDefaults'], targetName: string, common: TargetConfiguration, pluginPath: string, eligiblePairs: {
+    projectName: string;
+    inferredExecutor: string | undefined;
+}[], projectNodesByName: Record<string, ProjectGraphProjectNode>): boolean;
 export declare class NoTargetsToMigrateError extends Error {
     constructor();
 }
@@ -19,6 +200,7 @@ export declare function migrateProjectExecutorsToPlugin<T>(tree: Tree, projectGr
     postTargetTransformer: PostTargetTransformer;
     skipProjectFilter?: SkipProjectFilter;
     skipTargetFilter?: SkipTargetFilter;
+    allowSharedOptionOverwrite?: boolean;
 }>, specificProjectToMigrate?: string, logger?: typeof devkitLogger): Promise<Map<string, Record<string, string>>>;
 export declare function migrateProjectExecutorsToPluginV1<T>(tree: Tree, projectGraph: ProjectGraph, pluginPath: string, createNodes: CreateNodes<T>, defaultPluginOptions: T, migrations: Array<{
     executors: string[];
@@ -26,5 +208,72 @@ export declare function migrateProjectExecutorsToPluginV1<T>(tree: Tree, project
     postTargetTransformer: PostTargetTransformer;
     skipProjectFilter?: SkipProjectFilter;
     skipTargetFilter?: SkipTargetFilter;
+    allowSharedOptionOverwrite?: boolean;
 }>, specificProjectToMigrate?: string): Promise<Map<string, Record<string, string>>>;
+/**
+ * Phase 1: Infer (once per distinct option set). Runs a whole-workspace
+ * inference per distinct plugin-option set (usually one) instead of once per
+ * target and once per project. Builds `inferredTargetsByOptionSet` (option set
+ * id -> project root -> target name -> FULL inferred target; residual
+ * computation strips `command` / `options.cwd` at the point of use), which
+ * Phase 2 (`computeResidualByProject`) reads to compute residuals and
+ * `baselineFinal`; plus the matched config files owned by an inferred project
+ * root, which Phase 3's registration step reads for analytic include coverage.
+ */
+export declare function inferOncePerOptionSet<T>(tree: Tree, pluginPath: string, createNodes: CreateNodes<T> | undefined, createNodesV2: CreateNodes<T> | undefined, nxJson: NxJsonConfiguration, scope: MigrationScope<T>): Promise<{
+    inferredTargetsByOptionSet: InferredTargetsByOptionSet;
+    matchedConfigFiles: string[];
+    erroredConfigFiles: string[];
+    rawMatchedConfigFiles: string[];
+    inferredExecutors: Set<string>;
+    inferredRoots: Set<string>;
+}>;
+/**
+ * The set of project roots a generated `include` list scopes to, or `undefined`
+ * if any entry is not one of the two shapes this generator emits: `*` (the root
+ * project) or a literal root followed by a trailing globstar segment (a nested
+ * root). A user-authored include or any `exclude` falls back to the glob engine.
+ *
+ * The globstar branch only qualifies when the root prefix is a LITERAL path.
+ * A prefix carrying glob metacharacters (a wildcard, brace, or extglob segment
+ * before the trailing globstar) is not a shape this generator emits and can't be
+ * reduced to root ownership by string equality, so it falls back to the glob
+ * engine.
+ */
+export declare function generatedIncludeRoots(include: string[]): Set<string> | undefined;
+/** One harvested verification error, attributable to a plugin registration. */
+export interface HarvestedConfigurationError {
+    message: string;
+    /** The config files the error names (empty for a file-less error). */
+    files: string[];
+    /**
+     * The `nx.json` `plugins` index of the registration that produced the error,
+     * when the plugins were constructed with one (the batch finalize pass does);
+     * `undefined` otherwise.
+     */
+    pluginIndex: number | undefined;
+}
+/**
+ * Harvest the diagnostic messages and the errored config-file paths from a
+ * `ProjectConfigurationsError`. `ProjectConfigurationsError.errors` is a closed
+ * 5-member union; the two members that name a failing config file are
+ * `AggregateCreateNodesError` (a `[file, error]` list) and `MergeNodesError` (a
+ * single `.file`). `ProjectsWithNoNameError` / `MultipleProjectsWithSameNameError`
+ * are artifacts of running with no `project.json` layer (nothing supplies names),
+ * so they are dropped; `WorkspaceValidityError` carries no file and is exempt.
+ */
+export declare function harvestConfigurationErrors(e: ProjectConfigurationsError): {
+    messages: string[];
+    erroredConfigFiles: string[];
+    entries: HarvestedConfigurationError[];
+};
+/**
+ * Attribution map for errored-config ownership: every root the engine knows
+ * owns a project, i.e. graph project roots plus the roots the plugin inference
+ * produced (a project discovered from a config file alone has no graph node;
+ * graph roots win a collision). Keys are normalized for the
+ * `findProjectForPath` walk; values are the raw roots the per-target
+ * migrated-root sets hold.
+ */
+export declare function buildOwnerRootByPath(graphRoots: Iterable<string>, inferredRoots: Iterable<string>): Map<string, string>;
 export {};