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

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

@@ -0,0 +1,16 @@
+interface MigrationShape {
+    prompt?: string;
+    implementation?: string;
+    factory?: string;
+}
+/** A migration entry as written into the plan (migrations.json). */
+export interface PlannedMigration extends MigrationShape {
+    package: string;
+    name: string;
+    version: string;
+    description?: string;
+    documentation?: string;
+}
+export declare function isPromptOnlyMigration(m: MigrationShape): boolean;
+export declare function isHybridMigration(m: MigrationShape): boolean;
+export {};

package/dist/src/command-line/migrate/migration-shape.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPromptOnlyMigration = isPromptOnlyMigration;
+exports.isHybridMigration = isHybridMigration;
+function hasDeterministicImplementation(m) {
+    return !!(m.implementation || m.factory);
+}
+function isPromptOnlyMigration(m) {
+    return !!m.prompt && !hasDeterministicImplementation(m);
+}
+function isHybridMigration(m) {
+    return !!m.prompt && hasDeterministicImplementation(m);
+}

package/dist/src/command-line/migrate/multi-major.d.ts

@@ -0,0 +1,37 @@
+import type { MigrateInclude } from './migrate';
+import { type MigrateMultiMajorChoice } from './migrate-analytics';
+export declare const MULTI_MAJOR_MODE_FLAG = "--multi-major-mode";
+export type MultiMajorMode = 'direct' | 'gradual';
+/**
+ * Result of running the multi-major check.
+ *
+ * - `chosen`: the version to actually migrate to (always concrete semver when
+ *   the function ran past the dist-tag resolution; otherwise the input value).
+ * - `originalTarget`: set only when an actual redirect happened (gradual mode
+ *   auto-picked a smaller step, OR the interactive prompt returned a version
+ *   different from the resolved target). Holds the concrete resolved target
+ *   so callers can suggest re-running toward it.
+ * - `gradual`: set only when the redirect came from gradual mode (flag or
+ *   env). Tells callers it's safe to propagate `--multi-major-mode=gradual`
+ *   to a continuation command; left unset when the redirect came from the
+ *   interactive prompt so the user isn't silently locked into gradual.
+ * - `decision`: the collapsed outcome (`gradual` | `direct`) folded into the
+ *   generate completion analytics event; left unset on the early returns
+ *   where the multi-major gate didn't apply.
+ */
+export type MultiMajorResult = {
+    chosen: string;
+    originalTarget?: string;
+    gradual?: boolean;
+    decision?: MigrateMultiMajorChoice;
+};
+export declare function isNxTarget(targetPackage: string, targetVersion: string): boolean;
+export declare function maybePromptOrWarnMultiMajorMigration(args: {
+    include: MigrateInclude;
+    options: {
+        multiMajorMode?: MultiMajorMode;
+        interactive?: boolean;
+    };
+    targetPackage: string;
+    targetVersion: string;
+}): Promise<MultiMajorResult>;

