@ohos-ports/nx 23.2.1-beta.0 → 23.3.0-beta.0

package/dist/src/command-line/migrate/command-object.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTI_MAJOR_MODES = exports.MIGRATE_INCLUDE_VALUES = exports.DEFAULT_MIGRATION_COMMIT_PREFIX = exports.yargsInternalMigrateCommand = exports.yargsMigrateCommand = void 0;
+exports.customCommitPrefixHasNoEffect = customCommitPrefixHasNoEffect;
+const handle_import_1 = require("../../utils/handle-import");
+const documentation_1 = require("../yargs-utils/documentation");
+const shared_options_1 = require("../yargs-utils/shared-options");
+const cli_args_1 = require("./agentic/cli-args");
+const step_actions_1 = require("./step-actions");
+exports.yargsMigrateCommand = {
+    command: 'migrate [packageAndVersion]',
+    describe: `Creates a migrations file or runs migrations from the migrations file.
+  - Migrate packages and create migrations.json (e.g., nx migrate @nx/workspace@latest)
+  - Run migrations (e.g., nx migrate --run-migrations=migrations.json). Use flag --if-exists to run migrations only if the migrations file exists.
+  - Run a single migration from migrations.json by id (e.g., nx migrate --run-migration=@nx/js:my-migration).`,
+    builder: (yargs) => (0, documentation_1.linkToNxDevAndExamples)(withMigrationOptions(yargs), 'migrate'),
+    handler: async () => process.exit(await (await (0, handle_import_1.handleImport)('./migrate.js', __dirname)).runMigration()),
+};
+exports.yargsInternalMigrateCommand = {
+    command: '_migrate [packageAndVersion]',
+    describe: false,
+    builder: (yargs) => withMigrationOptions(yargs),
+    handler: async (args) => process.exit(await (await (0, handle_import_1.handleImport)('./migrate.js', __dirname)).migrate(process.cwd(), args, process.argv.slice(3))),
+};
+exports.DEFAULT_MIGRATION_COMMIT_PREFIX = 'chore: [nx migration] ';
+/** Allowed values for `--include` / `migrate.include`. */
+exports.MIGRATE_INCLUDE_VALUES = ['required', 'optional', 'all'];
+/** Allowed values for `--multi-major-mode` / `migrate.multiMajorMode`. */
+exports.MULTI_MAJOR_MODES = ['direct', 'gradual'];
+/**
+ * Whether a custom commit prefix would be silently ignored: commits aren't
+ * enabled and the agentic flow can't enable them either. Shared by the yargs
+ * `.check()` (CLI args) and the nx.json overlay (merged args) so the rule lives
+ * in one place. `agentic` may flip commits on by default, so a configured
+ * agentic value (other than `false`, and not paired with `--no-create-commits`)
+ * keeps the prefix in play.
+ */
+function customCommitPrefixHasNoEffect(args) {
+    const agenticMayEnableCommits = args.agentic !== undefined &&
+        args.agentic !== false &&
+        args.createCommits !== false;
+    return (args.createCommits !== true &&
+        !agenticMayEnableCommits &&
+        args.commitPrefix !== undefined &&
+        args.commitPrefix !== exports.DEFAULT_MIGRATION_COMMIT_PREFIX);
+}
+function withMigrationOptions(yargs) {
+    return (0, shared_options_1.withVerbose)(yargs)
+        .positional('packageAndVersion', {
+        describe: `The target package and version (e.g, @nx/workspace@16.0.0).`,
+        type: 'string',
+    })
+        .option('runMigrations', {
+        describe: `Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json).`,
+        type: 'string',
+    })
+        .option('runMigration', {
+        describe: "Run a single migration from migrations.json by id. The id is '<package>:<name>'; a bare '<name>' is accepted when it matches exactly one migration. A name that contains ':' must use the full '<package>:<name>' form.",
+        type: 'string',
+    })
+        .option('runId', {
+        // Hidden with the orchestrator itself.
+        describe: 'The orchestrated migrate run to record a single migration into, to continue with --run-migrations, or to reconcile when given alone.',
+        type: 'string',
+        hidden: true,
+    })
+        .option('stepAction', {
+        describe: 'How an orchestrated reconcile resolves its single failed or died step.',
+        choices: step_actions_1.STEP_ACTIONS,
+        type: 'string',
+        hidden: true,
+    })
+        .option('startFresh', {
+        describe: 'With --run-migrations and --run-id=<id> under the orchestrator: delete the record of the active migrate run the id names and start a new run over the whole plan. Migrations the deleted run applied stay applied.',
+        type: 'boolean',
+        hidden: true,
+    })
+        .option('ifExists', {
+        describe: `Run migrations only if the migrations file exists, if not continues successfully.`,
+        type: 'boolean',
+        default: false,
+    })
+        .option('from', {
+        describe: 'Use the provided versions for packages instead of the ones installed in node_modules (e.g., --from="@nx/react@16.0.0,@nx/js@16.0.0").',
+        type: 'string',
+    })
+        .option('to', {
+        describe: 'Use the provided versions for packages instead of the ones calculated by the migrator (e.g., --to="@nx/react@16.0.0,@nx/js@16.0.0").',
+        type: 'string',
+    })
+        .option('createCommits', {
+        describe: 'Automatically create a git commit after each migration runs.',
+        type: 'boolean',
+        alias: ['C'],
+    })
+        .option('commitPrefix', {
+        describe: 'Commit prefix to apply to the commit for each migration, when --create-commits is enabled.',
+        type: 'string',
+        default: exports.DEFAULT_MIGRATION_COMMIT_PREFIX,
+    })
+        .option('interactive', {
+        describe: "Enable confirmation prompts for collecting optional package updates and migrations. Deprecated and slated for removal in Nx v24. Use '--include' instead. The flag stays valid for other interactive prompts.",
+        type: 'boolean',
+    })
+        .option('excludeAppliedMigrations', {
+        describe: 'Exclude migrations that should have been applied on previous updates. To be used with --from.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('skipInstall', {
+        describe: 'Skip installing packages before running migrations. Useful when the installation needs to be performed manually (e.g., to resolve peer dependency conflicts).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('include', {
+        describe: "Restrict which packages to migrate. Only applies when the target package supports optional updates. 'required' processes only the target package and the related packages it ships with; 'optional' processes only the optional dependency updates those packages recommend, catching up on any that may have been skipped previously; 'all' processes everything. When the target supports optional updates in an interactive terminal, prompts for the value if not provided; otherwise defaults to 'all'.",
+        type: 'string',
+        choices: exports.MIGRATE_INCLUDE_VALUES,
+    })
+        .option('multiMajorMode', {
+        describe: "Skip the multi-major migration prompt/warning and pick how to handle the jump. 'direct' migrates straight to the requested target. 'gradual' migrates to the smallest recommended step (re-run `nx migrate` to continue toward the original target). Equivalent env var: NX_MULTI_MAJOR_MODE=direct|gradual.",
+        type: 'string',
+        choices: exports.MULTI_MAJOR_MODES,
+    })
+        .option('agentic', {
+        describe: 'Enable the agentic flow for prompt-based migrations and AI-driven review. Pass `--agentic=<agent>` to pin a specific agent (claude-code, codex, or opencode). Pass `--agentic=false` or `--no-agentic` to disable.',
+        coerce: cli_args_1.coerceAgenticArg,
+    })
+        .option('validate', {
+        describe: 'When `--agentic` resolves to an enabled agent, run agent-driven validation after generator-only migrations that have no `prompt:` field. Defaults to on; pass `--no-validate` to opt out. Has no effect when `--agentic` is disabled, when running inside an outer agent, or when running non-interactively without an explicit agent.',
+        type: 'boolean',
+    })
+        .option('finalValidation', {
+        describe: 'With --run-migrations under the orchestrator: end the run with an agent validation pass over the whole workspace once every migration has run. On by default; pass --no-final-validation to opt out.',
+        type: 'boolean',
+        hidden: true,
+    })
+        .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, include, agentic, }) => {
+        // Only an explicit `--no-create-commits` is decidable here, before the
+        // nx.json overlay runs: an explicit `false` can't be rescued by nx.json
+        // (the CLI flag wins, and the agentic flow can't enable commits when
+        // they're explicitly off). When `createCommits` is undefined, nx.json
+        // may still enable commits, so defer to the post-overlay
+        // `assertCommitPrefixHasCommits` check.
+        if (createCommits === false &&
+            customCommitPrefixHasNoEffect({
+                createCommits,
+                commitPrefix,
+                agentic,
+            })) {
+            throw new Error('Error: Providing a custom commit prefix requires --create-commits to be enabled');
+        }
+        if (excludeAppliedMigrations && !from && include !== 'optional') {
+            throw new Error('Error: Excluding migrations that should have been previously applied requires --from to be set');
+        }
+        if (typeof agentic === 'string' &&
+            !cli_args_1.AGENT_IDS.includes(agentic)) {
+            throw new Error(`Error: Invalid --agentic value "${agentic}". Allowed: ${cli_args_1.AGENT_IDS.join(', ')}, true, false.`);
+        }
+        return true;
+    });
+}

