@lumenflow/core 1.0.0

package/dist/git-staged-validator.js

@@ -0,0 +1,48 @@
+import { getGitForCwd } from './git-adapter.js';
+import { die } from './error-handler.js';
+/**
+ * Git Staged Files Validator
+ *
+ * Centralized validation for staged files requirement.
+ * Extracted from duplicate implementations in wu-block and wu-unblock (WU-1341).
+ *
+ * Used in --no-auto mode to enforce that required files are staged before commit.
+ *
+ * @module git-staged-validator
+ */
+/**
+ * Ensure all required paths are staged in git index
+ *
+ * Validates that specified files/directories are staged for commit.
+ * Supports exact path matching and directory prefix matching.
+ *
+ * @param {Array<string|null|undefined>} paths - Paths to check (null/undefined values filtered out)
+ * @throws {Error} If any required paths are not staged
+ * @returns {Array<string>} List of all staged files
+ *
+ * @example
+ * // All files staged - success
+ * ensureStaged(['docs/file.md', 'tools/script.js']);
+ *
+ * // Directory prefix - matches all files under directory
+ * ensureStaged(['docs/04-operations/']);
+ *
+ * // Missing files - throws error
+ * ensureStaged(['docs/file1.md', 'docs/file2.md']);
+ * // Error: Stage updates for: docs/file2.md
+ */
+export function ensureStaged(paths) {
+    const git = getGitForCwd();
+    const raw = git.run('git diff --cached --name-only');
+    const staged = raw ? raw.split(/\r?\n/).filter((s) => Boolean(s)) : [];
+    // Filter out null/undefined and check each path
+    const missing = paths.filter(Boolean).filter((p) => {
+        // Normalize path: remove trailing slash for directory checks
+        const pathToCheck = p.endsWith('/') ? p.slice(0, -1) : p;
+        return !staged.some((name) => name === pathToCheck || name.startsWith(`${pathToCheck}/`));
+    });
+    if (missing.length) {
+        die(`Stage updates for: ${missing.join(', ')}`);
+    }
+    return staged;
+}

package/dist/hardcoded-strings.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Hardcoded String Detection Module
+ *
+ * Provides classification of hardcoded path strings to distinguish between:
+ * - Route paths (API endpoints, webhooks, etc.) - should use endpoint constants
+ * - Filesystem paths (absolute paths, config files) - should use path.join()
+ *
+ * This enables Gate 13 to provide accurate, actionable remediation messages.
+ *
+ * @see WU-1788 - Improve hardcoded-string gate messaging for route paths
+ */
+/**
+ * Path type constants
+ * @type {Object}
+ */
+export declare const PATH_TYPES: Readonly<{
+    ROUTE: "route";
+    FILESYSTEM: "filesystem";
+    UNKNOWN: "unknown";
+}>;
+/**
+ * Classify a path string as route, filesystem, or unknown
+ *
+ * @param {string} pathStr - The path string to classify
+ * @returns {string} One of PATH_TYPES values
+ */
+export declare function classifyPath(pathStr: any): "unknown" | "route" | "filesystem";
+/**
+ * Get the appropriate remediation message for a path type
+ *
+ * @param {string} pathType - One of PATH_TYPES values
+ * @returns {string} Remediation message
+ */
+export declare function getRemediation(pathType: any): any;
+/**
+ * Options for hardcoded path violation detection
+ */
+export interface FindHardcodedPathViolationsOptions {
+    /** Whether this is a test file (skip detection) */
+    isTestFile?: boolean;
+    /** Whether this is a config file (skip detection) */
+    isConfigFile?: boolean;
+}
+/**
+ * Find hardcoded path violations in a line of code
+ *
+ * @param {string} line - The line of code to check
+ * @param {FindHardcodedPathViolationsOptions} options - Options for detection
+ * @returns {Array<{line: string, fix: string, pathType: string, path: string}>} Array of violations
+ */
+export declare function findHardcodedPathViolations(line: any, options?: FindHardcodedPathViolationsOptions): any[];
+/**
+ * Legacy function for backwards compatibility with gates-pre-commit.mjs
+ * Detects all hardcoded string patterns (not just paths)
+ *
+ * @deprecated Use findHardcodedPathViolations for path-specific detection
+ */
+export declare const HARDCODED_PATTERNS: {
+    pattern: RegExp;
+    message: string;
+}[];