package/dist/src/command-line/migrate/multi-major.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTI_MAJOR_MODE_FLAG = void 0;
+exports.isNxTarget = isNxTarget;
+exports.maybePromptOrWarnMultiMajorMigration = maybePromptOrWarnMultiMajorMigration;
+const safe_prompt_1 = require("./safe-prompt");
+const semver_1 = require("semver");
+const installed_nx_version_1 = require("../../utils/installed-nx-version");
+const output_1 = require("../../utils/output");
+const resolve_package_version_1 = require("./resolve-package-version");
+const migrate_analytics_1 = require("./migrate-analytics");
+const version_utils_1 = require("./version-utils");
+const INCREMENTAL_UPDATE_GUIDE_URL = 'https://nx.dev/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps';
+exports.MULTI_MAJOR_MODE_FLAG = '--multi-major-mode';
+const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
+// Caret-major (`^X.0.0`) excludes prereleases per semver, so the registry
+// resolution returns the highest stable in major X.
+async function resolveLatestStableInMajor(packageName, majorVersion) {
+    try {
+        // Probe only: this resolves prompt choices the user may never pick, so it
+        // must not prompt or write pnpm excludes. The chosen version is resolved
+        // again (with side effects) when migrations actually run.
+        const resolved = await (0, resolve_package_version_1.resolvePackageVersionRespectingMinReleaseAge)(packageName, `^${majorVersion}.0.0`, { applySideEffects: false });
+        return (0, semver_1.valid)(resolved) ? resolved : null;
+    }
+    catch {
+        return null;
+    }
+}
+const multiMajorHeader = (pkg, installed, target) => `Migrating across multiple major versions: ${pkg}@${installed} → ${pkg}@${target}.`;
+const multiMajorBodyLines = [
+    `The recommended process is to update one major version at a time, in small steps.`,
+    `See ${INCREMENTAL_UPDATE_GUIDE_URL}`,
+];
+function warnMultiMajorMigration(targetPackage, installed, target) {
+    output_1.output.warn({
+        title: multiMajorHeader(targetPackage, installed, target),
+        bodyLines: [
+            ...multiMajorBodyLines,
+            `Pass ${exports.MULTI_MAJOR_MODE_FLAG}=direct (or =gradual) or set ${MULTI_MAJOR_MODE_ENV} to silence this warning.`,
+        ],
+    });
+}
+function logGradualStep(targetPackage, step, target) {
+    // Status-only announcement. The follow-up instruction ("re-run `nx migrate`
+    // to continue toward the original target") lives in the Next Steps block at
+    // the end of the run, where it's adjacent to the other re-run guidance and
+    // not scrolled out of view by the migration output.
+    output_1.output.log({
+        title: `Migrating to ${targetPackage}@${step} (one step toward ${targetPackage}@${target}).`,
+    });
+}
+function warnGradualUnavailable(targetPackage, target, reason) {
+    output_1.output.warn({
+        title: `Could not look up incremental migration options for ${exports.MULTI_MAJOR_MODE_FLAG}=gradual. Proceeding directly to ${targetPackage}@${target}.`,
+        bodyLines: [reason],
+    });
+}
+// Returns the chosen target version. Caller replaces `targetVersion` with it.
+// At least one of `latestInCurrent`/`latestInNext` must be present.
+async function promptMultiMajorMigration(args) {
+    const choices = [];
+    let recommendedMarked = false;
+    if (args.latestInCurrent) {
+        choices.push({
+            value: args.latestInCurrent,
+            label: `Migrate to ${args.targetPackage}@${args.latestInCurrent} (latest in current major) [recommended]`,
+        });
+        recommendedMarked = true;
+    }
+    if (args.latestInNext) {
+        choices.push({
+            value: args.latestInNext,
+            label: `Migrate to ${args.targetPackage}@${args.latestInNext} (next major)${recommendedMarked ? '' : ' [recommended]'}`,
+        });
+    }
+    choices.push({
+        value: args.target,
+        label: `Migrate directly to ${args.targetPackage}@${args.target}`,
+    });
+    output_1.output.log({
+        title: multiMajorHeader(args.targetPackage, args.installed, args.target),
+        bodyLines: multiMajorBodyLines,
+    });
+    return (0, safe_prompt_1.migrateChoice)({
+        message: 'How would you like to proceed?',
+        choices,
+    });
+}
+// Flag wins over env var; only the two literal values are honoured.
+function resolveMultiMajorMode(options) {
+    if (options.multiMajorMode === 'direct' ||
+        options.multiMajorMode === 'gradual') {
+        return options.multiMajorMode;
+    }
+    const env = process.env[MULTI_MAJOR_MODE_ENV];
+    if (env === 'direct' || env === 'gradual')
+        return env;
+    return undefined;
+}
+// Whether the target is the canonical Nx package for its era (`@nrwl/workspace`
+// for legacy `< 14`, `nx`/`@nx/workspace` otherwise).
+function isNxTarget(targetPackage, targetVersion) {
+    if ((0, version_utils_1.isLegacyEra)(targetVersion)) {
+        return targetPackage === '@nrwl/workspace';
+    }
+    return targetPackage === 'nx' || targetPackage === '@nx/workspace';
+}
+async function maybePromptOrWarnMultiMajorMigration(args) {
+    const { include, options, targetPackage } = args;
+    let { targetVersion } = args;
+    if (include === 'optional')
+        return { chosen: targetVersion };
+    const multiMajorMode = resolveMultiMajorMode(options);
+    if (multiMajorMode === 'direct') {
+        return { chosen: targetVersion, decision: 'direct' };
+    }
+    // The multi-major catch-up only applies to Nx's own versioned cascade, so it
+    // keys off the canonical Nx package identity, not `--include` eligibility.
+    if (!isNxTarget(targetPackage, targetVersion)) {
+        return { chosen: targetVersion };
+    }
+    // Bare-package-name positionals (e.g. `nx migrate nx`, `nx migrate
+    // @nx/workspace`) leave `targetVersion` as the literal `'latest'` because
+    // `parseTargetPackageAndVersion` only resolves dist-tags via the registry
+    // when they appear standalone or after `@`. Resolve here so the remaining
+    // semver gates (and the subsequent walk) see a concrete version.
+    if (version_utils_1.DIST_TAGS.includes(targetVersion)) {
+        try {
+            targetVersion = await (0, version_utils_1.normalizeVersionWithTagCheck)(targetPackage, targetVersion);
+        }
+        catch {
+            if (multiMajorMode === 'gradual') {
+                warnGradualUnavailable(targetPackage, targetVersion, `Failed to resolve the '${targetVersion}' dist-tag against the registry.`);
+            }
+            return { chosen: targetVersion };
+        }
+    }
+    if (!(0, semver_1.valid)(targetVersion) || (0, version_utils_1.isLegacyEra)(targetVersion)) {
+        return { chosen: targetVersion };
+    }
+    const installed = (0, installed_nx_version_1.getInstalledNxVersion)();
+    if (!installed || !(0, semver_1.valid)(installed))
+        return { chosen: targetVersion };
+    // Legacy-era installs are out of scope for the multi-major check.
+    if ((0, version_utils_1.isLegacyEra)(installed))
+        return { chosen: targetVersion };
+    const installedMajor = (0, semver_1.major)(installed);
+    if ((0, semver_1.major)(targetVersion) - installedMajor < 2) {
+        return { chosen: targetVersion };
+    }
+    const interactive = (0, safe_prompt_1.canPrompt)(options.interactive);
+    // Non-interactive (non-TTY, CI, or --no-interactive) without gradual opt-in
+    // stays on the warn-only path; avoid the registry round-trip used to look
+    // up incremental migration options.
+    if (!interactive && multiMajorMode !== 'gradual') {
+        warnMultiMajorMigration(targetPackage, installed, targetVersion);
+        return { chosen: targetVersion, decision: 'direct' };
+    }
+    const [latestInCurrent, latestInNext] = await Promise.all([
+        resolveLatestStableInMajor(targetPackage, installedMajor),
+        resolveLatestStableInMajor(targetPackage, installedMajor + 1),
+    ]);
+    // Only suggest the current-major latest when there's at least a minor
+    // delta — a same-minor patch bump isn't a meaningful incremental step. Skip
+    // major 22 (the last release before the v23 era): a within-22 step doesn't
+    // advance toward a v23+ target, so suggest the next major instead.
+    const showCurrent = installedMajor !== 22 &&
+        latestInCurrent &&
+        (0, semver_1.gt)(latestInCurrent, installed) &&
+        (0, semver_1.minor)(latestInCurrent) > (0, semver_1.minor)(installed)
+        ? latestInCurrent
+        : null;
+    if (multiMajorMode === 'gradual') {
+        const step = showCurrent ?? latestInNext;
+        if (step) {
+            logGradualStep(targetPackage, step, targetVersion);
+            return {
+                chosen: step,
+                originalTarget: targetVersion,
+                gradual: true,
+                decision: 'gradual',
+            };
+        }
+        // Registry returned no eligible incremental version (or the lookup
+        // failed); without a step to land on, gradual silently degrades to direct.
+        // Surface that explicitly so the safety rail the user opted into isn't
+        // invisibly disabled.
+        warnGradualUnavailable(targetPackage, targetVersion, `Could not find an eligible version in major ${installedMajor} or ${installedMajor + 1} (registry lookup returned no result or failed).`);
+        return { chosen: targetVersion, decision: 'direct' };
+    }
+    if (interactive && (showCurrent || latestInNext)) {
+        const chosen = await promptMultiMajorMigration({
+            targetPackage,
+            installed,
+            target: targetVersion,
+            latestInCurrent: showCurrent,
+            latestInNext,
+        });
+        // The prompt returns a concrete version; map it back to the option the
+        // user picked for the prompt event's choice, then collapse to
+        // gradual/direct for the returned decision (any incremental step counts
+        // as gradual).
+        (0, migrate_analytics_1.reportMigratePrompt)('multi_major', chosen === targetVersion
+            ? 'direct'
+            : chosen === showCurrent
+                ? 'latest-in-current'
+                : 'latest-in-next');
+        return chosen !== targetVersion
+            ? { chosen, originalTarget: targetVersion, decision: 'gradual' }
+            : { chosen, decision: 'direct' };
+    }
+    warnMultiMajorMigration(targetPackage, installed, targetVersion);
+    return { chosen: targetVersion, decision: 'direct' };
+}