package/dist/src/command-line/migrate/deferred-output.d.ts

@@ -0,0 +1,44 @@
+export type NoticeLevel = 'log' | 'warn' | 'error';
+export type LineColor = 'dim' | 'yellow' | 'red';
+export interface MigrateOutputSink {
+    notice(level: NoticeLevel, message: {
+        title: string;
+        bodyLines?: string[];
+    }): void;
+    line(color: LineColor, text: string): void;
+    /** A chunk of a package manager's own output. */
+    raw(chunk: string): void;
+}
+export declare const terminalOutput: MigrateOutputSink;
+export type DeferredOutputRecord = {
+    kind: 'notice';
+    level: NoticeLevel;
+    title: string;
+    bodyLines?: string[];
+} | {
+    kind: 'line';
+    color: LineColor;
+    text: string;
+} | {
+    kind: 'raw';
+    text: string;
+};
+/**
+ * Collects the output as records that `replayDeferredOutput` prints later.
+ * The notices and lines are always kept; package manager output is bounded
+ * like generator output and rendered only on request. Render once the output
+ * is complete: a rendered collector accepts nothing more.
+ */
+export declare class DeferredOutputCollector implements MigrateOutputSink {
+    private readonly records;
+    private rendered;
+    private assertOpen;
+    notice(level: NoticeLevel, message: {
+        title: string;
+        bodyLines?: string[];
+    }): void;
+    line(color: LineColor, text: string): void;
+    raw(chunk: string): void;
+    render(rawOutput: 'keep' | 'drop'): DeferredOutputRecord[];
+}
+export declare function replayDeferredOutput(records: DeferredOutputRecord[], to?: MigrateOutputSink): void;

