nx 23.2.0-beta.0 → 23.2.0-beta.10

package/dist/src/utils/formatters/prettier.d.ts

@@ -0,0 +1,26 @@
+import type { Tree } from '../../generators/tree';
+/**
+ * Config filenames prettier discovers. Exported because generator setup must
+ * agree with detection - a format missing from one side gets a second,
+ * redundant config written next to it.
+ * https://prettier.io/docs/configuration
+ */
+export declare const prettierConfigFiles: string[];
+export declare function isUsingPrettier(root: string): boolean;
+export declare function isUsingPrettierInTree(tree: Tree): boolean;
+/**
+ * Keeps only the files prettier can format. oxfmt needs no equivalent - it
+ * silently skips file types it does not handle.
+ */
+export declare function filterToPrettierSupportedFiles(files: string[]): Promise<string[]>;
+export declare function writeWithPrettier(patterns: string[], cwd?: string): void;
+export declare function checkWithPrettier(patterns: string[]): Promise<string[]>;
+export declare function getPrettierPath(): string;
+/**
+ * Quote a pattern for prettier's shell-based exec calls; oxfmt uses execFile
+ * and takes raw paths.
+ *
+ * Exported so `nx format` can size its chunks against the quoted length -
+ * patterns are chunked before they get here, and quoting grows each one.
+ */
+export declare function quoteForShell(pattern: string): string;