package/dist/src/command-line/migrate/prompt-files.d.ts

@@ -0,0 +1,31 @@
+import { MigrationsJson } from '../../config/misc-interfaces';
+export declare const AI_MIGRATIONS_DIR: string;
+export declare function promptContentKey(packageName: string, promptRelPath: string): string;
+export declare function validateMigrationEntries(packageName: string, packageVersion: string, migrations: MigrationsJson): void;
+/**
+ * Thrown when the markdown prompt file referenced by a migration cannot be
+ * resolved.
+ */
+export declare class PromptResolutionError extends Error {
+    readonly promptPath: string;
+    readonly migrationsDir: string;
+    constructor(promptPath: string, migrationsDir: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Resolves a migration prompt file path to an absolute path. Prompt paths are
+ * plain markdown files referenced relative to the directory containing the
+ * `migrations.json` - unlike schemas, they are not resolved through package
+ * exports or `require.resolve`. The path must stay within the migrations
+ * directory and point at an existing file.
+ */
+export declare function resolvePrompt(promptPath: string, migrationsDir: string): string;
+export declare function extractPromptFilesFromTarball(packageName: string, packageVersion: string, migrations: MigrationsJson, migrationsFilePath: string, fullTarballPath: string, destDir: string): Promise<Record<string, string> | undefined>;
+export declare function readPromptFilesFromInstall(packageName: string, packageVersion: string, migrations: MigrationsJson, migrationsFilePath: string): Promise<Record<string, string> | undefined>;
+export declare function writePromptMigrationFiles(root: string, migrations: {
+    package: string;
+    name: string;
+    version: string;
+    prompt?: string;
+}[], promptContents: Record<string, string>, targetVersion: string): string[];

package/dist/src/command-line/migrate/prompt-files.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptResolutionError = exports.AI_MIGRATIONS_DIR = void 0;
+exports.promptContentKey = promptContentKey;
+exports.validateMigrationEntries = validateMigrationEntries;
+exports.resolvePrompt = resolvePrompt;
+exports.extractPromptFilesFromTarball = extractPromptFilesFromTarball;
+exports.readPromptFilesFromInstall = readPromptFilesFromInstall;
+exports.writePromptMigrationFiles = writePromptMigrationFiles;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const tar_1 = require("../../utils/tar");
+const path_2 = require("../../utils/path");
+exports.AI_MIGRATIONS_DIR = (0, path_2.joinPathFragments)('tools', 'ai-migrations');
+function promptContentKey(packageName, promptRelPath) {
+    return `${packageName}::${promptRelPath}`;
+}
+function* iterateMigrationEntries(migrations) {
+    const merged = { ...migrations.schematics, ...migrations.generators };
+    yield* Object.entries(merged);
+}
+function validateMigrationEntries(packageName, packageVersion, migrations) {
+    for (const [migrationName, entry] of iterateMigrationEntries(migrations)) {
+        if (!entry.implementation && !entry.factory && !entry.prompt) {
+            throw new Error(`Invalid migration "${migrationName}" in package "${packageName}@${packageVersion}": migration entries must have at least one of "implementation", "factory", or "prompt".`);
+        }
+    }
+}
+async function resolvePromptFiles(packageName, packageVersion, migrations, migrationsDir, resolveContent) {
+    const resolvedPromptFiles = {};
+    for (const [migrationName, entry] of iterateMigrationEntries(migrations)) {
+        if (!entry.prompt || resolvedPromptFiles[entry.prompt] !== undefined) {
+            continue;
+        }
+        assertPromptPathWithinMigrationsDir(migrationsDir, entry.prompt, packageName, packageVersion);
+        try {
+            resolvedPromptFiles[entry.prompt] = await resolveContent(entry.prompt);
+        }
+        catch (e) {
+            throw new Error(`Could not find prompt file "${entry.prompt}" for migration "${migrationName}" in package "${packageName}@${packageVersion}".`, { cause: e });
+        }
+    }
+    return Object.keys(resolvedPromptFiles).length > 0
+        ? resolvedPromptFiles
+        : undefined;
+}
+function assertPromptPathWithinMigrationsDir(migrationsDir, promptRelPath, packageName, packageVersion) {
+    if (!(0, path_2.isContainedRelativePath)(promptRelPath)) {
+        throw new Error(`Invalid prompt path "${promptRelPath}" in package "${packageName}@${packageVersion}": prompt paths must be relative and resolve within the package's migrations directory.`);
+    }
+}
+/**
+ * Thrown when the markdown prompt file referenced by a migration cannot be
+ * resolved.
+ */
+class PromptResolutionError extends Error {
+    constructor(promptPath, migrationsDir, options) {
+        super(`Could not resolve prompt "${promptPath}" from "${migrationsDir}".`, options);
+        this.promptPath = promptPath;
+        this.migrationsDir = migrationsDir;
+        this.name = 'PromptResolutionError';
+    }
+}
+exports.PromptResolutionError = PromptResolutionError;
+/**
+ * Resolves a migration prompt file path to an absolute path. Prompt paths are
+ * plain markdown files referenced relative to the directory containing the
+ * `migrations.json` - unlike schemas, they are not resolved through package
+ * exports or `require.resolve`. The path must stay within the migrations
+ * directory and point at an existing file.
+ */
+function resolvePrompt(promptPath, migrationsDir) {
+    if (!(0, path_2.isContainedRelativePath)(promptPath)) {
+        throw new PromptResolutionError(promptPath, migrationsDir);
+    }
+    const resolvedPath = (0, path_1.join)(migrationsDir, promptPath);
+    if (!(0, fs_1.existsSync)(resolvedPath)) {
+        throw new PromptResolutionError(promptPath, migrationsDir);
+    }
+    return resolvedPath;
+}
+function extractPromptFilesFromTarball(packageName, packageVersion, migrations, migrationsFilePath, fullTarballPath, destDir) {
+    const migrationsDir = (0, path_1.dirname)(migrationsFilePath);
+    return resolvePromptFiles(packageName, packageVersion, migrations, migrationsDir, async (promptRelPath) => {
+        const promptInTarball = (0, path_2.joinPathFragments)('package', migrationsDir, promptRelPath);
+        const promptDest = (0, path_1.join)(destDir, migrationsDir, promptRelPath);
+        await (0, tar_1.extractFileFromTarball)(fullTarballPath, promptInTarball, promptDest);
+        return (0, fs_1.readFileSync)(promptDest, 'utf-8');
+    });
+}
+function readPromptFilesFromInstall(packageName, packageVersion, migrations, migrationsFilePath) {
+    const migrationsDir = (0, path_1.dirname)(migrationsFilePath);
+    return resolvePromptFiles(packageName, packageVersion, migrations, migrationsDir, (promptRelPath) => (0, fs_1.readFileSync)((0, path_1.join)(migrationsDir, promptRelPath), 'utf-8'));
+}
+function writePromptMigrationFiles(root, migrations, promptContents, targetVersion) {
+    const sourceToChosen = new Map();
+    const result = [];
+    for (const migration of migrations) {
+        if (!migration.prompt)
+            continue;
+        const sourceKey = promptContentKey(migration.package, migration.prompt);
+        const content = promptContents[sourceKey];
+        if (content === undefined)
+            continue;
+        const cached = sourceToChosen.get(sourceKey);
+        if (cached !== undefined) {
+            migration.prompt = cached;
+            continue;
+        }
+        const baseName = path_1.posix.basename(migration.prompt);
+        const ext = path_1.posix.extname(baseName);
+        const stem = ext ? baseName.slice(0, -ext.length) : baseName;
+        const destDir = (0, path_2.joinPathFragments)(exports.AI_MIGRATIONS_DIR, migration.package, targetVersion);
+        let chosenPath;
+        for (let n = 0;; n++) {
+            const candidate = (0, path_2.joinPathFragments)(destDir, n === 0 ? baseName : `${stem}-${n}${ext}`);
+            const absCandidate = (0, path_1.join)(root, candidate);
+            if (!(0, fs_1.existsSync)(absCandidate)) {
+                (0, fs_1.mkdirSync)((0, path_1.dirname)(absCandidate), { recursive: true });
+                (0, fs_1.writeFileSync)(absCandidate, content);
+                result.push(candidate);
+                chosenPath = candidate;
+                break;
+            }
+            if ((0, fs_1.readFileSync)(absCandidate, 'utf-8') === content) {
+                chosenPath = candidate;
+                break;
+            }
+        }
+        sourceToChosen.set(sourceKey, chosenPath);
+        migration.prompt = chosenPath;
+    }
+    return result;
+}

package/dist/src/command-line/migrate/resolve-package-version.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether nx migrate should resolve versions via the npm registry (fast) rather
+ * than via a real package-manager install. Precedence, highest first:
+ *
+ * 1. `NX_MIGRATE_USE_REGISTRY_RESOLUTION` ('true' -> enabled, 'false' -> disabled)
+ * 2. legacy `NX_MIGRATE_SKIP_REGISTRY_FETCH` (deprecated, removed in Nx 24;
+ *    'true' -> disabled, 'false' -> enabled)
+ * 3. nx.json `migrate.useRegistryResolution`
+ * 4. default: enabled
+ */
+export declare function isRegistryResolutionEnabled(root?: string): boolean;
+/** Test-only: clear the module-level caches between cases. */
+export declare function resetResolvePackageVersionState(): void;
+/**
+ * The single resolution entry point for ALL nx migrate version resolutions. It
+ * resolves a package spec to a concrete version while honoring the effective
+ * minimum-release-age (cooldown) policy of the user's package manager, matching
+ * how that PM at its detected version would resolve. Falls back to a real PM
+ * install when the policy can't be reasoned about, or when registry resolution
+ * is opted out.
+ */
+export declare function resolvePackageVersionRespectingMinReleaseAge(packageName: string, version: string, options?: {
+    applySideEffects?: boolean;
+}): Promise<string>;