@vltpkg/cli-sdk 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/pack-tarball.js

@@ -0,0 +1,256 @@
+import { create as tarCreate, list as tarList } from 'tar';
+import { minimatch } from 'minimatch';
+import { error } from '@vltpkg/error-cause';
+import * as ssri from 'ssri';
+import assert from 'node:assert';
+import { existsSync, statSync } from 'node:fs';
+import { Spec } from '@vltpkg/spec';
+import { join } from 'node:path';
+import { parse, stringify } from 'polite-json';
+/**
+ * Replace workspace: and catalog: specs with actual versions
+ * @param {NormalizedManifest} manifest_ - The manifest to process
+ * @param {LoadedConfig} config - The loaded configuration containing project root, monorepo, and catalog data
+ * @returns {NormalizedManifest} The manifest with replaced specs
+ */
+const replaceWorkspaceAndCatalogSpecs = (manifest_, config) => {
+    // Create a json copy of the manifest to avoid modifying the original
+    // preserves original formatting symbols from polite-json
+    const manifest = parse(stringify(manifest_));
+    // Get workspace and catalog configuration from config
+    const { monorepo, catalog = {}, catalogs = {} } = config.options;
+    // Process dependency types
+    const depTypes = [
+        'dependencies',
+        'devDependencies',
+        'optionalDependencies',
+        'peerDependencies',
+    ];
+    for (const depType of depTypes) {
+        const deps = manifest[depType];
+        /* c8 ignore next */
+        if (!deps || typeof deps !== 'object')
+            continue;
+        const depsObj = deps;
+        for (const [depName, depSpec] of Object.entries(depsObj)) {
+            /* c8 ignore next */
+            if (typeof depSpec !== 'string')
+                continue;
+            const spec = Spec.parse(`${depName}@${depSpec}`, {
+                catalog,
+                catalogs,
+            });
+            switch (spec.type) {
+                case 'workspace': {
+                    assert(monorepo, error(`No workspace configuration found for ${depName}`, {
+                        found: depName,
+                    }));
+                    const workspaceName = spec.workspace;
+                    assert(workspaceName, error(`No workspace name found for ${depName}`, {
+                        found: depName,
+                    }));
+                    const workspace = monorepo.get(workspaceName);
+                    assert(workspace, error(`Workspace '${workspaceName}' not found`, {
+                        found: workspaceName,
+                        validOptions: Array.from(monorepo.keys()),
+                    }));
+                    const actualVersion = workspace.manifest.version;
+                    assert(actualVersion, error(`No version found for workspace '${workspaceName}'`, {
+                        found: workspaceName,
+                        wanted: 'package version',
+                    }));
+                    depsObj[depName] = actualVersion;
+                    break;
+                }
+                case 'catalog': {
+                    const catalogName = spec.catalog || '';
+                    const targetCatalog = catalogName ? catalogs[catalogName] : catalog;
+                    assert(targetCatalog, error(`Catalog '${catalogName}' not found`, {
+                        found: catalogName,
+                        validOptions: Object.keys(catalogs),
+                    }));
+                    const actualVersion = targetCatalog[depName];
+                    assert(actualVersion, error(`Package '${depName}' not found in catalog '${catalogName || 'default'}'`, {
+                        found: depName,
+                        validOptions: Object.keys(targetCatalog),
+                    }));
+                    depsObj[depName] = actualVersion;
+                    break;
+                }
+            }
+        }
+    }
+    return manifest;
+};
+/**
+ * Create a tarball from a package directory
+ * @param {NormalizedManifest} manifest - The manifest of the package to pack
+ * @param {string} dir - The directory containing the package to pack
+ * @param {LoadedConfig} [config] - The loaded configuration (for workspace/catalog resolution)
+ * @returns {Promise<PackTarballResult>} The manifest, filename, and tarball data (unless dry run)
+ */
+export const packTarball = async (manifest, dir, config) => {
+    let packDir = dir;
+    // Check if publishDirectory is configured via CLI flag or package.json publishConfig.directory
+    const cliPublishDir = config.get('publish-directory');
+    const manifestPublishDir = manifest.publishConfig?.directory;
+    const publishDirectory = cliPublishDir ?? manifestPublishDir;
+    if (publishDirectory) {
+        // CLI flag paths are used as-is; publishConfig.directory is relative to the package dir
+        const resolvedPublishDir = cliPublishDir ? publishDirectory : join(dir, publishDirectory);
+        // Validate that the publish directory exists and is a directory
+        assert(existsSync(resolvedPublishDir), error(`Publish directory does not exist: ${resolvedPublishDir}`, {
+            found: resolvedPublishDir,
+        }));
+        assert(statSync(resolvedPublishDir).isDirectory(), error(`Publish directory is not a directory: ${resolvedPublishDir}`, {
+            found: resolvedPublishDir,
+            wanted: 'directory',
+        }));
+        if (existsSync(join(resolvedPublishDir, 'package.json'))) {
+            manifest = config.options.packageJson.read(resolvedPublishDir);
+        }
+        packDir = resolvedPublishDir;
+    }
+    assert(manifest.name && manifest.version, error('Package must have a name and version'));
+    const processedManifest = replaceWorkspaceAndCatalogSpecs(manifest, config);
+    const filename = `${manifest.name.replace('@', '').replace('/', '-')}-${manifest.version}.tgz`;
+    const tarballName = `${manifest.name}-${manifest.version}.tgz`;
+    try {
+        config.options.packageJson.write(packDir, processedManifest);
+        const tarballData = await tarCreate({
+            cwd: packDir,
+            gzip: true,
+            portable: true,
+            prefix: 'package/',
+            filter: (path) => {
+                // Normalize path - remove leading './'
+                const normalizedPath = path.replace(/^\.\//, '');
+                // Always include root directory
+                if (path === '.' || normalizedPath === '') {
+                    return true;
+                }
+                // Always exclude certain files/directories
+                const alwaysExcludePatterns = [
+                    /^\.?\/?\.git(\/|$)/,
+                    /^\.?\/?node_modules(\/|$)/,
+                    /^\.?\/?\.nyc_output(\/|$)/,
+                    /^\.?\/?coverage(\/|$)/,
+                    /^\.?\/?\.DS_Store$/,
+                    /^\.?\/?\.npmrc$/,
+                    /^\.?\/?package-lock\.json$/,
+                    /^\.?\/?yarn\.lock$/,
+                    /^\.?\/?pnpm-lock\.yaml$/,
+                    /^\.?\/?bun\.lockb$/,
+                    /^\.?\/?bun\.lock$/,
+                    /^\.?\/?vlt-lock\.json$/,
+                    /~$/,
+                    /\.swp$/,
+                    /\.tgz$/,
+                ];
+                if (alwaysExcludePatterns.some(pattern => pattern.test(normalizedPath))) {
+                    return false;
+                }
+                // Always include certain files
+                const alwaysIncludePatterns = [
+                    /^README(\..*)?$/i,
+                    /^CHANGELOG(\..*)?$/i,
+                    /^HISTORY(\..*)?$/i,
+                    /^LICENSE(\..*)?$/i,
+                    /^LICENCE(\..*)?$/i,
+                ];
+                if (alwaysIncludePatterns.some(pattern => pattern.test(normalizedPath))) {
+                    return true;
+                }
+                // Always include package.json
+                if (normalizedPath === 'package.json') {
+                    return true;
+                }
+                // If files field is specified in package.json, use it for inclusion
+                const manifestWithFiles = manifest;
+                if (manifestWithFiles.files &&
+                    Array.isArray(manifestWithFiles.files)) {
+                    // Empty files array means exclude everything except always-included files
+                    if (manifestWithFiles.files.length === 0) {
+                        return false;
+                    }
+                    return manifestWithFiles.files.some((pattern) => {
+                        if (pattern.endsWith('/')) {
+                            const dirName = pattern.slice(0, -1);
+                            const globPattern = pattern.replace(/\/$/, '/**');
+                            const matchesDir = normalizedPath === dirName;
+                            const matchesContents = minimatch(normalizedPath, globPattern, {
+                                dot: true,
+                            });
+                            return matchesDir || matchesContents;
+                        }
+                        const directMatch = minimatch(normalizedPath, pattern, {
+                            dot: true,
+                        });
+                        // Check if this path is a parent directory of the pattern
+                        const isParentDir = pattern.includes('/') &&
+                            pattern.startsWith(normalizedPath + '/');
+                        // Check if this path is inside a directory matched by the pattern
+                        // (e.g. files: ["dist"] should include dist/index.js)
+                        const isChildOfPattern = minimatch(normalizedPath, pattern + '/**', { dot: true });
+                        return directMatch || isParentDir || isChildOfPattern;
+                    });
+                }
+                // Default behavior when no files field - exclude common development files
+                const defaultExcludePatterns = [
+                    /^\.?\/?\.vscode(\/|$)/,
+                    /^\.?\/?\.idea(\/|$)/,
+                    /^\.?\/?\.gitignore$/,
+                    /^\.?\/?\.npmignore$/,
+                    /^\.?\/?\.editorconfig$/,
+                ];
+                return !defaultExcludePatterns.some(pattern => pattern.test(normalizedPath));
+            },
+        }, ['.']).concat();
+        let unpackedSize = 0;
+        const files = [];
+        await new Promise((resolve, reject) => {
+            const stream = tarList({
+                onentry: entry => {
+                    if (entry.type === 'File') {
+                        unpackedSize += entry.size;
+                        // Remove the package/ prefix for cleaner file listing
+                        const cleanPath = entry.path.replace(/^[^/]+\//, '');
+                        if (cleanPath) {
+                            // Skip empty paths
+                            files.push(cleanPath);
+                        }
+                    }
+                },
+            });
+            stream
+                .on('end', () => resolve())
+                .on('error', reject)
+                .write(tarballData);
+            stream.end();
+        });
+        const integrityMap = ssri.fromData(tarballData, {
+            algorithms: [...new Set(['sha1', 'sha512'])],
+        });
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        const integrity = integrityMap.sha512?.[0]?.toString();
+        // @ts-expect-error -- types from DT are missing hexDigest
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        const shasum = integrityMap.sha1?.[0]?.hexDigest();
+        return {
+            name: manifest.name,
+            version: manifest.version,
+            filename,
+            tarballName,
+            tarballData,
+            unpackedSize,
+            files,
+            integrity,
+            shasum,
+            resolvedManifest: processedManifest,
+        };
+    }
+    finally {
+        // Restore the original package.json to the pack directory
+        config.options.packageJson.write(packDir, manifest);
+    }
+};

package/dist/parse-add-remove-args.d.ts

@@ -0,0 +1,28 @@
+import type { PathScurry } from 'path-scurry';
+import type { AddImportersDependenciesMap, RemoveImportersDependenciesMap } from '@vltpkg/graph';
+import type { Monorepo } from '@vltpkg/workspaces';
+import type { LoadedConfig } from './config/index.ts';
+export type ParsedAddArgs = {
+    add: AddImportersDependenciesMap;
+};
+export type ParsedRemoveArgs = {
+    remove: RemoveImportersDependenciesMap;
+};
+export type SaveTypes = {
+    'save-dev'?: boolean;
+    'save-optional'?: boolean;
+    'save-peer'?: boolean;
+    'save-prod'?: boolean;
+};
+export type WorkspaceTypes = {
+    workspace?: string[];
+    'workspace-group'?: string[];
+};
+/**
+ * Parses the positional arguments into {@link AddImportersDependenciesMap}.
+ */
+export declare const parseAddArgs: (config: LoadedConfig, scurry: PathScurry, monorepo?: Monorepo) => ParsedAddArgs;
+/**
+ * Parses the positional arguments into {@link RemoveImportersDependenciesMap}.
+ */
+export declare const parseRemoveArgs: (config: LoadedConfig, scurry: PathScurry, monorepo?: Monorepo) => ParsedRemoveArgs;

package/dist/parse-add-remove-args.js

@@ -0,0 +1,103 @@
+import { asDependency } from '@vltpkg/graph';
+import { joinDepIDTuple } from '@vltpkg/dep-id';
+import { Spec } from '@vltpkg/spec';
+const rootDepID = joinDepIDTuple(['file', '.']);
+/**
+ * Compute a DepID for the current working directory relative to the project
+ * root. Returns the root DepID if cwd is the project root, otherwise returns
+ * the computed DepID.
+ */
+const getCwdDepID = (scurry) => {
+    const cwd = process.cwd();
+    const relPath = scurry.relativePosix(cwd);
+    // If cwd is the project root or outside it, return root DepID
+    if (!relPath || relPath.startsWith('..')) {
+        return rootDepID;
+    }
+    // Return a DepID for the nested folder (posix-style path)
+    return joinDepIDTuple(['file', relPath.split('\\').join('/')]);
+};
+/**
+ * Get the list of importers that are currently selected
+ * in {@link WorkspaceTypes}.
+ */
+const getWorkspaceImporters = (opts, monorepo) => {
+    const res = new Set();
+    // collects DepID references to any selected workspace
+    if (monorepo) {
+        for (const ws of monorepo.filter(opts)) {
+            res.add(ws.id);
+        }
+    }
+    return res;
+};
+const getType = (opts) => opts['save-prod'] ? 'prod'
+    : opts['save-dev'] ? 'dev'
+        : opts['save-peer'] ?
+            opts['save-optional'] ?
+                'peerOptional'
+                : 'peer'
+            : opts['save-optional'] ? 'optional'
+                : 'implicit';
+class AddImportersDependenciesMapImpl extends Map {
+    modifiedDependencies = false;
+}
+class RemoveImportersDependenciesMapImpl extends Map {
+    modifiedDependencies = false;
+}
+/**
+ * Parses the positional arguments into {@link AddImportersDependenciesMap}.
+ */
+export const parseAddArgs = (config, scurry, monorepo) => {
+    const add = new AddImportersDependenciesMapImpl();
+    const items = config.positionals;
+    const type = getType(config.values);
+    const importers = getWorkspaceImporters(config.values, monorepo);
+    const newDependencies = new Map();
+    const specOptions = config.options;
+    // nameless spec definitions will need to use their full
+    // stringified spec result instead of their name in order
+    // to have an unique key name in the resulting Map
+    const getName = (s) => s.name === '(unknown)' ? s.spec : s.name;
+    // parses each positional argument into a Spec and
+    // adds it to the new dependencies Map
+    for (const item of items) {
+        const spec = Spec.parseArgs(item, specOptions);
+        newDependencies.set(getName(spec), asDependency({ spec, type }));
+        add.modifiedDependencies = true;
+    }
+    // assigns the new dependencies to each selected workspace importer
+    for (const importer of importers) {
+        add.set(importer, newDependencies);
+    }
+    // if no workspaces were selected, default to the cwd importer which
+    // can be either the root or a nested folder in case the user is installing
+    // from a subfolder that is also a file: type dependency
+    if (!importers.size) {
+        const cwdDepID = getCwdDepID(scurry);
+        add.set(cwdDepID, newDependencies);
+    }
+    return {
+        add,
+    };
+};
+/**
+ * Parses the positional arguments into {@link RemoveImportersDependenciesMap}.
+ */
+export const parseRemoveArgs = (config, scurry, monorepo) => {
+    const remove = new RemoveImportersDependenciesMapImpl();
+    const importers = getWorkspaceImporters(config.values, monorepo);
+    for (const importer of importers) {
+        remove.set(importer, new Set(config.positionals));
+        remove.modifiedDependencies = true;
+    }
+    // if no workspaces were selected, default to the cwd importer
+    if (!importers.size) {
+        const cwdDepID = getCwdDepID(scurry);
+        remove.set(cwdDepID, new Set(config.positionals));
+        remove.modifiedDependencies = true;
+    }
+    return {
+        remove,
+    };
+};

package/dist/print-err.d.ts

@@ -0,0 +1,13 @@
+import type { InspectOptions } from 'node:util';
+import type { CommandUsage } from './index.ts';
+export declare const formatOptions: {
+    readonly depth: number;
+    readonly maxArrayLength: number;
+    readonly maxStringLength: number;
+};
+export type ErrorFormatOptions = InspectOptions & {
+    maxLines?: number;
+};
+export type Formatter = (arg: unknown, options?: ErrorFormatOptions) => string;
+export declare const indent: (lines: string, num?: number) => string;
+export declare const printErr: (e: unknown, usage: CommandUsage, stderr: (...a: string[]) => void, baseOpts?: ErrorFormatOptions) => void;

package/dist/print-err.js

@@ -0,0 +1,193 @@
+import { splitDepID } from '@vltpkg/dep-id';
+import { parseError } from '@vltpkg/output/error';
+import { isErrorWithCause, isObject } from '@vltpkg/types';
+import { XDG } from '@vltpkg/xdg';
+import { isGraphRunError } from '@vltpkg/graph-run';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { formatWithOptions } from 'node:util';
+export const formatOptions = {
+    depth: Infinity,
+    maxArrayLength: Infinity,
+    maxStringLength: Infinity,
+};
+const isNonEmptyString = (v) => !!v && typeof v === 'string';
+const formatURL = (v, format) => v instanceof URL ? v.toString() : /* c8 ignore next */ format(v);
+const formatArray = (v, format, joiner = ', ') => Array.isArray(v) ? v.join(joiner) : /* c8 ignore next */ format(v);
+export const indent = (lines, num = 2) => lines
+    .split('\n')
+    .map(l => ' '.repeat(num) + l)
+    .join('\n');
+const writeErrorLog = (e, format) => {
+    try {
+        const dir = new XDG('vlt/error-logs').data();
+        const file = join(dir, `error-${process.pid}.log`);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(file, format(e, {
+            colors: false,
+            maxLines: Infinity,
+        }));
+        return file;
+    }
+    catch {
+        return null;
+    }
+};
+const readErrorLog = (file) => {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+export const printErr = (e, usage, stderr, baseOpts) => {
+    const format = (arg, opts) => {
+        const { maxLines = 200, ...rest } = {
+            ...formatOptions,
+            ...baseOpts,
+            ...opts,
+        };
+        const lines = formatWithOptions(rest, arg).split('\n');
+        const totalLines = lines.length;
+        if (totalLines > maxLines) {
+            lines.length = maxLines;
+            lines.push(`... ${totalLines - maxLines} lines hidden ...`);
+        }
+        return lines.join('\n');
+    };
+    const err = parseError(e);
+    const knownError = printCode(err, usage, stderr, format);
+    const fileWritten = !knownError || knownError.file ? writeErrorLog(e, format) : null;
+    // We could not write an error log and its not a know error,
+    // so we print the entire formatted value.
+    if (!fileWritten && !knownError) {
+        return stderr(format(e));
+    }
+    if (err && !knownError) {
+        stderr(`${err.name}: ${err.message}`);
+    }
+    if (fileWritten) {
+        stderr('');
+        stderr(`Full details written to: ${fileWritten}`);
+        if (process.env.CI) {
+            const fullErrorLog = readErrorLog(fileWritten);
+            if (fullErrorLog) {
+                stderr('');
+                stderr('Full details:');
+                stderr(fullErrorLog);
+            }
+        }
+    }
+    if (!knownError || knownError.bug) {
+        stderr('');
+        stderr('Open an issue with the full error details at:');
+        stderr(indent('https://github.com/vltpkg/vltpkg/issues/new'));
+    }
+};
+const printCode = (err, usage, stderr, format) => {
+    if (!err)
+        return;
+    switch (err.cause?.code) {
+        case 'GRAPHRUN_TRAVERSAL': {
+            if (!isGraphRunError(err))
+                break;
+            const { node, path, cause } = err.cause;
+            stderr(`Graph traversal failure at: ${splitDepID(node.id).join(' ')}`);
+            if (Array.isArray(path) && path.length) {
+                stderr(indent(`Path: ${path.map(n => n.id).join(',')}`));
+            }
+            if (isErrorWithCause(cause) &&
+                isObject(cause.cause) &&
+                'command' in cause.cause &&
+                'stdout' in cause.cause &&
+                'stderr' in cause.cause &&
+                'status' in cause.cause &&
+                'signal' in cause.cause &&
+                'cwd' in cause.cause) {
+                const { command, args, cwd, stdout: cmdStdout, stderr: cmdStderr, status, signal, } = cause.cause;
+                stderr(`Command: ${command}`);
+                if (args && Array.isArray(args) && args.length) {
+                    stderr(`Args: ${args.map(a => JSON.stringify(a)).join(', ')}`);
+                }
+                stderr(`Cwd: ${cwd}`);
+                if (cmdStderr || cmdStdout) {
+                    stderr('');
+                    if (isNonEmptyString(cmdStderr)) {
+                        stderr(cmdStderr);
+                    }
+                    if (isNonEmptyString(cmdStdout)) {
+                        stderr(cmdStdout);
+                    }
+                    stderr('');
+                }
+                if (signal !== null)
+                    stderr(`Signal: ${format(signal)}`);
+                if (status !== null)
+                    stderr(`Status: ${format(status)}`);
+            }
+            return { file: true };
+        }
+        case 'EUSAGE': {
+            const { found, validOptions } = err.cause;
+            stderr(usage().usage());
+            stderr(`Usage Error: ${err.message}`);
+            if (found) {
+                stderr(indent(`Found: ${format(found)}`));
+            }
+            if (validOptions) {
+                stderr(indent(`Valid options: ${formatArray(validOptions, format)}`));
+            }
+            return {};
+        }
+        case 'ERESOLVE': {
+            const { url, from, response, spec } = err.cause;
+            stderr(`Resolve Error: ${err.message}`);
+            if (url) {
+                stderr(indent(`While fetching: ${formatURL(url, format)}`));
+            }
+            if (spec) {
+                stderr(indent(`To satisfy: ${format(spec)}`));
+            }
+            if (from) {
+                stderr(indent(`From: ${format(from)}`));
+            }
+            if (response) {
+                stderr(indent(`Response: ${format(response)}`));
+            }
+            return { file: true };
+        }
+        case 'EREQUEST': {
+            const { url, method } = err.cause;
+            const { code, syscall } = err.cause.cause ?? {};
+            stderr(`Request Error: ${err.message}`);
+            if (code) {
+                stderr(indent(`Code: ${format(code)}`));
+            }
+            if (syscall) {
+                stderr(indent(`Syscall: ${format(syscall)}`));
+            }
+            if (url) {
+                stderr(indent(`URL: ${formatURL(url, format)}`));
+            }
+            if (method) {
+                stderr(indent(`Method: ${format(method)}`));
+            }
+            return { file: true };
+        }
+        case 'ECONFIG': {
+            const { found, wanted, validOptions } = err.cause;
+            stderr(`Config Error: ${err.message}`);
+            if (found) {
+                stderr(indent(`Found: ${format(found)}`));
+            }
+            if (wanted) {
+                stderr(indent(`Wanted: ${format(wanted)}`));
+            }
+            if (validOptions) {
+                stderr(indent(`Valid Options: ${format(validOptions)}`));
+            }
+            return {};
+        }
+    }
+};

package/dist/query-diff-files.d.ts

@@ -0,0 +1,17 @@
+import type { DiffFilesProvider } from '@vltpkg/query';
+/**
+ * Validates that a commitish string is safe to use
+ * in a git command.
+ */
+export declare const validateCommitish: (commitish: string) => string;
+/**
+ * Creates a {@link DiffFilesProvider} that uses
+ * `git diff --name-only` to determine changed files.
+ * @param {string} projectRoot - The absolute path to the
+ *   project root directory where git commands will be
+ *   executed.
+ * @returns {DiffFilesProvider} A function that takes a
+ *   commitish and returns a Set of changed file paths
+ *   relative to the project root.
+ */
+export declare const createDiffFilesProvider: (projectRoot: string) => DiffFilesProvider;

package/dist/query-diff-files.js

@@ -0,0 +1,63 @@
+import { execSync } from 'node:child_process';
+import { error } from '@vltpkg/error-cause';
+/**
+ * Pattern to validate commitish arguments.
+ * Allows branch names, tags, SHAs, HEAD~N, HEAD^N, etc.
+ * Rejects shell metacharacters to prevent command injection.
+ */
+const VALID_COMMITISH = /^[a-zA-Z0-9_./@^~:#{}-]+$/;
+/**
+ * Validates that a commitish string is safe to use
+ * in a git command.
+ */
+export const validateCommitish = (commitish) => {
+    if (!commitish) {
+        throw error('Missing commitish argument for :diff() selector');
+    }
+    if (!VALID_COMMITISH.test(commitish)) {
+        throw error('Invalid commitish argument for :diff() selector', {
+            found: commitish,
+        });
+    }
+    return commitish;
+};
+/**
+ * Creates a {@link DiffFilesProvider} that uses
+ * `git diff --name-only` to determine changed files.
+ * @param {string} projectRoot - The absolute path to the
+ *   project root directory where git commands will be
+ *   executed.
+ * @returns {DiffFilesProvider} A function that takes a
+ *   commitish and returns a Set of changed file paths
+ *   relative to the project root.
+ */
+export const createDiffFilesProvider = (projectRoot) => {
+    // Cache results per commitish to avoid repeated git calls
+    const cache = new Map();
+    return (commitish) => {
+        const cached = cache.get(commitish);
+        if (cached)
+            return cached;
+        const safeCommitish = validateCommitish(commitish);
+        try {
+            const stdout = execSync(`git diff --name-only ${safeCommitish}`, {
+                cwd: projectRoot,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 30_000,
+            });
+            const files = new Set();
+            for (const line of stdout.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed) {
+                    files.add(trimmed);
+                }
+            }
+            cache.set(commitish, files);
+            return files;
+        }
+        catch (err) {
+            throw error(`Failed to run git diff for commitish: ${safeCommitish}`, { cause: err });
+        }
+    };
+};