package/dist/src/utils/formatters/prettier.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prettierConfigFiles = void 0;
+exports.isUsingPrettier = isUsingPrettier;
+exports.isUsingPrettierInTree = isUsingPrettierInTree;
+exports.filterToPrettierSupportedFiles = filterToPrettierSupportedFiles;
+exports.writeWithPrettier = writeWithPrettier;
+exports.checkWithPrettier = checkWithPrettier;
+exports.getPrettierPath = getPrettierPath;
+exports.quoteForShell = quoteForShell;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const semver_1 = require("semver");
+const json_1 = require("../../generators/utils/json");
+const fileutils_1 = require("../fileutils");
+const handle_import_1 = require("../handle-import");
+const package_json_1 = require("../package-json");
+const shared_1 = require("./shared");
+/**
+ * Config filenames prettier discovers. Exported because generator setup must
+ * agree with detection - a format missing from one side gets a second,
+ * redundant config written next to it.
+ * https://prettier.io/docs/configuration
+ */
+exports.prettierConfigFiles = [
+    '.prettierrc',
+    '.prettierrc.json',
+    '.prettierrc.yml',
+    '.prettierrc.yaml',
+    '.prettierrc.json5',
+    '.prettierrc.js',
+    'prettier.config.js',
+    '.prettierrc.ts',
+    'prettier.config.ts',
+    '.prettierrc.mjs',
+    'prettier.config.mjs',
+    '.prettierrc.mts',
+    'prettier.config.mts',
+    '.prettierrc.cjs',
+    'prettier.config.cjs',
+    '.prettierrc.cts',
+    'prettier.config.cts',
+    '.prettierrc.toml',
+];
+function isUsingPrettier(root) {
+    for (const file of exports.prettierConfigFiles) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, file))) {
+            return true;
+        }
+    }
+    // Even if no file is present, it is possible the user is configuring prettier via their package.json
+    const packageJsonPath = (0, node_path_1.join)(root, 'package.json');
+    if ((0, node_fs_1.existsSync)(packageJsonPath)) {
+        const packageJson = (0, fileutils_1.readJsonFile)(packageJsonPath);
+        if (packageJson.prettier) {
+            return true;
+        }
+    }
+    return false;
+}
+function isUsingPrettierInTree(tree) {
+    for (const file of exports.prettierConfigFiles) {
+        if (tree.exists(file)) {
+            return true;
+        }
+    }
+    // Even if no file is present, it is possible the user is configuring prettier via their package.json
+    if (tree.exists('package.json')) {
+        const packageJson = (0, json_1.readJson)(tree, 'package.json');
+        if (packageJson.prettier) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Keeps only the files prettier can format. oxfmt needs no equivalent - it
+ * silently skips file types it does not handle.
+ */
+async function filterToPrettierSupportedFiles(files) {
+    const prettier = await (0, handle_import_1.handleImport)('prettier');
+    const supportInfo = await prettier.getSupportInfo();
+    const supportedExtensions = new Set(supportInfo.languages
+        .flatMap((language) => language.extensions)
+        .filter((extension) => !!extension));
+    // Prettier matches ~30 files by *name* rather than extension (`.swcrc`,
+    // `Jakefile`). It publishes that list next to the extensions, so read it
+    // rather than hardcoding.
+    const supportedFilenames = new Set(supportInfo.languages.flatMap((language) => language.filenames ?? []));
+    return files.filter((file) => supportedExtensions.has((0, node_path_1.extname)(file)) ||
+        supportedFilenames.has((0, node_path_1.basename)(file)));
+}
+function writeWithPrettier(patterns, 
+// Defaults to the caller's cwd. `nx init` sets it so it can pass paths
+// relative to the repo root rather than absolute ones the user has to read.
+cwd) {
+    if (patterns.length === 0) {
+        // Prettier with no file arguments reads stdin, and `stdio: [0, 1, 2]` hands
+        // it nx's own - from a terminal it blocks forever with nothing on screen. At
+        // EOF it exits 0 under `--list-different` and 2 (which `execSync` throws on)
+        // without it, so which failure you get depends on `shouldUseListDifferent`.
+        return;
+    }
+    const prettierPath = getPrettierPath();
+    const listDifferentArg = shouldUseListDifferent() ? '--list-different ' : '';
+    // No `--parser json` special case for `.swcrc`: prettier's own language table
+    // maps it to the json parser, so it formats correctly on its own (measured).
+    // Splitting the batch also meant one of the two spawns could receive zero
+    // files, which is the error above.
+    (0, node_child_process_1.execSync)(`node ${quoteForShell(prettierPath)} --write ${listDifferentArg}-- ${patterns
+        .map(quoteForShell)
+        .join(' ')}`, {
+        cwd,
+        stdio: [0, 1, 2],
+        windowsHide: true,
+    });
+}
+function checkWithPrettier(patterns) {
+    const prettierPath = getPrettierPath();
+    return new Promise((resolve, reject) => {
+        (0, node_child_process_1.exec)(`node ${quoteForShell(prettierPath)} --list-different -- ${patterns
+            .map(quoteForShell)
+            .join(' ')}`, { encoding: 'utf-8', windowsHide: true, maxBuffer: shared_1.FORMATTER_MAX_BUFFER }, (error, stdout) => {
+            if (error) {
+                // As the oxfmt sibling: a spawn failure, kill or maxBuffer overrun reports a
+                // string `code` or none. Prettier signals "files differ" numerically, so
+                // treating these as a file list would pass `format:check` on a formatter
+                // that never ran.
+                if (typeof error['code'] !== 'number') {
+                    reject(new Error(`prettier could not be run to completion (${error['code'] ?? error.signal ?? 'unknown'}): ${error.message}`));
+                    return;
+                }
+                // Only `Mismatch` means "files differ", as in `checkWithOxfmt`. `Failure`
+                // still prints the files prettier got through - measured, one differing plus
+                // one unparseable exits 2 with the differing file on stdout - so reading
+                // stdout there would swallow the syntax error.
+                if (error['code'] !== 1 /* PrettierExitCode.Mismatch */ ||
+                    stdout.length === 0) {
+                    reject(error);
+                    return;
+                }
+                resolve(stdout.trim().split('\n'));
+            }
+            else {
+                resolve([]);
+            }
+        });
+    });
+}
+let prettierPath;
+function getPrettierPath() {
+    if (prettierPath) {
+        return prettierPath;
+    }
+    const { packageJson, path: packageJsonPath } = (0, package_json_1.readModulePackageJson)('prettier');
+    const bin = packageJson.bin;
+    const binPath = typeof bin === 'string' ? bin : bin?.['prettier'];
+    if (!binPath) {
+        throw new Error(`Could not find prettier binary in ${packageJsonPath}`);
+    }
+    prettierPath = (0, node_path_1.resolve)((0, node_path_1.dirname)(packageJsonPath), binPath);
+    return prettierPath;
+}
+let useListDifferent;
+/**
+ * Determines if --list-different should be used with --write.
+ * Prettier 4+ and 3.6.x with experimental CLI don't support combining these flags.
+ */
+function shouldUseListDifferent() {
+    if (useListDifferent !== undefined) {
+        return useListDifferent;
+    }
+    try {
+        const { packageJson } = (0, package_json_1.readModulePackageJson)('prettier');
+        const prettierMajor = (0, semver_1.major)(packageJson.version);
+        const isExperimentalCli = process.env.PRETTIER_EXPERIMENTAL_CLI === '1';
+        useListDifferent = prettierMajor < 4 && !isExperimentalCli;
+    }
+    catch {
+        useListDifferent = false;
+    }
+    return useListDifferent;
+}
+/**
+ * Quote a pattern for prettier's shell-based exec calls; oxfmt uses execFile
+ * and takes raw paths.
+ *
+ * Exported so `nx format` can size its chunks against the quoted length -
+ * patterns are chunked before they get here, and quoting grows each one.
+ */
+function quoteForShell(pattern) {
+    // Interpolated into a command string, so every character special *inside
+    // double quotes* needs escaping, not just `$`: a backtick substitutes, `"`
+    // closes the quoting, `\` escapes what follows. One pass over the original,
+    // since `String.replace` never re-scans what it inserted.
+    const escaped = process.platform !== 'win32'
+        ? pattern.replace(/([\\"`$])/g, '\\$1')
+        : pattern;
+    return `"${escaped}"`;
+}

package/dist/src/utils/formatters/shared.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Formatters list every mismatching path on stdout, which overruns Node's 1MB
+ * default on a large workspace.
+ */
+export declare const FORMATTER_MAX_BUFFER: number;

package/dist/src/utils/formatters/shared.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORMATTER_MAX_BUFFER = void 0;
+/**
+ * Formatters list every mismatching path on stdout, which overruns Node's 1MB
+ * default on a large workspace.
+ */
+exports.FORMATTER_MAX_BUFFER = 50 * 1024 * 1024;

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

@@ -0,0 +1,12 @@
+/**
+ * Git parses any argument beginning with `-` as an option rather than a
+ * revision, so a flag-shaped revision could smuggle options such as
+ * `--upload-pack` into the git commands Nx runs.
+ */
+export declare function assertValidGitRevision(revision: string): void;
+/**
+ * For refs Nx itself recorded from `git rev-parse` and later read back off
+ * disk, where anything other than a commit sha means the value was tampered
+ * with rather than that the user picked an unusual revision.
+ */
+export declare function assertValidGitSha(sha: string): void;

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidGitRevision = assertValidGitRevision;
+exports.assertValidGitSha = assertValidGitSha;
+/**
+ * Git parses any argument beginning with `-` as an option rather than a
+ * revision, so a flag-shaped revision could smuggle options such as
+ * `--upload-pack` into the git commands Nx runs.
+ */
+function assertValidGitRevision(revision) {
+    if (revision.startsWith('-')) {
+        throw new Error(`Invalid git revision: "${revision}". Git revisions cannot start with "-".`);
+    }
+}
+const COMMIT_SHA = /^[0-9a-f]{7,40}$/i;
+/**
+ * For refs Nx itself recorded from `git rev-parse` and later read back off
+ * disk, where anything other than a commit sha means the value was tampered
+ * with rather than that the user picked an unusual revision.
+ */
+function assertValidGitSha(sha) {
+    if (!COMMIT_SHA.test(sha)) {
+        throw new Error(`Invalid git commit sha: "${sha}". Expected a hexadecimal commit sha.`);
+    }
+}

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

@@ -36,9 +36,37 @@ export interface VcsRemoteInfo {
 }
 export declare function parseVcsRemoteUrl(url: string): VcsRemoteInfo | null;
 export declare function getVcsRemoteInfo(directory?: string): VcsRemoteInfo | null;
+export declare function getGitRootPath(cwd?: string): string;
+/**
+ * Path of `directory` relative to its git root, posix-separated so it is
+ * identical on every OS, and '' when the directory is the git root itself.
+ * Null outside a git repository.
+ */
+export declare function getGitRootRelativePath(directory: string): string | null;
+/** A shallow clone's truncated history has no stable root commit. */
+export declare function isShallowRepository(directory?: string): boolean;
+/**
+ * SHA of the repository's first commit. Merged unrelated histories leave
+ * several root commits — the sorted-first one is picked so every clone
+ * agrees. Null when there are no commits, or outside a git repository.
+ */
+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;
 /**
@@ -51,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,16 +1,25 @@
 "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;
+exports.getGitRootPath = getGitRootPath;
+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"));
@@ -49,12 +58,7 @@ class GitRepository {
         this.root = this.getGitRootPath(this.directory);
     }
     getGitRootPath(cwd) {
-        return (0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], {
-            cwd,
-            windowsHide: true,
-        })
-            .toString()
-            .trim();
+        return getGitRootPath(cwd);
     }
     async hasUncommittedChanges() {
         const data = await this.execGit(['status', '--porcelain']);
@@ -297,6 +301,65 @@ function getVcsRemoteInfo(directory) {
         return null;
     }
 }
+function getGitRootPath(cwd) {
+    return (0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], {
+        cwd,
+        windowsHide: true,
+    })
+        .toString()
+        .trim();
+}
+/**
+ * Path of `directory` relative to its git root, posix-separated so it is
+ * identical on every OS, and '' when the directory is the git root itself.
+ * Null outside a git repository.
+ */
+function getGitRootRelativePath(directory) {
+    try {
+        return (0, path_1.relative)(getGitRootPath(directory), directory)
+            .split(path_1.sep)
+            .join(path_1.posix.sep);
+    }
+    catch {
+        return null;
+    }
+}
+/** A shallow clone's truncated history has no stable root commit. */
+function isShallowRepository(directory) {
+    try {
+        return ((0, child_process_1.execFileSync)('git', ['rev-parse', '--is-shallow-repository'], {
+            encoding: 'utf8',
+            stdio: 'pipe',
+            cwd: directory,
+            windowsHide: true,
+        }).trim() === 'true');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * SHA of the repository's first commit. Merged unrelated histories leave
+ * several root commits — the sorted-first one is picked so every clone
+ * agrees. Null when there are no commits, or outside a git repository.
+ */
+function getFirstCommitSha(directory) {
+    try {
+        const roots = (0, child_process_1.execFileSync)('git', ['rev-list', '--max-parents=0', 'HEAD'], {
+            encoding: 'utf8',
+            stdio: 'pipe',
+            cwd: directory,
+            windowsHide: true,
+        })
+            .trim()
+            .split(/\r?\n/)
+            .filter(Boolean);
+        return roots.sort()[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 function isGitRepository(directory) {
     try {
         (0, child_process_1.execSync)('git rev-parse --is-inside-work-tree', {
@@ -310,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.
@@ -327,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
@@ -445,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',
@@ -454,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',
@@ -488,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;
+    }
+}