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

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

@@ -0,0 +1,378 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setMigrateInclude = setMigrateInclude;
+exports.setMigrateIncludeSource = setMigrateIncludeSource;
+exports.classifyMigrateFetchFallback = classifyMigrateFetchFallback;
+exports.reportMigratePrompt = reportMigratePrompt;
+exports.reportMigrateGenerateStart = reportMigrateGenerateStart;
+exports.reportMigrateGenerateComplete = reportMigrateGenerateComplete;
+exports.reportMigrateGenerateError = reportMigrateGenerateError;
+exports.reportMigrateRunStart = reportMigrateRunStart;
+exports.hasMigrateRunStarted = hasMigrateRunStarted;
+exports.reportMigrateRunComplete = reportMigrateRunComplete;
+exports.reportMigrateRunError = reportMigrateRunError;
+exports.reportMigrateOrchestratorInit = reportMigrateOrchestratorInit;
+exports.reportMigrateOrchestratorDispense = reportMigrateOrchestratorDispense;
+exports.reportMigrateOrchestratorStepDispensed = reportMigrateOrchestratorStepDispensed;
+exports.reportMigrateOrchestratorComplete = reportMigrateOrchestratorComplete;
+exports.reportMigrateOrchestratorAbandoned = reportMigrateOrchestratorAbandoned;
+exports.reportMigrateOrchestratorResume = reportMigrateOrchestratorResume;
+exports.reportMigrateOrchestratorExistingRun = reportMigrateOrchestratorExistingRun;
+exports.reportMigrateSingleMigrationInvocation = reportMigrateSingleMigrationInvocation;
+exports.computeMajorsCrossed = computeMajorsCrossed;
+exports.safeReport = safeReport;
+const semver_1 = require("semver");
+const analytics_1 = require("../../analytics");
+const provenance_1 = require("../../utils/provenance");
+const workspace_root_1 = require("../../utils/workspace-root");
+// Identifier-shaped tokens only (Node codes like ENOENT, class names like
+// TypeError). Rejects anything with a slash, space, or punctuation so a
+// settable `.code`/`.name` can't smuggle a path or message into GA.
+const IDENTIFIER_SHAPE = /^[A-Za-z][A-Za-z0-9_]*$/;
+// Context collected across the flow and folded into the completion/error
+// events. `_migrate` executes a single migrate invocation per process, so
+// module state is safe.
+let resolvedInclude;
+let includeSource;
+let generateErrorRecorded = false;
+let runErrorRecorded = false;
+let runStarted = false;
+function setMigrateInclude(include) {
+    resolvedInclude = include;
+}
+function setMigrateIncludeSource(source) {
+    includeSource = source;
+}
+function classifyMigrateFetchFallback(error) {
+    if (error instanceof provenance_1.ProvenanceError) {
+        return 'provenance';
+    }
+    if (error instanceof Error &&
+        error.message.includes('is not supported from')) {
+        return 'unsupported-registry';
+    }
+    return 'registry-error';
+}
+/**
+ * Records an interactive migrate prompt and the user's selection.
+ *
+ * The prompt identity is encoded in the event name (`migrate_prompt_<prompt>`)
+ * so it doesn't cost a GA custom dimension; `choice` is one dimension
+ * multiplexed across all prompts, read conditioned on the event name. The
+ * per-prompt value-spaces are typed in {@link MigratePromptChoices}.
+ */
+function reportMigratePrompt(prompt, choice) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)(`migrate_prompt_${prompt}`, {
+            [analytics_1.customDimensions.promptChoice]: choice,
+        });
+    });
+}
+function reportMigrateGenerateStart(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_generate_start', {
+            // Resolved migration target (defaults to `nx`; only an explicit
+            // non-first-party target is third-party). Reported raw per the `nx add`
+            // precedent - it's the chosen target, not a transitive dep like
+            // `run_error`'s `migration_name`, so there's no dependency-graph leak.
+            [analytics_1.customDimensions.packageName]: opts.targetPackage,
+            [analytics_1.customDimensions.cliSource]: cliSource(),
+            [analytics_1.customDimensions.interactive]: opts.interactive,
+            [analytics_1.customDimensions.excludeAppliedMigrations]: opts.excludeAppliedMigrations,
+        });
+    });
+}
+function reportMigrateGenerateComplete(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        const majorsCrossed = computeMajorsCrossed(opts.installedTargetVersion, opts.requestedTargetVersion);
+        const { registryCount = 0, installCount = 0 } = opts.fetchStats ?? {};
+        const fetchMethod = registryCount > 0 && installCount > 0
+            ? 'mixed'
+            : installCount > 0
+                ? 'install'
+                : registryCount > 0
+                    ? 'registry'
+                    : undefined;
+        (0, analytics_1.reportEvent)('migrate_generate_complete', {
+            [analytics_1.customDimensions.packageVersion]: opts.targetVersion,
+            [analytics_1.customDimensions.include]: opts.include,
+            [analytics_1.customDimensions.includeSource]: includeSource,
+            [analytics_1.customDimensions.majorsCrossed]: majorsCrossed,
+            // Only meaningful when the multi-major gate (2+ majors) applied.
+            ...(majorsCrossed !== undefined &&
+                majorsCrossed >= 2 &&
+                opts.multiMajorChoice
+                ? { [analytics_1.customDimensions.multiMajorChoice]: opts.multiMajorChoice }
+                : {}),
+            [analytics_1.customDimensions.fetchMethod]: fetchMethod,
+            [analytics_1.customDimensions.fetchFallbackReason]: opts.fetchStats?.fallbackReason,
+        });
+    });
+}
+function reportMigrateGenerateError(code, error) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions || generateErrorRecorded)
+            return;
+        generateErrorRecorded = true;
+        // The failing phase is encoded in the event name so it doesn't cost a GA
+        // custom dimension.
+        (0, analytics_1.reportEvent)(`migrate_generate_error_${code}`, {
+            // Populated only when include resolution had already happened when the
+            // failure occurred; earlier failures leave these undefined.
+            [analytics_1.customDimensions.include]: resolvedInclude,
+            [analytics_1.customDimensions.includeSource]: includeSource,
+            [analytics_1.customDimensions.errorName]: errorName(error),
+            [analytics_1.customDimensions.errorLocation]: errorLocation(error),
+        });
+    });
+}
+function reportMigrateRunStart(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        runStarted = true;
+        // No cli_source here: the run phase always executes from the local
+        // installation (the temp-install process re-dispatches before this point).
+        (0, analytics_1.reportEvent)('migrate_run_start', {
+            [analytics_1.customDimensions.createCommits]: opts.createCommits,
+            [analytics_1.customDimensions.migrationCount]: opts.migrationCount,
+        });
+    });
+}
+/**
+ * Whether the current process recorded a `migrate_run_start` event. Lets
+ * shared code paths (e.g. `executeMigrations`, reused by `nx repair`) skip
+ * migrate events when not running inside a migrate run.
+ */
+function hasMigrateRunStarted() {
+    return runStarted;
+}
+function reportMigrateRunComplete(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_run_complete', {
+            [analytics_1.customDimensions.agenticOutcome]: opts.agenticOutcome,
+            [analytics_1.customDimensions.agentUsed]: opts.agentUsed,
+            [analytics_1.customDimensions.migrationCount]: opts.migrationCount,
+            [analytics_1.customDimensions.appliedCount]: opts.appliedCount,
+        });
+    });
+}
+function reportMigrateRunError(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions || runErrorRecorded)
+            return;
+        runErrorRecorded = true;
+        // The failing step is encoded in the event name so it doesn't cost a GA
+        // custom dimension.
+        (0, analytics_1.reportEvent)(`migrate_run_error_${opts.code}`, {
+            // Third-party migration names can reveal private packages; only report
+            // first-party ones.
+            ...(opts.migrationPackage &&
+                opts.migrationName &&
+                isFirstPartyMigrationPackage(opts.migrationPackage)
+                ? {
+                    [analytics_1.customDimensions.migrationName]: `${opts.migrationPackage}:${opts.migrationName}`,
+                }
+                : {}),
+            [analytics_1.customDimensions.migrationCount]: opts.migrationCount,
+            [analytics_1.customDimensions.errorName]: opts.error !== undefined ? errorName(opts.error) : undefined,
+            [analytics_1.customDimensions.errorLocation]: opts.error !== undefined ? errorLocation(opts.error) : undefined,
+        });
+    });
+}
+function reportMigrateOrchestratorInit(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_init', {
+            [analytics_1.customDimensions.createCommits]: opts.createCommits,
+            [analytics_1.customDimensions.migrationCount]: opts.migrationCount,
+        });
+    });
+}
+/**
+ * One event per dispense response, repeated on every reconcile until the
+ * step moves. The `action` (dispense case) is a closed enum carried on a
+ * reused dimension, read conditioned on the event name (the same
+ * multiplexing pattern as {@link reportMigratePrompt}); `attempt` rides the
+ * migration-count dimension and `ordinal` (the run's dispense count) the
+ * task-count one.
+ */
+function reportMigrateOrchestratorDispense(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_dispense', {
+            [analytics_1.customDimensions.promptChoice]: opts.action,
+            [analytics_1.customDimensions.migrationCount]: opts.attempt,
+            [analytics_1.customDimensions.taskCount]: opts.ordinal,
+        });
+    });
+}
+/** Once per durable dispense transition. */
+function reportMigrateOrchestratorStepDispensed(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_step_dispensed', {
+            [analytics_1.customDimensions.migrationCount]: opts.attempt,
+            [analytics_1.customDimensions.taskCount]: opts.ordinal,
+        });
+    });
+}
+/**
+ * The three step tallies and the total dispense count ride reused numeric
+ * dimensions, read conditioned on the event name.
+ */
+function orchestratorTallyParams(tallies) {
+    return {
+        [analytics_1.customDimensions.appliedCount]: tallies.completed,
+        [analytics_1.customDimensions.taskCount]: tallies.skipped,
+        [analytics_1.customDimensions.majorsCrossed]: tallies.unresolved,
+        [analytics_1.customDimensions.migrationCount]: tallies.dispenseCount,
+    };
+}
+function reportMigrateOrchestratorComplete(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_complete', orchestratorTallyParams(opts));
+    });
+}
+/** The agent session nx spawned ended with the run still active. */
+function reportMigrateOrchestratorAbandoned(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_abandoned', {
+            ...orchestratorTallyParams(opts),
+            [analytics_1.customDimensions.agentUsed]: opts.agentUsed,
+        });
+    });
+}
+/**
+ * An explicit continue (`--run-migrations --run-id`, or "continue" at the
+ * master prompt) took up an active run; every resume reports. A bare
+ * `--run-id` reconcile is not a resume: nothing in run state marks the first
+ * call after a lost session.
+ */
+function reportMigrateOrchestratorResume(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_resume', orchestratorTallyParams(opts));
+    });
+}
+/**
+ * An invocation found an active run and started nothing. `activity` says
+ * whether another nx migrate process held the run; 'unknown' where nx cannot
+ * tell.
+ */
+function reportMigrateOrchestratorExistingRun(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_existing_run', {
+            ...orchestratorTallyParams(opts),
+            [analytics_1.customDimensions.promptChoice]: opts.activity,
+        });
+    });
+}
+/**
+ * Counts invocations, not completions: emitted as soon as the migration id
+ * resolves, while the worker can still stop before running anything.
+ *
+ * An invocation recorded into an orchestrated run (`--run-id`) gets its own
+ * event name. Every other one keeps the name `--run-migration` shipped with,
+ * so that series stays continuous for users who never enable the orchestrator.
+ */
+function reportMigrateSingleMigrationInvocation(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)(opts.orchestrated
+            ? 'migrate_single_migration_recorded'
+            : 'migrate_single_migration_invocation', {
+            [analytics_1.customDimensions.promptChoice]: opts.migrationType,
+        });
+    });
+}
+// `_migrate` runs either from a temp install of the latest CLI or from the
+// workspace-local installation; same signal as the run-phase re-dispatch
+// check in migrate.ts.
+function cliSource() {
+    return __dirname.startsWith(workspace_root_1.workspaceRoot) ? 'local' : 'temp-latest';
+}
+// `coerce` tolerates ranges and partial versions from package.json entries
+// (e.g. `^21.0.0`); dist-tags that never resolved coerce to null.
+function computeMajorsCrossed(installed, target) {
+    const installedVersion = installed ? (0, semver_1.coerce)(installed) : null;
+    const targetVersion = target ? (0, semver_1.coerce)(target) : null;
+    if (!installedVersion || !targetVersion) {
+        return undefined;
+    }
+    return Math.max(0, targetVersion.major - installedVersion.major);
+}
+function isFirstPartyMigrationPackage(packageName) {
+    return (packageName === 'nx' ||
+        packageName.startsWith('@nx/') ||
+        packageName.startsWith('@nrwl/'));
+}
+// Structured error identity instead of the raw message: a Node system `code`
+// (ENOENT, ETIMEDOUT), else the constructor name (TypeError, ProvenanceError),
+// else the bare type. `.code`/`.name` are settable, so a migration could stuff
+// a path or message into them - only accept identifier-shaped tokens and fall
+// back to the bare type, so no free text reaches GA.
+function errorName(error) {
+    const code = error?.code;
+    if (typeof code === 'string' && IDENTIFIER_SHAPE.test(code)) {
+        return code;
+    }
+    if (error instanceof Error && IDENTIFIER_SHAPE.test(error.name)) {
+        return error.name;
+    }
+    return typeof error;
+}
+// Topmost stack frame inside a first-party package (nx, @nx/*, @nrwl/*),
+// package-qualified and relative to the package root (e.g.
+// `nx/src/command-line/migrate/migrate.js:1830:18`). The absolute prefix and
+// `dist/` are stripped so no user path leaks, and non-first-party frames are
+// skipped so a failing third-party migration can't surface a private package
+// path. Caveats: the topmost first-party frame may be a dispatcher rather than
+// the exact throw site, and (no shipped sourcemaps) the line:col is in the
+// compiled JS - so this locates against `nx_version`, not the TS source.
+function errorLocation(error) {
+    if (!(error instanceof Error) || !error.stack)
+        return undefined;
+    for (const line of error.stack.split('\n')) {
+        const match = line
+            .replace(/\\/g, '/')
+            .match(/\/node_modules\/((?:@(?:nx|nrwl)\/[^/]+|nx))\/(?:dist\/)?(src\/.+?:\d+:\d+)/);
+        if (match)
+            return `${match[1]}/${match[2]}`;
+    }
+    return undefined;
+}
+// Analytics is a secondary concern and must never interfere with the migrate
+// run. Swallow any failure while building params or emitting the event
+// (surfaced only under verbose logging), mirroring `trackEvent`/`flushAnalytics`
+// in `../../analytics`. Exported for callers whose param-building expressions
+// evaluate before the report function is entered.
+function safeReport(emit) {
+    try {
+        emit();
+    }
+    catch (e) {
+        if (process.env.NX_VERBOSE_LOGGING === 'true') {
+            console.log(`Failed to record migrate analytics event: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+}

package/dist/src/command-line/migrate/migrate-commits.d.ts

@@ -0,0 +1,81 @@
+import type { ResolvedAgentic } from './agentic/types';
+import { type MigrateOutputSink } from './deferred-output';
+/**
+ * Discriminated result for `commitMigrationIfRequested`. Distinguishes the
+ * shapes the executor needs to react to:
+ *
+ * - `committed`: a commit landed. `sha` is `null` only when `git rev-parse
+ *   HEAD` failed transiently — by contract the diff is no longer in the
+ *   working tree.
+ * - `no-changes`: commits were requested but there was nothing to commit.
+ * - `failed`: the attempt errored, possibly after the commit landed; tracked
+ *   as pending so the next successful commit can annotate its body.
+ * - `disabled`: commits are off for this run.
+ */
+export type CommitResult = {
+    status: 'committed';
+    sha: string | null;
+} | {
+    status: 'no-changes';
+} | {
+    status: 'failed';
+    reason: string;
+} | {
+    status: 'disabled';
+};
+/**
+ * `pendingMigrations` are listed in the commit body so a `git log -p` reader
+ * can see which earlier migrations' diffs this commit absorbed (their own
+ * commits failed and `git add -A` picked their working-tree state up too).
+ *
+ * The default `failureGuidance` describes the classic loop's absorb-and-recap
+ * behavior; a caller with no later commit or recap to absorb the diff (the
+ * standalone single-migration worker) passes its own.
+ */
+export declare function commitMigrationIfRequested(root: string, migration: {
+    name: string;
+}, shouldCreateCommits: boolean, commitPrefix: string, installDepsIfChanged: () => Promise<void>, pendingMigrations?: ReadonlyArray<{
+    package: string;
+    name: string;
+}>, failureGuidance?: string, out?: MigrateOutputSink): Promise<CommitResult>;
+/**
+ * Commits any pre-existing working-tree state into a dedicated "checkpoint"
+ * commit before the first migration runs. Without this, the first migration's
+ * commit would absorb whatever was already pending — most commonly the
+ * package.json edit `nx migrate latest` produces and the lockfile churn from
+ * the orchestrator's `npm install --ignore-scripts` step — and migration 1's
+ * validation would see that mixed in with the generator output. No-op when
+ * the working tree is already clean.
+ */
+export declare function commitCheckpointBeforeMigrations(root: string, commitPrefix: string): void;
+/**
+ * `agenticHasDiffContext` gates the agent prompt: without per-migration commits
+ * to isolate a migration's diff, the prompt embeds a file list instead of
+ * pointing at git.
+ */
+export declare function resolveCreateCommits(args: {
+    createCommits: boolean | undefined;
+    mode: ResolvedAgentic['kind'] | 'orchestrated';
+    isGitRepo: boolean;
+    commitPrefixIsCustom?: boolean;
+}): {
+    effective: boolean;
+    agenticHasDiffContext: boolean;
+    warning?: string;
+    error?: string;
+};
+export declare function currentBranchIfDefault(root: string): string | null;
+/**
+ * Asks before a run starts committing on the workspace's default branch, and
+ * reports the decision when the answer is no. Returns whether to proceed.
+ *
+ * Callers gate this on commits being effective and on prompting being
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here;
+ * `confirmCommitsOnDefaultBranch` has no guard of its own and would block on a
+ * prompt nobody can answer.
+ */
+export declare function confirmMigrationCommitsOnDefaultBranch(root: string, whatWouldRun: 'running migrations' | 'running the migration'): Promise<boolean>;
+export declare function confirmCommitsOnDefaultBranch(args: {
+    currentBranch: string | null;
+    defaultBranch: string | null;
+}): Promise<boolean>;