package/dist/src/command-line/migrate/deferred-output.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeferredOutputCollector = exports.terminalOutput = void 0;
+exports.replayDeferredOutput = replayDeferredOutput;
+const tslib_1 = require("tslib");
+const pc = tslib_1.__importStar(require("picocolors"));
+const logger_1 = require("../../utils/logger");
+const output_1 = require("../../utils/output");
+exports.terminalOutput = {
+    notice: (level, message) => output_1.output[level](message),
+    line: (color, text) => logger_1.logger.info(pc[color](text)),
+    raw: (chunk) => process.stdout.write(chunk),
+};
+/**
+ * Collects the output as records that `replayDeferredOutput` prints later.
+ * The notices and lines are always kept; package manager output is bounded
+ * like generator output and rendered only on request. Render once the output
+ * is complete: a rendered collector accepts nothing more.
+ */
+class DeferredOutputCollector {
+    constructor() {
+        this.records = [];
+        this.rendered = false;
+    }
+    assertOpen() {
+        if (this.rendered) {
+            throw new Error('The deferred output was already rendered.');
+        }
+    }
+    notice(level, message) {
+        this.assertOpen();
+        this.records.push({ kind: 'notice', level, ...message });
+    }
+    line(color, text) {
+        this.assertOpen();
+        this.records.push({ kind: 'line', color, text });
+    }
+    raw(chunk) {
+        this.assertOpen();
+        let block = this.records[this.records.length - 1];
+        if (block?.kind !== 'raw-block') {
+            // Lazy: the non-agentic migrate path must not load the agentic chain.
+            const { BoundedChunks } = require('./agentic/capture-generator-output');
+            block = { kind: 'raw-block', buffer: new BoundedChunks() };
+            this.records.push(block);
+        }
+        block.buffer.append(chunk);
+    }
+    render(rawOutput) {
+        this.rendered = true;
+        const records = [];
+        for (const record of this.records) {
+            if (record.kind !== 'raw-block') {
+                records.push(record);
+                continue;
+            }
+            if (rawOutput === 'drop')
+                continue;
+            // The replay adds the final newline back.
+            const text = record.buffer.render();
+            records.push({
+                kind: 'raw',
+                text: text.endsWith('\n') ? text.slice(0, -1) : text,
+            });
+        }
+        return records;
+    }
+}
+exports.DeferredOutputCollector = DeferredOutputCollector;
+function replayDeferredOutput(records, to = exports.terminalOutput) {
+    for (const record of records) {
+        switch (record.kind) {
+            case 'notice':
+                to.notice(record.level, {
+                    title: record.title,
+                    bodyLines: record.bodyLines,
+                });
+                break;
+            case 'line':
+                to.line(record.color, record.text);
+                break;
+            case 'raw':
+                if (record.text)
+                    to.raw(`${record.text}\n`);
+                break;
+            default: {
+                const exhaustive = record;
+                throw new Error(`Unhandled output record: ${JSON.stringify(exhaustive)}`);
+            }
+        }
+    }
+}

package/dist/src/command-line/migrate/execute-migration.d.ts

