@yasserkhanorg/impact-gate 2.0.0

package/dist/esm/cli/commands/traceability.js

@@ -0,0 +1,73 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { readFileSync } from 'fs';
+import { resolveConfig } from '../../agent/config.js';
+import { captureTraceabilityInput } from '../../agent/traceability_capture.js';
+import { ingestTraceabilityInput } from '../../agent/traceability_ingest.js';
+export function runTraceabilityCaptureCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for traceability-capture command');
+        process.exit(1);
+    }
+    if (!args.traceabilityReportPath) {
+        console.error('Error: --traceability-report <path> is required for traceability-capture command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'impact',
+        gitSince: args.gitSince,
+        llmProvider: args.llmProvider,
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const output = captureTraceabilityInput({
+        appPath: config.path,
+        testsRoot: reportRoot,
+        reportPath: args.traceabilityReportPath,
+        sinceRef: args.gitSince || config.git.since,
+        outputPath: args.traceabilityCaptureOutputPath,
+        coverageMapPath: args.traceabilityCoverageMapPath,
+        changedFilesPath: args.traceabilityChangedFilesPath,
+    });
+    console.log(`Traceability input: ${output.outputPath}`);
+    console.log(`Traceability tests seen: ${output.testsSeen}`);
+    console.log(`Traceability runs generated: ${output.runsGenerated}`);
+    console.log(`Traceability changed files used: ${output.changedFilesUsed}`);
+    if (output.warnings.length > 0) {
+        console.log(`Traceability warnings: ${output.warnings.join(' | ')}`);
+    }
+}
+export function runTraceabilityIngestCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for traceability-ingest command');
+        process.exit(1);
+    }
+    if (!args.traceabilityInputPath) {
+        console.error('Error: --traceability-input <path> is required for traceability-ingest command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'impact',
+        llmProvider: args.llmProvider,
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const raw = JSON.parse(readFileSync(args.traceabilityInputPath, 'utf-8'));
+    const output = ingestTraceabilityInput(reportRoot, config.impact.traceability, raw, {
+        minHits: args.traceabilityMinHits,
+        maxFilesPerTest: args.traceabilityMaxFilesPerTest,
+        maxAgeDays: args.traceabilityMaxAgeDays,
+    });
+    console.log(`Traceability manifest: ${output.manifestPath}`);
+    console.log(`Traceability state: ${output.statePath}`);
+    console.log(`Traceability ingested entries: ${output.entriesIngested}`);
+    console.log(`Traceability tracked tests: ${output.testsTracked}`);
+    console.log(`Traceability tracked edges: ${output.edgesTracked}`);
+    if (output.warnings.length > 0) {
+        console.log(`Traceability warnings: ${output.warnings.join(' | ')}`);
+    }
+}

package/dist/esm/cli/commands/train.js

@@ -0,0 +1,355 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { execFileSync } from 'child_process';
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import * as readline from 'readline';
+import { resolveConfig } from '../../agent/config.js';
+import { loadRouteFamilyManifest, serializeManifest } from '../../knowledge/route_families.js';
+import { LLMProviderFactory } from '../../provider_factory.js';
+import { logger, LogLevel } from '../../logger.js';
+import { getVersion } from '../../version.js';
+import { scanProject } from '../../training/scanner.js';
+import { scanFromKnowledgeGraph } from '../../training/kg_scanner.js';
+import { mergeFamilies, detectStaleFamilies } from '../../training/merger.js';
+import { enrichFamilies } from '../../training/enricher.js';
+import { getCommitFiles, validateCommit, buildValidationReport, formatValidationReport } from '../../training/validator.js';
+import { loadKnowledgeGraph } from '../../knowledge/kg_bridge.js';
+class TrainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TrainError';
+    }
+}
+const MAX_BUDGET_USD = 10;
+/**
+ * Resolves train-specific options from CLI args.
+ * Unlike other commands (analyze, plan, heal) that use the shared resolveConfig()
+ * for full pipeline configuration, train only needs appPath and testsRoot.
+ * We call resolveConfig() solely to extract testsRoot from the config file.
+ */
+function resolveTrainOptions(args, autoConfig) {
+    const appPath = args.path || '.';
+    let testsRoot = args.testsRoot || appPath;
+    // Try to resolve testsRoot from config
+    if (autoConfig) {
+        try {
+            const { config } = resolveConfig(process.cwd(), autoConfig, {
+                path: appPath,
+                testsRoot: args.testsRoot,
+            });
+            testsRoot = config.testsRoot || config.path || appPath;
+        }
+        catch {
+            // use defaults
+        }
+    }
+    const outputPath = args.trainOutput ||
+        join(testsRoot, '.e2e-ai-agents', 'route-families.json');
+    // Validate --pr is a positive integer
+    if (args.trainPr !== undefined && (!Number.isInteger(args.trainPr) || args.trainPr <= 0)) {
+        throw new TrainError('--pr must be a positive integer');
+    }
+    // Validate --pr and --since are mutually exclusive
+    if (args.trainPr && args.gitSince) {
+        throw new TrainError('--pr and --since are mutually exclusive.');
+    }
+    // Validate --since format (reject leading '-' to prevent git flag injection)
+    const since = args.gitSince || 'HEAD~20';
+    if (/^-/.test(since) || !/^[a-zA-Z0-9_.~^@\/-]+$/.test(since)) {
+        throw new TrainError(`Invalid git ref: ${since}`);
+    }
+    // Validate budget bounds
+    const budget = args.budgetUSD || 0.50;
+    if (budget <= 0) {
+        throw new TrainError('--budget-usd must be a positive number');
+    }
+    if (budget > MAX_BUDGET_USD) {
+        throw new TrainError(`Budget exceeds maximum of $${MAX_BUDGET_USD}. Use a lower --budget-usd value.`);
+    }
+    const resolvedAppPath = resolve(appPath);
+    const resolvedTestsRoot = resolve(testsRoot);
+    const resolvedOutputPath = resolve(outputPath);
+    // Validate --path is a real project
+    if (!existsSync(resolvedAppPath)) {
+        throw new TrainError(`Project root not found: ${resolvedAppPath}`);
+    }
+    // Validate --output is within project boundary (append separator to prevent prefix attacks)
+    const inApp = resolvedOutputPath === resolvedAppPath || resolvedOutputPath.startsWith(resolvedAppPath + '/');
+    const inTests = resolvedOutputPath === resolvedTestsRoot || resolvedOutputPath.startsWith(resolvedTestsRoot + '/');
+    if (!inApp && !inTests) {
+        throw new TrainError(`Output path must be within the project root or tests root: ${resolvedOutputPath}`);
+    }
+    // Discover git repo root for monorepo-aware scanning and validation
+    let gitRepoRoot;
+    try {
+        gitRepoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: resolvedAppPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        // Not a git repo or git not available
+    }
+    // Resolve serverRoot: explicit flag, or auto-detect from git repo root
+    let serverRoot = args.serverPath;
+    if (!serverRoot && gitRepoRoot) {
+        const serverDir = join(gitRepoRoot, 'server');
+        if (existsSync(serverDir)) {
+            serverRoot = serverDir;
+        }
+    }
+    const resolvedServerRoot = serverRoot ? resolve(serverRoot) : undefined;
+    return {
+        appPath: resolvedAppPath,
+        testsRoot: resolvedTestsRoot,
+        serverRoot: resolvedServerRoot,
+        gitRepoRoot: gitRepoRoot ? resolve(gitRepoRoot) : undefined,
+        enrich: args.trainEnrich !== false,
+        validate: args.trainValidate || false,
+        since,
+        pr: args.trainPr,
+        outputPath: resolvedOutputPath,
+        dryRun: args.dryRun || false,
+        yes: args.trainYes || false,
+        budgetUSD: budget,
+    };
+}
+function ask(rl, question, defaultValue) {
+    const suffix = defaultValue ? ` (${defaultValue})` : '';
+    return new Promise((res) => {
+        rl.question(`${question}${suffix}: `, (answer) => {
+            res(answer.trim() || defaultValue || '');
+        });
+    });
+}
+export async function runTrainCommand(args, autoConfig) {
+    const opts = resolveTrainOptions(args, autoConfig);
+    const totalTimer = logger.timer('train-total');
+    const timings = {};
+    // Configure observability from CLI flags
+    if (args.verbose)
+        logger.setLevel(LogLevel.DEBUG);
+    if (args.jsonOutput)
+        logger.setJsonMode(true);
+    logger.info('impact-gate train');
+    logger.info('===================');
+    // ---------- Phase 1: Deterministic scan ----------
+    // Prefer knowledge graph when available
+    const kg = loadKnowledgeGraph(opts.appPath);
+    logger.info('Scanning project structure...');
+    if (opts.serverRoot) {
+        logger.info(`Server root: ${opts.serverRoot}`);
+    }
+    const scanTimer = logger.timer('scan');
+    let scanResult;
+    if (kg) {
+        logger.info('Using knowledge graph for scanning (found .understand-anything/knowledge-graph.json)');
+        scanResult = scanFromKnowledgeGraph(kg);
+        logger.info(`KG: ${kg.nodes.length} nodes, ${kg.edges.length} edges`);
+    }
+    else {
+        scanResult = scanProject(opts.appPath, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined, opts.serverRoot, opts.gitRepoRoot);
+    }
+    timings.scan = scanTimer.end();
+    logger.info(`Found ${scanResult.stats.totalSourceFiles} source files, ${scanResult.stats.totalTestFiles} test files`);
+    logger.info(`Discovered ${scanResult.families.length} candidate families`);
+    if (scanResult.families.length === 0) {
+        logger.info('No families discovered. Make sure your project has recognizable');
+        logger.info('source directories (src/, server/, app/) and test directories');
+        logger.info('(tests/, e2e/, specs/) with matching names.');
+        return;
+    }
+    // ---------- Phase 2: Merge with existing ----------
+    const mergeTimer = logger.timer('merge');
+    const existing = loadRouteFamilyManifest(opts.testsRoot);
+    if (existing) {
+        logger.info(`Found existing manifest with ${existing.families.length} families`);
+    }
+    let mergeResult = mergeFamilies(existing, scanResult.families);
+    timings.merge = mergeTimer.end();
+    logger.info(`Merge: ${mergeResult.summary}`);
+    // ---------- Phase 3: Stale detection ----------
+    if (mergeResult.manifest.families.length > 0) {
+        const stale = detectStaleFamilies(mergeResult.manifest, opts.appPath, opts.testsRoot);
+        if (stale.length > 0) {
+            logger.info(`Stale families detected (${stale.length}):`);
+            for (const id of stale) {
+                logger.info(`  ${id} — paths no longer exist`);
+            }
+            if (!opts.yes && !opts.dryRun && process.stdin.isTTY) {
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    const answer = await ask(rl, '  Remove stale families? [y/N]', 'N');
+                    if (answer.toLowerCase() === 'y') {
+                        const staleSet = new Set(stale);
+                        mergeResult.manifest.families = mergeResult.manifest.families.filter((f) => !staleSet.has(f.id));
+                        mergeResult.staleFamilies = stale;
+                        logger.info(`Removed ${stale.length} stale families`);
+                    }
+                }
+                finally {
+                    rl.close();
+                }
+            }
+        }
+    }
+    // ---------- Phase 4: LLM Enrichment ----------
+    let enrichTokens = 0;
+    let enrichCost = 0;
+    let enrichRequests = 0;
+    let enrichAvgResponseMs = 0;
+    if (opts.enrich) {
+        logger.info('Enriching with LLM...');
+        const enrichTimer = logger.timer('enrich');
+        try {
+            const provider = await LLMProviderFactory.createFromEnv();
+            const enrichResult = await enrichFamilies(mergeResult.manifest.families, scanResult.families, opts.appPath, provider, opts.budgetUSD, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined);
+            mergeResult.manifest.families = enrichResult.enrichedFamilies;
+            enrichTokens = enrichResult.tokensUsed;
+            enrichCost = enrichResult.costUSD;
+            enrichRequests = enrichResult.requestCount ?? 0;
+            enrichAvgResponseMs = enrichResult.avgResponseMs ?? 0;
+            logger.info(`Enriched ${enrichResult.enrichedFamilies.length} families`, {
+                tokens: enrichResult.tokensUsed,
+                cost: enrichResult.costUSD,
+                requests: enrichRequests,
+                avgResponseMs: enrichAvgResponseMs,
+            });
+            if (enrichResult.skippedFamilies.length > 0) {
+                logger.info(`Skipped ${enrichResult.skippedFamilies.length} families (budget limit)`);
+            }
+        }
+        catch (error) {
+            logger.warn(`LLM enrichment failed: ${error instanceof Error ? error.message : String(error)}`);
+            logger.warn('Continuing with deterministic results. Use --no-enrich to skip LLM.');
+        }
+        timings.enrich = enrichTimer.end();
+    }
+    // ---------- Phase 5: Write manifest ----------
+    const json = serializeManifest(mergeResult.manifest);
+    if (opts.dryRun) {
+        logger.info('Dry run — proposed manifest:');
+        console.log(json);
+    }
+    else {
+        const dir = dirname(opts.outputPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const tmpPath = `${opts.outputPath}.tmp`;
+        writeFileSync(tmpPath, json, 'utf-8');
+        renameSync(tmpPath, opts.outputPath);
+        logger.info(`Wrote ${opts.outputPath}`);
+        logger.info(`${mergeResult.manifest.families.length} families`);
+    }
+    // ---------- Phase 6: Report unmatched ----------
+    if (scanResult.unmatchedSourceDirs.length > 0 || scanResult.unmatchedTestDirs.length > 0) {
+        logger.info('Unmatched (review manually):');
+        for (const dir of scanResult.unmatchedSourceDirs.slice(0, 10)) {
+            logger.info(`  source: ${dir.relativePath}`);
+        }
+        for (const dir of scanResult.unmatchedTestDirs.slice(0, 10)) {
+            logger.info(`  test:   ${dir.relativePath}`);
+        }
+        if (scanResult.unmatchedSourceDirs.length + scanResult.unmatchedTestDirs.length > 20) {
+            logger.info('  ... and more');
+        }
+    }
+    // ---------- Phase 7: Validation (optional) ----------
+    let validationReport;
+    if (opts.validate) {
+        const validateTimer = logger.timer('validate');
+        // Build path prefixes for monorepo-aware path normalization.
+        // Git log returns repo-root-relative paths, but manifest globs are
+        // relative to appPath, testsRoot, or serverRoot.
+        const pathPrefixes = [];
+        if (opts.gitRepoRoot) {
+            const { relative: relPath } = await import('path');
+            for (const root of [opts.appPath, opts.testsRoot, opts.serverRoot].filter(Boolean)) {
+                const rel = relPath(opts.gitRepoRoot, root).replace(/\\/g, '/');
+                if (rel && !rel.startsWith('..') && rel !== '.') {
+                    pathPrefixes.push(rel.endsWith('/') ? rel : rel + '/');
+                }
+            }
+        }
+        logger.debug('Validation path prefixes', { prefixes: pathPrefixes });
+        if (opts.pr) {
+            logger.info(`Validating against PR #${opts.pr}...`);
+            // Check for gh CLI
+            const { execFileSync } = await import('child_process');
+            try {
+                execFileSync('gh', ['--version'], { stdio: 'pipe' });
+            }
+            catch {
+                throw new TrainError('--pr requires the GitHub CLI (gh). Install: https://cli.github.com/');
+            }
+            // Fetch PR changed files via gh CLI
+            let prFiles;
+            try {
+                const output = execFileSync('gh', ['pr', 'view', String(opts.pr), '--json', 'files', '-q', '.files[].path'], {
+                    cwd: opts.appPath,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                prFiles = output.trim().split('\n').filter(Boolean);
+            }
+            catch (error) {
+                throw new TrainError(`Error fetching PR #${opts.pr}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (prFiles.length === 0) {
+                logger.info('No files found in PR.');
+            }
+            else {
+                const validation = validateCommit(mergeResult.manifest, prFiles, `PR#${opts.pr}`, `PR #${opts.pr}`, pathPrefixes);
+                validationReport = buildValidationReport([validation], mergeResult.manifest);
+                logger.info(formatValidationReport(validationReport));
+            }
+        }
+        else {
+            logger.info(`Validating against git history (${opts.since})...`);
+            const commits = getCommitFiles(opts.gitRepoRoot || opts.appPath, opts.since);
+            if (commits.length === 0) {
+                logger.info('No commits found in range.');
+            }
+            else {
+                const validations = commits.map((c) => validateCommit(mergeResult.manifest, c.files, c.hash, c.message, pathPrefixes));
+                validationReport = buildValidationReport(validations, mergeResult.manifest);
+                logger.info(formatValidationReport(validationReport));
+            }
+        }
+        timings.validate = validateTimer.end();
+    }
+    timings.total = totalTimer.end();
+    // ---------- Write train report ----------
+    if (!opts.dryRun) {
+        const reportDir = dirname(opts.outputPath);
+        const trainReport = {
+            timestamp: new Date().toISOString(),
+            version: getVersion(),
+            timings,
+            families: {
+                total: mergeResult.manifest.families.length,
+                new: mergeResult.newFamilies.length,
+                updated: mergeResult.updatedFamilies.length,
+                stale: mergeResult.staleFamilies.length,
+            },
+            coverage: validationReport ? {
+                percent: validationReport.coveragePercent,
+                boundFiles: validationReport.boundFiles,
+                totalFiles: validationReport.totalFiles,
+            } : undefined,
+            llm: opts.enrich ? {
+                tokensUsed: enrichTokens,
+                costUSD: enrichCost,
+                requests: enrichRequests,
+                avgResponseMs: enrichAvgResponseMs,
+            } : undefined,
+        };
+        const reportPath = join(reportDir, 'train-report.json');
+        writeFileSync(reportPath, JSON.stringify(trainReport, null, 2) + '\n', 'utf-8');
+        logger.debug('Wrote train report', { path: reportPath });
+    }
+    logger.info('Done.');
+}

package/dist/esm/cli/defaults.js

@@ -0,0 +1,165 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { join, resolve } from 'path';
+function detectPytestFramework(appPath) {
+    const resolvedPath = resolve(appPath);
+    const pytestIni = join(resolvedPath, 'pytest.ini');
+    if (existsSync(pytestIni)) {
+        return 'pytest';
+    }
+    const conftest = join(resolvedPath, 'conftest.py');
+    if (existsSync(conftest)) {
+        return 'pytest';
+    }
+    const pyproject = join(resolvedPath, 'pyproject.toml');
+    if (existsSync(pyproject)) {
+        try {
+            const content = readFileSync(pyproject, 'utf-8');
+            if (content.includes('pytest')) {
+                return 'pytest';
+            }
+        }
+        catch {
+            // ignore malformed or unreadable file
+        }
+    }
+    const setupCfg = join(resolvedPath, 'setup.cfg');
+    if (existsSync(setupCfg)) {
+        try {
+            const content = readFileSync(setupCfg, 'utf-8');
+            if (content.includes('[tool:pytest]') || content.includes('[pytest]')) {
+                return 'pytest';
+            }
+        }
+        catch {
+            // ignore malformed or unreadable file
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect the test framework from package.json dependencies.
+ */
+export function detectFramework(appPath) {
+    const resolvedPath = resolve(appPath);
+    const pkgPath = join(resolvedPath, 'package.json');
+    if (!existsSync(pkgPath)) {
+        const pytestFramework = detectPytestFramework(resolvedPath);
+        if (pytestFramework) {
+            return pytestFramework;
+        }
+        return 'auto';
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        if (allDeps['@playwright/test'] || allDeps.playwright) {
+            return 'playwright';
+        }
+        if (allDeps.cypress) {
+            return 'cypress';
+        }
+        if (allDeps.supertest) {
+            return 'supertest';
+        }
+        if (allDeps['selenium-webdriver'] || allDeps.webdriverio) {
+            return 'selenium';
+        }
+    }
+    catch {
+        // ignore malformed package.json
+    }
+    const pytestFramework = detectPytestFramework(resolvedPath);
+    if (pytestFramework) {
+        return pytestFramework;
+    }
+    return 'auto';
+}
+/**
+ * Detect the tests root directory by scanning common conventions.
+ */
+export function detectTestsRoot(appPath) {
+    const resolvedPath = resolve(appPath);
+    const candidates = [
+        'e2e-tests/playwright',
+        'e2e-tests',
+        'e2e',
+        'tests/e2e',
+        'test/e2e',
+        'tests',
+        'test',
+        'specs',
+        'playwright',
+        'cypress',
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(join(resolvedPath, candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect the git default branch for diffing.
+ * Returns origin/<branch> format.
+ */
+export function detectGitDefaultBranch(appPath) {
+    try {
+        // Try to find the remote HEAD branch first
+        const remoteInfo = execFileSync('git', ['remote', 'show', 'origin'], {
+            cwd: resolve(appPath),
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        const headMatch = remoteInfo.match(/HEAD branch:\s*(.+)/);
+        if (headMatch) {
+            return `origin/${headMatch[1].trim()}`;
+        }
+    }
+    catch {
+        // fallback to current branch
+    }
+    try {
+        const result = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: resolve(appPath),
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).trim();
+        return `origin/${result}`;
+    }
+    catch {
+        return 'origin/main';
+    }
+}
+/**
+ * Detect the project root by walking up to find package.json or .git.
+ */
+export function detectProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, 'package.json')) || existsSync(join(current, '.git'))) {
+            return current;
+        }
+        const parent = resolve(current, '..');
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return startDir;
+}
+/**
+ * Resolve defaults for CLI commands that need path/testsRoot/framework/since.
+ * Explicit values from CLI flags take precedence over detected values.
+ */
+export function resolveDefaults(explicit) {
+    const path = explicit.path || detectProjectRoot(process.cwd());
+    const testsRoot = explicit.testsRoot || detectTestsRoot(path) || '.';
+    const framework = explicit.framework || detectFramework(path);
+    const since = explicit.gitSince || detectGitDefaultBranch(path);
+    return { path, testsRoot, framework, since };
+}

package/dist/esm/cli/errors.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * CLI Error types with structured exit codes.
+ *
+ * Exit codes:
+ *   0 = success
+ *   1 = general/user error (bad args, missing config, invalid input)
+ *   2 = budget exceeded
+ *   3 = LLM provider unavailable (API down, auth failure)
+ *   4 = invalid manifest or config file
+ */
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    GENERAL_ERROR: 1,
+    BUDGET_EXCEEDED: 2,
+    PROVIDER_UNAVAILABLE: 3,
+    INVALID_CONFIG: 4,
+};
+export class CliError extends Error {
+    constructor(message, exitCode = EXIT_CODES.GENERAL_ERROR) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'CliError';
+    }
+}
+/**
+ * Classify an unknown error into the appropriate exit code.
+ */
+export function classifyError(error) {
+    if (error instanceof CliError)
+        return error.exitCode;
+    const msg = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    // Budget errors
+    if (msg.includes('budget exceeded') || msg.includes('budget limit')) {
+        return EXIT_CODES.BUDGET_EXCEEDED;
+    }
+    // Provider/auth errors
+    if (msg.includes('api key') || msg.includes('authentication') ||
+        msg.includes('unauthorized') || msg.includes('403') ||
+        (msg.includes('provider') && msg.includes('unavailable')) ||
+        msg.includes('econnrefused') || msg.includes('econnreset')) {
+        return EXIT_CODES.PROVIDER_UNAVAILABLE;
+    }
+    // Config/manifest errors
+    if ((msg.includes('manifest') && (msg.includes('invalid') || msg.includes('not found') || msg.includes('parse'))) ||
+        (msg.includes('config') && msg.includes('invalid')) ||
+        (msg.includes('route-families') && msg.includes('invalid'))) {
+        return EXIT_CODES.INVALID_CONFIG;
+    }
+    return EXIT_CODES.GENERAL_ERROR;
+}