nx 23.2.0-beta.7 → 23.2.0-beta.8

package/dist/src/project-graph/utils/project-configuration/target-normalization.js

@@ -5,6 +5,8 @@ exports.normalizeTarget = normalizeTarget;
 exports.validateAndNormalizeProjectRootMap = validateAndNormalizeProjectRootMap;
 const executor_utils_1 = require("../../../command-line/run/executor-utils");
 const fileutils_1 = require("../../../utils/fileutils");
+const long_running_target_1 = require("../../../utils/long-running-target");
+const output_1 = require("../../../utils/output");
 const to_project_name_1 = require("../../../config/to-project-name");
 const error_types_1 = require("../../error-types");
 const target_merging_1 = require("./target-merging");
@@ -65,15 +67,137 @@ function normalizeTarget(target, project, workspaceRoot, projectsMap, errorMsgKe
     }
     return target;
 }
+// TODO(v24): remove the legacy target-name cache fallback and its warning.
+// Removal needs a second mechanism for plugin-inferred targets, which the
+// accompanying migration cannot reach.
+/**
+ * Whether `target` is cacheable only by way of the legacy name-based fallback:
+ * the exact target-name key of `targetDefaults` declares `cache: true`, but an
+ * executor key won target-default resolution instead, so the merged target never
+ * received it.
+ *
+ * A `true` result means the user's `cache: true` silently lost, so this doubles
+ * as the condition for warning them that the name key is being shadowed.
+ */
+function isLegacyCachedTarget(targetName, targetDefaults, target) {
+    // Resolution already decided `cache`, so the name key isn't shadowed.
+    if (target.cache !== undefined) {
+        return false;
+    }
+    if (isLongRunningTarget(targetName, target)) {
+        return false;
+    }
+    // Restricted to shadowing, which is narrower than what pre-23 restored: that
+    // derivation matched on target name alone, so a name key dropped as
+    // incompatible (its entry declared a foreign executor) was cacheable too.
+    // Restoring that as well would mean writing `cache` with no key to name in
+    // the warning, and no migration able to retire it. Deliberately not covered.
+    if (!findShadowingTargetDefaultKey(targetDefaults, target)) {
+        return false;
+    }
+    return declaresCacheTrue(targetDefaults?.[targetName]);
+}
+/**
+ * Whether the name key declares `cache: true` on an entry that always applies.
+ *
+ * Filters are deliberately not evaluated. They cannot express a pre-23 config
+ * (the filtered array shape postdates the behavior being restored), and a
+ * filtered entry declaring `cache` may or may not apply to this project — so
+ * rather than guess, a filtered `cache` declares the value unknowable and
+ * nothing is restored. Among unfiltered entries the last wins, matching the
+ * in-key merge order.
+ */
+function declaresCacheTrue(value) {
+    if (!value) {
+        return false;
+    }
+    const entries = Array.isArray(value) ? value : [value];
+    let declared;
+    for (const entry of entries) {
+        // `nx.json` is hand-edited; a null or scalar entry would throw here.
+        if (!entry || typeof entry !== 'object')
+            continue;
+        if (entry.cache === undefined)
+            continue;
+        if (entry.filter)
+            return false;
+        declared = entry.cache;
+    }
+    return declared === true;
+}
+/**
+ * The normalization-time half of the pre-23 `longRunningTask` guard, which kept
+ * `cacheableOperations` from ever making these cacheable. Its remaining clause
+ * — `task.overrides['watch']` — is a runtime invocation override with no target
+ * equivalent, so it has no counterpart here.
+ */
+function isLongRunningTarget(targetName, target) {
+    return !!target.continuous || (0, long_running_target_1.isLongRunningTargetName)(targetName);
+}
+/**
+ * The `targetDefaults` key that beat the target-name key for `target`. Only an
+ * executor key can: key precedence puts the exact target name ahead of every
+ * glob, so nothing else outranks it. Undefined when the name key lost for
+ * another reason (e.g. its entry declared a foreign executor and was dropped as
+ * incompatible) — see {@link isLegacyCachedTarget} for why that case is left
+ * alone even though pre-23 restored it.
+ *
+ * `hasOwnProperty` rather than a lookup: an executor named `__proto__` resolves
+ * through the prototype chain to a truthy object, which would report a key the
+ * user never wrote.
+ */
+function findShadowingTargetDefaultKey(targetDefaults, target) {
+    return target.executor &&
+        targetDefaults &&
+        Object.prototype.hasOwnProperty.call(targetDefaults, target.executor)
+        ? target.executor
+        : undefined;
+}
+/**
+ * Emits a single grouped warning for every (shadowing key, target-name key)
+ * pair that relied on the deprecated fallback. Grouping matters because the
+ * same pair recurs in every affected project — a per-target warning would
+ * print hundreds of identical lines in a large workspace.
+ */
+function warnAboutLegacyCachedTargets(legacyCacheReads) {
+    if (legacyCacheReads.size === 0) {
+        return;
+    }
+    const bodyLines = [];
+    for (const [shadowingKey, targetKeys] of legacyCacheReads) {
+        for (const targetKey of targetKeys) {
+            bodyLines.push(`  - "${shadowingKey}" does not set "cache", so it was read from "${targetKey}"`);
+        }
+    }
+    bodyLines.push('', 'An executor key applies to every target that resolves through it, so exclude any continuous target before setting "cache" on one — a target that is both cacheable and continuous is rejected.', 'Target defaults resolve to a single key rather than merging, so an executor key hides the target name key entirely.', 'Set "cache" on the executor key to keep these targets cacheable — reading it from the target name key is deprecated and will be removed in Nx 24.');
+    output_1.output.warn({
+        title: 'Some targets are only cacheable through a deprecated fallback.',
+        bodyLines,
+    });
+}
 function normalizeTargets(project, sourceMaps, nxJsonConfiguration, workspaceRoot, 
 /**
  * Project configurations keyed by project name
  */
-projects) {
+projects, 
+/**
+ * Shadowing `targetDefaults` key -> target name keys its `cache` was read
+ * from. Accumulated across projects so the deprecation warns once per pair.
+ */
+legacyCacheReads) {
     const targetErrorMessage = [];
     for (const targetName in project.targets) {
         project.targets[targetName] = normalizeTarget(project.targets[targetName], project, workspaceRoot, projects, [project.root, targetName].join(':'));
         const target = project.targets[targetName];
+        const targetDefaults = nxJsonConfiguration.targetDefaults;
+        if (isLegacyCachedTarget(targetName, targetDefaults, target)) {
+            target.cache = true;
+            // Always defined: `isLegacyCachedTarget` returns false without it.
+            const shadowingKey = findShadowingTargetDefaultKey(targetDefaults, target);
+            const targetKeys = legacyCacheReads.get(shadowingKey) ?? new Set();
+            targetKeys.add(targetName);
+            legacyCacheReads.set(shadowingKey, targetKeys);
+        }
         if (
         // If the target has no executor or command, it doesn't do anything
         !target.executor &&
@@ -106,6 +230,7 @@ function validateAndNormalizeProjectRootMap(workspaceRoot, projectRootMap, nxJso
     const conflicts = new Map();
     const projectRootsWithNoName = [];
     const validityErrors = [];
+    const legacyCacheReads = new Map();
     for (const root in projectRootMap) {
         const project = projectRootMap[root];
         // We're setting `// targets` as a comment `targets` is empty due to Project Crystal.
@@ -155,7 +280,7 @@ function validateAndNormalizeProjectRootMap(workspaceRoot, projectRootMap, nxJso
     for (const root in projectRootMap) {
         const project = projectRootMap[root];
         try {
-            normalizeTargets(project, sourceMaps, nxJsonConfiguration, workspaceRoot, projects);
+            normalizeTargets(project, sourceMaps, nxJsonConfiguration, workspaceRoot, projects, legacyCacheReads);
         }
         catch (e) {
             if (e instanceof error_types_1.WorkspaceValidityError) {
@@ -166,6 +291,7 @@ function validateAndNormalizeProjectRootMap(workspaceRoot, projectRootMap, nxJso
             }
         }
     }
+    warnAboutLegacyCachedTargets(legacyCacheReads);
     const errors = [];
     if (conflicts.size > 0) {
         errors.push(new error_types_1.MultipleProjectsWithSameNameError(conflicts, projects));

package/dist/src/tasks-runner/run-command.js

@@ -8,7 +8,7 @@ exports.constructLifeCycles = constructLifeCycles;
 exports.getRunner = getRunner;
 exports.getRunnerOptions = getRunnerOptions;
 const tslib_1 = require("tslib");
-const enquirer_1 = require("enquirer");
+const prompt_helpers_1 = require("../utils/prompt-helpers");
 const node_util_1 = require("node:util");
 const nx_json_1 = require("../config/nx-json");
 const client_1 = require("../daemon/client/client");
@@ -599,23 +599,19 @@ async function ensureWorkspaceIsInSyncAndGetGraphs(projectGraph, nxJson, project
 }
 async function promptForApplyingSyncGeneratorChanges() {
     try {
-        const promptConfig = {
-            name: 'applyChanges',
-            type: 'autocomplete',
-            message: 'Would you like to sync the identified changes to get your workspace up to date?',
+        // No footer slot, so the opt-out note is part of the message.
+        const applyChanges = await (0, prompt_helpers_1.selectPrompt)({
+            message: `Would you like to sync the identified changes to get your workspace up to date?${pc.dim('\nYou can skip this prompt by setting the `sync.applyChanges` option to `true` in your `nx.json`.\nFor more information, refer to the docs: https://nx.dev/concepts/sync-generators.')}`,
             choices: [
+                { value: 'yes', label: 'Yes, sync the changes and run the tasks' },
                 {
-                    name: 'yes',
-                    message: 'Yes, sync the changes and run the tasks',
-                },
-                {
-                    name: 'no',
-                    message: 'No, run the tasks without syncing the changes',
+                    value: 'no',
+                    label: 'No, run the tasks without syncing the changes',
                 },
             ],
-            footer: () => pc.dim('\nYou can skip this prompt by setting the `sync.applyChanges` option to `true` in your `nx.json`.\nFor more information, refer to the docs: https://nx.dev/concepts/sync-generators.'),
-        };
-        return await (0, enquirer_1.prompt)([promptConfig]).then(({ applyChanges }) => applyChanges === 'yes');
+            onCancel: () => process.exit(1),
+        });
+        return applyChanges === 'yes';
     }
     catch {
         process.exit(1);
@@ -623,26 +619,15 @@ async function promptForApplyingSyncGeneratorChanges() {
 }
 async function confirmRunningTasksWithSyncFailures() {
     try {
-        const promptConfig = {
-            name: 'runTasks',
-            type: 'autocomplete',
-            message: 'Would you like to ignore the sync failures and continue running the tasks?',
+        const runTasks = await (0, prompt_helpers_1.selectPrompt)({
+            message: `Would you like to ignore the sync failures and continue running the tasks?${pc.dim(`\nWhen running in CI and there are sync failures, the tasks won't run. Addressing the errors above is highly recommended to prevent failures in CI.`)}`,
             choices: [
-                {
-                    name: 'yes',
-                    message: 'Yes, ignore the failures and run the tasks',
-                },
-                {
-                    name: 'no',
-                    message: `No, don't run the tasks`,
-                },
+                { value: 'yes', label: 'Yes, ignore the failures and run the tasks' },
+                { value: 'no', label: `No, don't run the tasks` },
             ],
-            footer: () => pc.dim(`\nWhen running in CI and there are sync failures, the tasks won't run. Addressing the errors above is highly recommended to prevent failures in CI.`),
-        };
-        const runTasks = await (0, enquirer_1.prompt)([
-            promptConfig,
-        ]).then(({ runTasks }) => runTasks === 'yes');
-        if (!runTasks) {
+            onCancel: () => process.exit(1),
+        });
+        if (runTasks !== 'yes') {
             process.exit(1);
         }
     }

package/dist/src/tasks-runner/task-env.js

@@ -166,10 +166,13 @@ function getOwnerTargetForTask(task, graph) {
         for (const targets of Object.values(project.data.metadata.targetGroups)) {
             if (targets.includes(task.target.target)) {
                 for (const target of targets) {
-                    if (project.data.targets[target].metadata?.nonAtomizedTarget) {
+                    // a target group can name a target the project does not define —
+                    // inference plugins build the group and the targets separately, so
+                    // the two can disagree. skip the phantom rather than dereferencing it.
+                    if (project.data.targets[target]?.metadata?.nonAtomizedTarget) {
                         return [
                             target,
-                            project.data.targets[target].metadata?.nonAtomizedTarget,
+                            project.data.targets[target]?.metadata?.nonAtomizedTarget,
                         ];
                     }
                 }

package/dist/src/tasks-runner/utils.js

@@ -36,6 +36,7 @@ const fileutils_1 = require("../utils/fileutils");
 const find_matching_projects_1 = require("../utils/find-matching-projects");
 const legacy_depends_on_warning_1 = require("./legacy-depends-on-warning");
 const globs_1 = require("../utils/globs");
+const long_running_target_1 = require("../utils/long-running-target");
 const path_1 = require("../utils/path");
 const serialize_overrides_into_command_line_1 = require("../utils/serialize-overrides-into-command-line");
 const split_target_1 = require("../utils/split-target");
@@ -429,14 +430,9 @@ function isCacheableTask(task) {
     return task.cache;
 }
 function longRunningTask(task) {
-    const t = task.target.target;
     return (task.continuous ||
         (!!task.overrides['watch'] && task.overrides['watch'] !== 'false') ||
-        t.endsWith(':watch') ||
-        t.endsWith('-watch') ||
-        t === 'serve' ||
-        t === 'dev' ||
-        t === 'start');
+        (0, long_running_target_1.isLongRunningTargetName)(task.target.target));
 }
 // TODO: vsavkin remove when nx-cloud doesn't depend on it
 function unparse(options) {

package/dist/src/utils/analytics-prompt.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureAnalyticsPreferenceSet = ensureAnalyticsPreferenceSet;
 exports.promptForAnalyticsPreference = promptForAnalyticsPreference;
 const fs_1 = require("fs");
-const enquirer_1 = require("enquirer");
+const prompt_helpers_1 = require("./prompt-helpers");
 const path_1 = require("path");
 const output_1 = require("./output");
 const is_ci_1 = require("./is-ci");
@@ -47,16 +47,13 @@ async function promptForAnalyticsPreference() {
                 'Learn more: https://cloud.nx.app/privacy',
             ],
         });
-        const { enableAnalytics } = await (0, enquirer_1.prompt)({
-            type: 'confirm',
-            name: 'enableAnalytics',
+        return await (0, prompt_helpers_1.confirmationPrompt)({
             message: 'Share usage data with the Nx team?',
-            initial: true,
+            // Cancelling is a decline, not a failure.
+            onCancel: () => false,
         });
-        return enableAnalytics;
     }
     catch {
-        // User cancelled - default to false
         return false;
     }
 }

package/dist/src/utils/exit-codes.d.ts

@@ -13,3 +13,12 @@ export declare const EXPECTED_TERMINATION_SIGNALS: Set<number>;
  * Handles both Linux exact-match and macOS strsignal formats (e.g. "Terminated by Hangup: 1").
  */
 export declare function messageToCode(message: string): number;
+/**
+ * Ends the process the way an interrupted process ends: by SIGINT, not by
+ * exiting with its conventional code.
+ *
+ * A shell reports 130 either way, but a parent using waitpid sees
+ * `signal: 'SIGINT'` rather than `code: 130`, which is what tools wrapping nx
+ * check to tell "the user pressed Ctrl+C" from "the command failed".
+ */
+export declare function exitAsInterrupted(): never;

package/dist/src/utils/exit-codes.js

@@ -4,6 +4,7 @@ exports.EXPECTED_TERMINATION_SIGNALS = void 0;
 exports.signalToCode = signalToCode;
 exports.codeToSignal = codeToSignal;
 exports.messageToCode = messageToCode;
+exports.exitAsInterrupted = exitAsInterrupted;
 /**
  * Translates NodeJS signals to numeric exit code
  * @param signal
@@ -73,3 +74,21 @@ function messageToCode(message) {
         return 1;
     }
 }
+/**
+ * Ends the process the way an interrupted process ends: by SIGINT, not by
+ * exiting with its conventional code.
+ *
+ * A shell reports 130 either way, but a parent using waitpid sees
+ * `signal: 'SIGINT'` rather than `code: 130`, which is what tools wrapping nx
+ * check to tell "the user pressed Ctrl+C" from "the command failed".
+ */
+function exitAsInterrupted() {
+    // Windows has no signal disposition to inherit - `process.kill` there
+    // terminates with an arbitrary code - so keep the 128+SIGINT convention.
+    if (process.platform !== 'win32') {
+        // Any listener would swallow this; the default action is what terminates.
+        process.removeAllListeners('SIGINT');
+        process.kill(process.pid, 'SIGINT');
+    }
+    process.exit(130);
+}

package/dist/src/utils/fileutils.d.ts

@@ -27,6 +27,11 @@ interface YamlReadOptions {
      * Compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error.
      */
     json?: boolean;
+    /**
+     * Resolves only the tags every YAML parser must support, so every scalar stays
+     * a string instead of `true` or `12`.
+     */
+    failsafe?: boolean;
 }
 /**
  * Reads a YAML file and returns the object the YAML content represents.

package/dist/src/utils/fileutils.js

@@ -41,8 +41,13 @@ function readJsonFile(path, options) {
  */
 function readYamlFile(path, options) {
     const content = (0, node_fs_1.readFileSync)(path, 'utf-8');
-    const { load } = require('@zkochan/js-yaml');
-    return load(content, { ...options, filename: path });
+    const { load, FAILSAFE_SCHEMA } = require('@zkochan/js-yaml');
+    const { failsafe, ...loadOptions } = options ?? {};
+    return load(content, {
+        ...loadOptions,
+        ...(failsafe ? { schema: FAILSAFE_SCHEMA } : {}),
+        filename: path,
+    });
 }
 /**
  * Serializes the given data to JSON and writes it to a file.

package/dist/src/utils/git-utils.d.ts

@@ -52,8 +52,21 @@ export declare function isShallowRepository(directory?: string): boolean;
  */
 export declare function getFirstCommitSha(directory?: string): string | null;
 export declare function isGitRepository(directory?: string): boolean;
+export type GitRepositoryStatus = 'git' | 'not-git' | 'unknown';
+/**
+ * Like `isGitRepository`, but separates "this is not a git repository" from
+ * "the probe itself failed" (git not installed, permissions). Callers gating
+ * destructive or unverifiable behavior on the answer must fail closed on
+ * 'unknown' instead of reading a broken probe as a missing repository.
+ */
+export declare function getGitRepositoryStatus(directory?: string): GitRepositoryStatus;
 export declare function getGitCurrentBranch(directory?: string): string | null;
-export declare function hasUncommittedChanges(directory?: string): boolean;
+export declare function getGitRemoteNames(directory?: string): string[];
+export type WorkingTreeStatus = 'dirty' | 'clean' | 'unknown';
+export declare function getWorkingTreeStatus(directory?: string, excludePaths?: string[]): WorkingTreeStatus;
+export declare function hasUncommittedChanges(directory?: string, excludePaths?: string[]): boolean;
+export type PathCommitExposure = 'ignored' | 'tracked' | 'unignored' | 'unknown';
+export declare function getPathCommitExposure(dirPath: string, directory?: string): PathCommitExposure;
 export declare function getUncommittedChangesSnapshot(directory?: string): string;
 export declare function commitChanges(commitMessage: string, directory?: string): string | null;
 /**
@@ -66,6 +79,24 @@ export declare function commitChanges(commitMessage: string, directory?: string)
  * Returns `null` (rather than throwing) when the commit itself succeeded
  * but `git rev-parse HEAD` failed transiently — by contract the diff is
  * no longer in the working tree, so callers must NOT report it as such.
+ *
+ * `excludePaths` are `directory`-relative paths the commit must not capture,
+ * whatever the ignore rules say. Their working-tree files are left intact;
+ * only their index entries are put back to HEAD's state. Paths come from
+ * callers' own constants, never from user input.
  */
-export declare function tryCommitChanges(commitMessage: string, directory: string): string | null;
+export declare function tryCommitChanges(commitMessage: string, directory: string, excludePaths?: string[]): string | null;
 export declare function getLatestCommitSha(directory?: string): string | null;
+/**
+ * The shape of a recorded `git rev-parse` output: 40 hex chars, or 64 in a
+ * sha256 repository. Anything a caller persists and later interpolates into a
+ * command line has to be checked against this first.
+ */
+export declare const GIT_SHA: RegExp;
+/**
+ * Whether `ancestor` is reachable from `descendant`, i.e. resetting to
+ * `descendant` keeps `ancestor` in history. Returns false when the answer
+ * cannot be established (invalid input, not a repository, unknown commits),
+ * so callers treat an unverifiable commit as not preserved.
+ */
+export declare function isAncestorCommit(ancestor: string, descendant: string, directory?: string): boolean;

package/dist/src/utils/git-utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GitRepository = void 0;
+exports.GIT_SHA = exports.GitRepository = void 0;
 exports.cloneFromUpstream = cloneFromUpstream;
 exports.parseVcsRemoteUrl = parseVcsRemoteUrl;
 exports.getVcsRemoteInfo = getVcsRemoteInfo;
@@ -9,12 +9,17 @@ exports.getGitRootRelativePath = getGitRootRelativePath;
 exports.isShallowRepository = isShallowRepository;
 exports.getFirstCommitSha = getFirstCommitSha;
 exports.isGitRepository = isGitRepository;
+exports.getGitRepositoryStatus = getGitRepositoryStatus;
 exports.getGitCurrentBranch = getGitCurrentBranch;
+exports.getGitRemoteNames = getGitRemoteNames;
+exports.getWorkingTreeStatus = getWorkingTreeStatus;
 exports.hasUncommittedChanges = hasUncommittedChanges;
+exports.getPathCommitExposure = getPathCommitExposure;
 exports.getUncommittedChangesSnapshot = getUncommittedChangesSnapshot;
 exports.commitChanges = commitChanges;
 exports.tryCommitChanges = tryCommitChanges;
 exports.getLatestCommitSha = getLatestCommitSha;
+exports.isAncestorCommit = isAncestorCommit;
 const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const crypto = tslib_1.__importStar(require("crypto"));
@@ -368,6 +373,29 @@ function isGitRepository(directory) {
         return false;
     }
 }
+/**
+ * Like `isGitRepository`, but separates "this is not a git repository" from
+ * "the probe itself failed" (git not installed, permissions). Callers gating
+ * destructive or unverifiable behavior on the answer must fail closed on
+ * 'unknown' instead of reading a broken probe as a missing repository.
+ */
+function getGitRepositoryStatus(directory) {
+    try {
+        (0, child_process_1.execSync)('git rev-parse --is-inside-work-tree', {
+            stdio: 'pipe',
+            cwd: directory,
+            windowsHide: true,
+            // Force untranslated messages; the classification matches on the
+            // English "not a git repository".
+            env: { ...process.env, LC_ALL: 'C' },
+        });
+        return 'git';
+    }
+    catch (err) {
+        const stderr = err?.stderr?.toString() ?? '';
+        return /not a git repository/i.test(stderr) ? 'not-git' : 'unknown';
+    }
+}
 // Checked-out branch name, or null when there isn't one to act on: a detached
 // HEAD reports the literal "HEAD" (treated as no branch), and any git error
 // (not a repo, no commits yet) also yields null.
@@ -385,21 +413,94 @@ function getGitCurrentBranch(directory) {
         return null;
     }
 }
+// Names of the remotes configured in the repository, empty when there are
+// none or the probe itself failed.
+function getGitRemoteNames(directory) {
+    try {
+        return (0, child_process_1.execSync)('git remote', {
+            encoding: 'utf8',
+            cwd: directory,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        })
+            .split('\n')
+            .map((name) => name.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+// Tri-state working-tree probe: 'unknown' means the probe itself failed (git
+// missing, spawn failure, permissions), not that the tree is clean. Callers
+// that gate destructive actions on tree cleanliness must treat 'unknown' as
+// unsafe rather than clean.
+// `excludePaths` are left out of the probe the way `tryCommitChanges` leaves
+// them out of the commit, so a tree dirty only under them reads as clean. An
+// exclude-only pathspec still covers the whole tree, matching `git add -A`.
+function getWorkingTreeStatus(directory, excludePaths = []) {
+    const pathspecs = excludePaths
+        .map((excludePath) => ` ":(exclude)${excludePath}"`)
+        .join('');
+    try {
+        const out = (0, child_process_1.execSync)(`git status --porcelain${pathspecs ? ` --${pathspecs}` : ''}`, {
+            encoding: 'utf8',
+            cwd: directory,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        return out.trim() === '' ? 'clean' : 'dirty';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 // Sync companion to `GitRepository.hasUncommittedChanges` for callers that
-// can't drop into the async class (e.g. the migrate orchestrator, which
-// branches on this before spawning subprocesses synchronously).
-function hasUncommittedChanges(directory) {
+// can't drop into the async class. A failed probe reads as false; callers for
+// whom that tolerance is unsafe use `getWorkingTreeStatus` instead.
+function hasUncommittedChanges(directory, excludePaths = []) {
+    return getWorkingTreeStatus(directory, excludePaths) === 'dirty';
+}
+// Classifies whether `git add -A` commits made in `directory` can sweep in
+// the directory at `dirPath`. Tracked files stay committable no matter what
+// the ignore rules say (ignore rules never apply to tracked files), so
+// `git ls-files` decides 'tracked' first; `git check-ignore` then splits the
+// untracked remainder into 'ignored' (covered) vs 'unignored' (no
+// coverage). 'unknown' means the probe itself failed (not a git repository,
+// git missing); callers gating destructive behavior on the result must
+// treat it as unsafe.
+function getPathCommitExposure(dirPath, directory) {
     try {
-        const out = (0, child_process_1.execSync)('git status --porcelain', {
+        const tracked = (0, child_process_1.execSync)(`git ls-files -- ${dirPath}`, {
             encoding: 'utf8',
             cwd: directory,
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
         });
-        return out.trim() !== '';
+        if (tracked.trim() !== '') {
+            return 'tracked';
+        }
     }
     catch {
-        return false;
+        return 'unknown';
+    }
+    // Query with a trailing slash so git treats the path as a directory even
+    // when it does not exist on disk yet: a directory-only ignore rule (a
+    // trailing-slash .gitignore entry) does not match a bare query for an
+    // absent path, which would misreport covered workspaces as unignored.
+    const asDir = dirPath.endsWith('/') ? dirPath : `${dirPath}/`;
+    try {
+        (0, child_process_1.execSync)(`git check-ignore -q -- ${asDir}`, {
+            cwd: directory,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        return 'ignored';
+    }
+    catch (e) {
+        // check-ignore exits 1 for "not ignored"; anything else is a probe
+        // failure.
+        return e?.status === 1 ? 'unignored' : 'unknown';
     }
 }
 // Returns a content-sensitive sha1 snapshot of the working tree state for
@@ -503,8 +604,13 @@ function commitChanges(commitMessage, directory) {
  * Returns `null` (rather than throwing) when the commit itself succeeded
  * but `git rev-parse HEAD` failed transiently — by contract the diff is
  * no longer in the working tree, so callers must NOT report it as such.
+ *
+ * `excludePaths` are `directory`-relative paths the commit must not capture,
+ * whatever the ignore rules say. Their working-tree files are left intact;
+ * only their index entries are put back to HEAD's state. Paths come from
+ * callers' own constants, never from user input.
  */
-function tryCommitChanges(commitMessage, directory) {
+function tryCommitChanges(commitMessage, directory, excludePaths = []) {
     try {
         (0, child_process_1.execSync)('git add -A', {
             encoding: 'utf8',
@@ -512,6 +618,20 @@ function tryCommitChanges(commitMessage, directory) {
             cwd: directory,
             windowsHide: true,
         });
+        // Exclusion happens as an unstage rather than an add-time pathspec:
+        // `git add` refuses a pathspec naming an ignored directory (exit 1) even
+        // as an exclusion, and an add-time pathspec cannot cover entries that
+        // were already staged before this call. The reset is relative to cwd, so
+        // a workspace nested inside a larger repo excludes its own path; a path
+        // with no index entry is a quiet no-op, unborn HEAD included.
+        for (const excludePath of excludePaths) {
+            (0, child_process_1.execSync)(`git reset -q -- "${excludePath}"`, {
+                encoding: 'utf8',
+                stdio: 'pipe',
+                cwd: directory,
+                windowsHide: true,
+            });
+        }
         (0, child_process_1.execSync)('git commit --no-verify -F -', {
             encoding: 'utf8',
             stdio: 'pipe',
@@ -546,3 +666,31 @@ function getLatestCommitSha(directory) {
         return null;
     }
 }
+/**
+ * The shape of a recorded `git rev-parse` output: 40 hex chars, or 64 in a
+ * sha256 repository. Anything a caller persists and later interpolates into a
+ * command line has to be checked against this first.
+ */
+exports.GIT_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+/**
+ * Whether `ancestor` is reachable from `descendant`, i.e. resetting to
+ * `descendant` keeps `ancestor` in history. Returns false when the answer
+ * cannot be established (invalid input, not a repository, unknown commits),
+ * so callers treat an unverifiable commit as not preserved.
+ */
+function isAncestorCommit(ancestor, descendant, directory) {
+    if (!exports.GIT_SHA.test(ancestor) || !exports.GIT_SHA.test(descendant)) {
+        return false;
+    }
+    try {
+        (0, child_process_1.execSync)(`git merge-base --is-ancestor ${ancestor} ${descendant}`, {
+            stdio: 'pipe',
+            windowsHide: true,
+            cwd: directory,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}