@@ -0,0 +1,97 @@
+import { MigrationsJson } from '../../config/misc-interfaces';
+import { FileChange } from '../../generators/tree';
+import { ArrayPackageGroup, NxMigrationsConfiguration, PackageJson } from '../../utils/package-json';
+import { type MigrateOutputSink } from './deferred-output';
+interface PackageMigrationConfig extends NxMigrationsConfiguration {
+    packageJson: PackageJson;
+    packageGroup: ArrayPackageGroup;
+}
+export declare function readPackageMigrationConfig(packageName: string, dir: string): PackageMigrationConfig;
+/**
+ * With a `sink`, stdin is ignored and stdout and stderr are collected for a
+ * caller sharing the terminal. On POSIX the child stays in nx's process
+ * group. Without a sink, the install owns the terminal.
+ */
+export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase, rerunCommand?: string, sink?: MigrateOutputSink): Promise<void>;
+export type MigrationInstallPhase = 'pre-migration' | 'post-migration';
+export declare class NpmPeerDepsInstallError extends Error {
+    constructor();
+}
+/**
+ * Detects npm peer-dependency resolution failures. Keyed on the `ERESOLVE`
+ * error code, which npm consistently emits for this class of failure across
+ * v7+ (`npm ERR! code ERESOLVE` / `npm error code ERESOLVE`). Falls back to a
+ * small set of stable phrases in case the code line is missing from the
+ * captured output.
+ */
+export declare function isNpmPeerDepsError(stderr: string): boolean;
+export declare function formatSingleMigrationRerunCommand(migrationId: string): string;
+export declare function logNpmPeerDepsError(phase: MigrationInstallPhase, rerunCommand?: string, out?: MigrateOutputSink): void;
+export declare function logSkippedPostMigrationInstall(root: string, out?: MigrateOutputSink): void;
+export declare class ChangedDepInstaller {
+    private readonly root;
+    private readonly shouldSkipInstall;
+    private readonly rerunCommand?;
+    private initialDeps;
+    private _skippedInstall;
+    private _installed;
+    constructor(root: string, shouldSkipInstall?: boolean, rerunCommand?: string);
+    get skippedInstall(): boolean;
+    /**
+     * Whether an install actually ran. Distinct from `!skippedInstall`, which is
+     * only about the skip-install flag: dependencies that never changed leave
+     * both false.
+     */
+    get installed(): boolean;
+    installDepsIfChanged(): Promise<void>;
+}
+export declare function runNxOrAngularMigration(root: string, migration: {
+    package: string;
+    name: string;
+    description?: string;
+    version: string;
+}, isVerbose: boolean, captureGeneratorOutput?: boolean, resolvedCollection?: ResolvedMigrationCollection): Promise<{
+    changes: FileChange[];
+    nextSteps: string[];
+    agentContext: string[];
+    skipAgentic: boolean;
+    logs: string;
+    madeChanges: boolean;
+}>;
+/**
+ * The workspace's declared dependencies, serialized for equality comparison,
+ * or `null` when package.json could not be read or parsed. Callers that
+ * persist the value across processes need that distinction: an unreadable
+ * package.json is not an empty dependency set.
+ */
+export declare function readPackageJsonDeps(root: string): string | null;
+export declare function getStringifiedPackageJsonDeps(root: string): string;
+export declare function runNxMigration(root: string, collectionPath: string, collection: MigrationsJson, name: string, migrationVersion: string | undefined, captureGeneratorOutput: boolean): Promise<{
+    changes: FileChange[];
+    nextSteps: string[];
+    agentContext: string[];
+    skipAgentic: boolean;
+    logs: string;
+}>;
+export declare function parseMigrationReturn(value: unknown): {
+    nextSteps: string[];
+    agentContext: string[];
+    skipAgentic: boolean;
+};
+export declare function filterStrings(value: unknown): string[];
+export interface ResolvedMigrationCollection {
+    collection: MigrationsJson;
+    collectionPath: string;
+}
+export declare function readMigrationCollection(packageName: string, root: string): ResolvedMigrationCollection;
+export declare function resolveDocumentationFileToWorkspacePath(root: string, migrationsDir: string, documentation: string): string | undefined;
+export declare function getImplementationPath(collection: MigrationsJson, collectionPath: string, name: string, migrationVersion?: string): {
+    path: string;
+    fnSymbol: string;
+};
+export declare class MigrationImplementationMissingError extends Error {
+    constructor(baseMessage: string, collectionPath: string, migrationVersion: string | undefined);
+}
+export declare function isAngularMigration(collection: MigrationsJson, name: string): import("../../config/misc-interfaces").MigrationsJsonEntry;
+export declare const getNgCompatLayer: () => Promise<typeof import("../../adapter/ngcli-adapter")>;
+export {};