package/dist/hardcoded-strings.js

@@ -0,0 +1,270 @@
+/**
+ * Hardcoded String Detection Module
+ *
+ * Provides classification of hardcoded path strings to distinguish between:
+ * - Route paths (API endpoints, webhooks, etc.) - should use endpoint constants
+ * - Filesystem paths (absolute paths, config files) - should use path.join()
+ *
+ * This enables Gate 13 to provide accurate, actionable remediation messages.
+ *
+ * @see WU-1788 - Improve hardcoded-string gate messaging for route paths
+ */
+/**
+ * Path type constants
+ * @type {Object}
+ */
+export const PATH_TYPES = Object.freeze({
+    ROUTE: 'route',
+    FILESYSTEM: 'filesystem',
+    UNKNOWN: 'unknown',
+});
+/**
+ * Route path prefixes that indicate API/web endpoints
+ * These should use endpoint constants, not path.join()
+ */
+const ROUTE_PREFIXES = [
+    '/api/',
+    '/api?', // API with query params
+    '/auth/',
+    '/v1/',
+    '/v2/',
+    '/v3/',
+    '/graphql',
+    '/webhook/',
+    '/webhooks/',
+    '/trpc/',
+    '/rest/',
+    '/rpc/',
+];
+/**
+ * Filesystem path prefixes that indicate absolute paths
+ * These should use path.join() with constants
+ */
+const FILESYSTEM_PREFIXES = [
+    '/home/',
+    '/usr/',
+    '/etc/',
+    '/var/',
+    '/tmp/',
+    '/opt/',
+    '/bin/',
+    '/sbin/',
+    '/lib/',
+    '/proc/',
+    '/sys/',
+    '/dev/',
+    '/mnt/',
+    '/media/',
+    '/srv/',
+    '/root/',
+];
+/**
+ * Common file extensions that indicate filesystem paths
+ */
+const FILE_EXTENSIONS = [
+    '.json',
+    '.yaml',
+    '.yml',
+    '.xml',
+    '.conf',
+    '.config',
+    '.cfg',
+    '.ini',
+    '.env',
+    '.log',
+    '.txt',
+    '.md',
+    '.csv',
+    '.tsv',
+    '.sql',
+    '.sh',
+    '.bash',
+    '.zsh',
+    '.py',
+    '.rb',
+    '.pl',
+    '.js',
+    '.ts',
+    '.jsx',
+    '.tsx',
+    '.js',
+    '.cjs',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.svg',
+    '.ico',
+    '.pdf',
+    '.doc',
+    '.docx',
+    '.xls',
+    '.xlsx',
+    '.pem',
+    '.key',
+    '.crt',
+    '.cer',
+];
+/**
+ * Patterns that indicate filesystem paths
+ */
+const FILESYSTEM_PATTERNS = [
+    /^[A-Z]:[/\\]/, // Windows drive letter (C:\, D:/)
+    /node_modules/, // Node.js modules directory
+    /\.\.\//, // Relative path traversal
+    /~\//, // Home directory shorthand
+];
+/**
+ * Classify a path string as route, filesystem, or unknown
+ *
+ * @param {string} pathStr - The path string to classify
+ * @returns {string} One of PATH_TYPES values
+ */
+export function classifyPath(pathStr) {
+    if (!pathStr || pathStr === '/') {
+        return PATH_TYPES.UNKNOWN;
+    }
+    const normalizedPath = pathStr.toLowerCase();
+    // Check for route path indicators first (more specific)
+    for (const prefix of ROUTE_PREFIXES) {
+        if (normalizedPath.startsWith(prefix) || normalizedPath.includes(prefix)) {
+            return PATH_TYPES.ROUTE;
+        }
+    }
+    // Check for query parameters (indicates a route/URL)
+    if (pathStr.includes('?') && pathStr.startsWith('/')) {
+        return PATH_TYPES.ROUTE;
+    }
+    // Check for filesystem path prefixes
+    for (const prefix of FILESYSTEM_PREFIXES) {
+        if (normalizedPath.startsWith(prefix)) {
+            return PATH_TYPES.FILESYSTEM;
+        }
+    }
+    // Check for file extensions
+    for (const ext of FILE_EXTENSIONS) {
+        if (normalizedPath.endsWith(ext)) {
+            return PATH_TYPES.FILESYSTEM;
+        }
+    }
+    // Check for filesystem patterns
+    for (const pattern of FILESYSTEM_PATTERNS) {
+        if (pattern.test(pathStr)) {
+            return PATH_TYPES.FILESYSTEM;
+        }
+    }
+    // Default to unknown for ambiguous paths
+    return PATH_TYPES.UNKNOWN;
+}
+/**
+ * Remediation messages for each path type
+ */
+const REMEDIATION_MESSAGES = Object.freeze({
+    [PATH_TYPES.ROUTE]: 'Route path - use an endpoint constant or config (e.g., BEACON_API_ENDPOINT, API_ROUTES.ASSISTANT)',
+    [PATH_TYPES.FILESYSTEM]: 'File path - use path.join() with constants',
+    [PATH_TYPES.UNKNOWN]: 'Path string - use a constant or configuration value',
+});
+/**
+ * Get the appropriate remediation message for a path type
+ *
+ * @param {string} pathType - One of PATH_TYPES values
+ * @returns {string} Remediation message
+ */
+export function getRemediation(pathType) {
+    // Validate pathType to prevent object injection
+    const validTypes = Object.values(PATH_TYPES);
+    if (validTypes.includes(pathType)) {
+        // eslint-disable-next-line security/detect-object-injection -- Safe: pathType validated against known values above
+        return REMEDIATION_MESSAGES[pathType];
+    }
+    return REMEDIATION_MESSAGES[PATH_TYPES.UNKNOWN];
+}
+/**
+ * Pattern to match path-like strings in code
+ * Matches quoted strings that:
+ * - Start with /
+ * - Have at least one path segment after the initial /
+ * - May include alphanumeric characters, underscores, hyphens, dots
+ * - May include query parameters
+ *
+ * Note: Uses non-greedy quantifiers and avoids nested quantifiers to prevent ReDoS
+ */
+// eslint-disable-next-line security/detect-unsafe-regex -- Intentionally simplified pattern, not user-controlled
+const PATH_PATTERN = /['"](\/[\w./-]+(?:\?[^'"]*)?)['"]/gi;
+/**
+ * Check if a line contains a constant definition (SCREAMING_SNAKE_CASE)
+ *
+ * @param {string} line - The line to check
+ * @returns {boolean} True if line defines a constant
+ */
+function isConstantDefinition(line) {
+    if (!line.includes('const '))
+        return false;
+    const afterConst = line.split('const ')[1];
+    if (!afterConst)
+        return false;
+    const identifier = afterConst.trim().split(/[\s=]/)[0];
+    return identifier && identifier === identifier.toUpperCase() && identifier.length > 1;
+}
+/**
+ * Find hardcoded path violations in a line of code
+ *
+ * @param {string} line - The line of code to check
+ * @param {FindHardcodedPathViolationsOptions} options - Options for detection
+ * @returns {Array<{line: string, fix: string, pathType: string, path: string}>} Array of violations
+ */
+export function findHardcodedPathViolations(line, options = {}) {
+    const { isTestFile = false, isConfigFile = false } = options;
+    // Skip test files and config files
+    if (isTestFile || isConfigFile) {
+        return [];
+    }
+    // Skip constant definitions (they ARE the constants we want people to create)
+    if (isConstantDefinition(line)) {
+        return [];
+    }
+    // Skip lines that look like test context
+    if (line.includes('.test.') || line.includes('.spec.')) {
+        return [];
+    }
+    const violations = [];
+    let match;
+    // Reset regex lastIndex for global matching
+    PATH_PATTERN.lastIndex = 0;
+    while ((match = PATH_PATTERN.exec(line)) !== null) {
+        const pathStr = match[1];
+        // Only flag paths that start with /
+        if (!pathStr.startsWith('/')) {
+            continue;
+        }
+        const pathType = classifyPath(pathStr);
+        const remediation = getRemediation(pathType);
+        violations.push({
+            line: line.substring(0, 80),
+            fix: remediation,
+            pathType,
+            path: pathStr,
+        });
+    }
+    return violations;
+}
+/**
+ * Legacy function for backwards compatibility with gates-pre-commit.mjs
+ * Detects all hardcoded string patterns (not just paths)
+ *
+ * @deprecated Use findHardcodedPathViolations for path-specific detection
+ */
+export const HARDCODED_PATTERNS = [
+    {
+        pattern: /['"]https?:\/\/[^'"]+\/api\//i,
+        message: 'API endpoint - use environment variable or config',
+    },
+    {
+        pattern: /throw new Error\s*\(\s*['"][^'"]{50,}['"]\s*\)/i,
+        message: 'Long error message - use error constants',
+    },
+    // WU-1788: Path pattern now uses classifier for accurate messages
+    // The old pattern is replaced by findHardcodedPathViolations
+    { pattern: /['"]#[0-9a-fA-F]{6}['"]/i, message: 'Color value - use theme/design tokens' },
+    { pattern: /if\s*\(\s*['"]feature_/i, message: 'Feature flag - use feature flag service' },
+];

package/dist/incremental-lint.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file incremental-lint.mjs
+ * @description Incremental linting utilities for gates
+ * WU-1304: Optimise ESLint gates performance
+ *
+ * Provides utilities to determine which files need linting based on
+ * changes since branching from main, enabling faster gate execution.
+ */
+/**
+ * File extensions that should be linted by ESLint
+ * @type {string[]}
+ */
+export declare const LINTABLE_EXTENSIONS: string[];
+/**
+ * Check if a file path should be linted
+ * @param {string} filePath - File path to check
+ * @returns {boolean} True if file should be linted
+ */
+export declare function isLintableFile(filePath: any): boolean;
+/**
+ * Git adapter interface for testing
+ */
+interface GitAdapter {
+    mergeBase: (ref1: string, ref2: string) => Promise<string>;
+    raw: (args: string[]) => Promise<string>;
+}
+/**
+ * Options for getting changed lintable files
+ */
+export interface GetChangedLintableFilesOptions {
+    /** GitAdapter instance (for testing) */
+    git?: GitAdapter;
+    /** Base branch to compare against */
+    baseBranch?: string;
+    /** Optional path prefix to filter files */
+    filterPath?: string;
+}
+/**
+ * Get list of changed files that should be linted
+ * Includes:
+ * - Committed changes since branching from main (git diff merge-base...HEAD)
+ * - Modified but unstaged files (git diff --name-only)
+ * - Untracked files (git ls-files --others --exclude-standard)
+ *
+ * WU-1784: Extended to include untracked and unstaged files to prevent
+ * lint gaps when gates are run before staging/committing changes.
+ *
+ * @param {GetChangedLintableFilesOptions} [options] - Options
+ * @returns {Promise<string[]>} List of file paths to lint
+ *
+ * @example
+ * // Get all changed lintable files
+ * const files = await getChangedLintableFiles();
+ *
+ * @example
+ * // Get only files in apps/web/
+ * const files = await getChangedLintableFiles({ filterPath: 'apps/web/' });
+ */
+export declare function getChangedLintableFiles(options?: GetChangedLintableFilesOptions): Promise<any[]>;
+/**
+ * Convert repo-relative file paths to package-relative paths
+ *
+ * WU-2571: ESLint runs from package directory (e.g., apps/web/) where
+ * repo-relative paths (e.g., apps/web/src/file.ts) don't exist.
+ * This function strips the package prefix to produce paths that
+ * work correctly when ESLint is run from the package directory.
+ *
+ * @param {string[]} repoRelativePaths - Paths relative to repo root (e.g., ['apps/web/src/app.ts'])
+ * @param {string} packagePrefix - Package directory prefix (e.g., 'apps/web/' or 'apps/web')
+ * @returns {string[]} Paths relative to package directory (e.g., ['src/app.ts'])
+ *
+ * @example
+ * const repoRelative = ['apps/web/src/app.ts', 'apps/web/src/lib.tsx'];
+ * const packageRelative = convertToPackageRelativePaths(repoRelative, 'apps/web/');
+ * // Returns: ['src/app.ts', 'src/lib.tsx']
+ */
+export declare function convertToPackageRelativePaths(repoRelativePaths: any, packagePrefix: any): any;
+export {};

package/dist/incremental-lint.js

@@ -0,0 +1,129 @@
+/**
+ * @file incremental-lint.mjs
+ * @description Incremental linting utilities for gates
+ * WU-1304: Optimise ESLint gates performance
+ *
+ * Provides utilities to determine which files need linting based on
+ * changes since branching from main, enabling faster gate execution.
+ */
+import { getGitForCwd } from './git-adapter.js';
+import { STRING_LITERALS } from './wu-constants.js';
+/**
+ * File extensions that should be linted by ESLint
+ * @type {string[]}
+ */
+export const LINTABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.js'];
+/**
+ * Directory patterns that should be ignored
+ * Matches ESLint ignores in apps/web/eslint.config.mjs
+ * @type {string[]}
+ */
+const IGNORED_DIRECTORIES = [
+    'node_modules/',
+    '.next/',
+    '.expo/',
+    'dist/',
+    'build/',
+    '.turbo/',
+    'coverage/',
+    'worktrees/',
+];
+/**
+ * Check if a file path should be linted
+ * @param {string} filePath - File path to check
+ * @returns {boolean} True if file should be linted
+ */
+export function isLintableFile(filePath) {
+    // Check if in ignored directory
+    for (const ignored of IGNORED_DIRECTORIES) {
+        if (filePath.includes(ignored)) {
+            return false;
+        }
+    }
+    // Check if has lintable extension
+    for (const ext of LINTABLE_EXTENSIONS) {
+        if (filePath.endsWith(ext)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parse git output into a list of file paths
+ * @param {string} output - Git command output
+ * @returns {string[]} List of file paths
+ */
+function parseGitFileList(output) {
+    return output
+        .split(STRING_LITERALS.NEWLINE)
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+}
+/**
+ * Get list of changed files that should be linted
+ * Includes:
+ * - Committed changes since branching from main (git diff merge-base...HEAD)
+ * - Modified but unstaged files (git diff --name-only)
+ * - Untracked files (git ls-files --others --exclude-standard)
+ *
+ * WU-1784: Extended to include untracked and unstaged files to prevent
+ * lint gaps when gates are run before staging/committing changes.
+ *
+ * @param {GetChangedLintableFilesOptions} [options] - Options
+ * @returns {Promise<string[]>} List of file paths to lint
+ *
+ * @example
+ * // Get all changed lintable files
+ * const files = await getChangedLintableFiles();
+ *
+ * @example
+ * // Get only files in apps/web/
+ * const files = await getChangedLintableFiles({ filterPath: 'apps/web/' });
+ */
+export async function getChangedLintableFiles(options = {}) {
+    const { git = getGitForCwd(), baseBranch = 'origin/main', filterPath } = options;
+    // Get the merge base (common ancestor) with the base branch
+    const mergeBase = await git.mergeBase('HEAD', baseBranch);
+    // 1. Get committed changes since the merge base
+    const committedOutput = await git.raw(['diff', '--name-only', `${mergeBase}...HEAD`]);
+    const committedFiles = parseGitFileList(committedOutput);
+    // 2. Get modified but unstaged files (WU-1784)
+    const unstagedOutput = await git.raw(['diff', '--name-only']);
+    const unstagedFiles = parseGitFileList(unstagedOutput);
+    // 3. Get untracked files (WU-1784)
+    const untrackedOutput = await git.raw(['ls-files', '--others', '--exclude-standard']);
+    const untrackedFiles = parseGitFileList(untrackedOutput);
+    // Combine all sources and deduplicate using Set
+    const allFiles = [...new Set([...committedFiles, ...unstagedFiles, ...untrackedFiles])];
+    // Filter to lintable files
+    let lintableFiles = allFiles.filter(isLintableFile);
+    // Apply path filter if specified
+    if (filterPath) {
+        lintableFiles = lintableFiles.filter((f) => f.startsWith(filterPath));
+    }
+    return lintableFiles;
+}
+/**
+ * Convert repo-relative file paths to package-relative paths
+ *
+ * WU-2571: ESLint runs from package directory (e.g., apps/web/) where
+ * repo-relative paths (e.g., apps/web/src/file.ts) don't exist.
+ * This function strips the package prefix to produce paths that
+ * work correctly when ESLint is run from the package directory.
+ *
+ * @param {string[]} repoRelativePaths - Paths relative to repo root (e.g., ['apps/web/src/app.ts'])
+ * @param {string} packagePrefix - Package directory prefix (e.g., 'apps/web/' or 'apps/web')
+ * @returns {string[]} Paths relative to package directory (e.g., ['src/app.ts'])
+ *
+ * @example
+ * const repoRelative = ['apps/web/src/app.ts', 'apps/web/src/lib.tsx'];
+ * const packageRelative = convertToPackageRelativePaths(repoRelative, 'apps/web/');
+ * // Returns: ['src/app.ts', 'src/lib.tsx']
+ */
+export function convertToPackageRelativePaths(repoRelativePaths, packagePrefix) {
+    // Normalize the prefix to ensure it ends with a slash
+    const normalizedPrefix = packagePrefix.endsWith('/') ? packagePrefix : `${packagePrefix}/`;
+    return repoRelativePaths
+        .filter((filePath) => filePath.startsWith(normalizedPrefix))
+        .map((filePath) => filePath.slice(normalizedPrefix.length));
+}

package/dist/incremental-test.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file incremental-test.mjs
+ * @description Helpers for Vitest --changed execution
+ *
+ * WU-1920: Add incremental test execution to gates
+ * WU-2504: Use Vitest --changed instead of custom file diff logic
+ */
+/**
+ * Glob patterns to exclude slow integration/golden tests from changed runs.
+ * @type {string[]}
+ */
+export declare const VITEST_CHANGED_EXCLUDES: readonly string[];
+/**
+ * File extensions considered executable code for test runs.
+ * @type {string[]}
+ */
+export declare const CODE_FILE_EXTENSIONS: readonly string[];
+/**
+ * Check if a path points to a code file that should trigger full tests.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if the path has a code extension
+ */
+export declare function isCodeFilePath(filePath: any): boolean;
+/**
+ * Options for building Vitest changed args
+ */
+interface BuildVitestChangedArgsOptions {
+    /** Base branch for diff */
+    baseBranch?: string;
+}
+/**
+ * Build Vitest CLI args for --changed runs.
+ *
+ * @param {BuildVitestChangedArgsOptions} [options]
+ * @returns {string[]} Vitest args for changed test runs
+ */
+export declare function buildVitestChangedArgs(options?: BuildVitestChangedArgsOptions): string[];
+export {};

package/dist/incremental-test.js

@@ -0,0 +1,61 @@
+/**
+ * @file incremental-test.mjs
+ * @description Helpers for Vitest --changed execution
+ *
+ * WU-1920: Add incremental test execution to gates
+ * WU-2504: Use Vitest --changed instead of custom file diff logic
+ */
+import { GIT_REFS } from './wu-constants.js';
+/**
+ * Glob patterns to exclude slow integration/golden tests from changed runs.
+ * @type {string[]}
+ */
+export const VITEST_CHANGED_EXCLUDES = Object.freeze(['**/*.integration.*', '**/golden-*.test.*']);
+/**
+ * File extensions considered executable code for test runs.
+ * @type {string[]}
+ */
+export const CODE_FILE_EXTENSIONS = Object.freeze([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.js',
+    '.cjs',
+    '.mts',
+    '.cts',
+]);
+/**
+ * Check if a path points to a code file that should trigger full tests.
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if the path has a code extension
+ */
+export function isCodeFilePath(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    const normalized = filePath.replace(/\\/g, '/').toLowerCase();
+    return CODE_FILE_EXTENSIONS.some((ext) => normalized.endsWith(ext));
+}
+/**
+ * Build Vitest CLI args for --changed runs.
+ *
+ * @param {BuildVitestChangedArgsOptions} [options]
+ * @returns {string[]} Vitest args for changed test runs
+ */
+export function buildVitestChangedArgs(options = {}) {
+    const { baseBranch = GIT_REFS.ORIGIN_MAIN } = options;
+    const args = [
+        '--changed',
+        baseBranch,
+        '--run',
+        '--passWithNoTests',
+        '--maxWorkers=1',
+        '--teardownTimeout=30000',
+    ];
+    for (const pattern of VITEST_CHANGED_EXCLUDES) {
+        args.push(`--exclude='${pattern}'`);
+    }
+    return args;
+}