@halecraft/verify 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,532 @@
+/**
+ * Command to execute for verification
+ */
+interface VerificationCommand {
+    /** The command/binary to run */
+    cmd: string;
+    /** Arguments to pass to the command */
+    args: string[];
+    /** Working directory (defaults to cwd) */
+    cwd?: string;
+    /** Environment variables to set */
+    env?: Record<string, string>;
+}
+/**
+ * Result from parsing command output
+ */
+interface ParsedResult {
+    /** One-line summary for display */
+    summary: string;
+    /** Optional metrics extracted from output */
+    metrics?: {
+        passed?: number;
+        failed?: number;
+        total?: number;
+        duration?: string;
+        errors?: number;
+        warnings?: number;
+    };
+}
+/**
+ * Output parser interface
+ */
+interface OutputParser {
+    /** Unique identifier for this parser */
+    id: string;
+    /** Parse command output and return structured result */
+    parse(output: string, exitCode: number): ParsedResult | null;
+}
+/**
+ * Execution strategy for child nodes
+ */
+type ExecutionStrategy = "parallel" | "sequential" | "fail-fast";
+/**
+ * A node in the verification tree
+ */
+interface VerificationNode {
+    /** Unique key for this node (used in CLI filtering) */
+    key: string;
+    /** Human-readable name */
+    name?: string;
+    /** Command to run (leaf nodes only) */
+    run?: VerificationCommand | string | [string, string[]];
+    /** Child verification nodes */
+    children?: VerificationNode[];
+    /** Execution strategy for children (default: parallel) */
+    strategy?: ExecutionStrategy;
+    /** Parser ID to use for output (auto-detected if not specified) */
+    parser?: string;
+    /** Success message template */
+    successLabel?: string;
+    /** Failure message template */
+    failureLabel?: string;
+    /**
+     * Tasks that must pass for this task's failure to be reported.
+     * If any dependency fails, this task's failure output is suppressed.
+     * Can specify task keys (e.g., "format") or full paths (e.g., "types:tsc").
+     */
+    reportingDependsOn?: string[];
+}
+/**
+ * Options for the verification runner
+ */
+interface VerifyOptions {
+    /** Log verbosity: all, failed, none */
+    logs?: "all" | "failed" | "none";
+    /** Output format */
+    format?: "human" | "json";
+    /** Filter to specific task paths (e.g., "logic:ts") */
+    filter?: string[];
+    /** Working directory */
+    cwd?: string;
+    /** Disable colors */
+    noColor?: boolean;
+    /** Show only top-level tasks (hide descendants) */
+    topLevelOnly?: boolean;
+    /** Force sequential output (disable live dashboard) */
+    noTty?: boolean;
+}
+/**
+ * Package discovery options for monorepos
+ */
+interface PackageDiscoveryOptions {
+    /** Glob patterns for package directories */
+    patterns?: string[];
+    /** Filter to specific packages */
+    filter?: string[];
+    /** Include packages that have changed (git-aware) */
+    changed?: boolean;
+}
+/**
+ * Root configuration for verify
+ */
+interface VerifyConfig {
+    /** Root verification tasks */
+    tasks: VerificationNode[];
+    /** Monorepo package discovery options */
+    packages?: PackageDiscoveryOptions;
+    /** Default options */
+    options?: VerifyOptions;
+}
+/**
+ * Result of a single verification task
+ */
+interface TaskResult {
+    /** Task key */
+    key: string;
+    /** Full path in tree (e.g., "logic:ts") */
+    path: string;
+    /** Whether the task passed */
+    ok: boolean;
+    /** Exit code */
+    code: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Raw output */
+    output: string;
+    /** Parsed summary line */
+    summaryLine: string;
+    /** Parsed metrics */
+    metrics?: ParsedResult["metrics"];
+    /** Child results (for group nodes) */
+    children?: TaskResult[];
+    /**
+     * Whether this task's failure output was suppressed due to a dependency failure.
+     * The task still ran and failed, but its output is hidden to reduce noise.
+     */
+    suppressed?: boolean;
+    /**
+     * The path of the dependency task that caused this task to be suppressed.
+     * Only set when suppressed is true.
+     */
+    suppressedBy?: string;
+}
+/**
+ * Overall verification run result
+ */
+interface VerifyResult {
+    /** Whether all tasks passed */
+    ok: boolean;
+    /** ISO timestamp when run started */
+    startedAt: string;
+    /** ISO timestamp when run finished */
+    finishedAt: string;
+    /** Total duration in milliseconds */
+    durationMs: number;
+    /** Individual task results */
+    tasks: TaskResult[];
+}
+
+/**
+ * Helper function for defining config with type inference
+ */
+declare function defineConfig(config: VerifyConfig): VerifyConfig;
+/**
+ * Helper function for defining a single verification task
+ */
+declare function defineTask(task: VerificationNode): VerificationNode;
+/**
+ * Find config file in directory
+ */
+declare function findConfigFile(cwd: string): string | null;
+/**
+ * Load config from file
+ */
+declare function loadConfig(configPath: string): Promise<VerifyConfig | null>;
+/**
+ * Load config from cwd or specified path
+ */
+declare function loadConfigFromCwd(cwd: string, configPath?: string): Promise<VerifyConfig | null>;
+/**
+ * Merge options with defaults.
+ *
+ * NOTE: The `satisfies AllKeys<VerifyOptions>` ensures this function handles
+ * all properties of VerifyOptions. If you add a new option to VerifyOptions,
+ * TypeScript will error here until you add it to the return object.
+ */
+declare function mergeOptions(configOptions?: VerifyOptions, cliOptions?: Partial<VerifyOptions>): VerifyOptions;
+
+/**
+ * Discovered package with its config
+ */
+interface DiscoveredPackage {
+    /** Package name from package.json */
+    name: string;
+    /** Relative path from root */
+    path: string;
+    /** Absolute path */
+    absolutePath: string;
+    /** Loaded verify config (if exists) */
+    config: VerifyConfig | null;
+}
+/**
+ * Discover packages in a monorepo
+ */
+declare function discoverPackages(rootDir: string, options?: PackageDiscoveryOptions): Promise<DiscoveredPackage[]>;
+/**
+ * Check if a package has changed (git-aware)
+ * This is a placeholder - full implementation would use git diff
+ */
+declare function hasPackageChanged(_packagePath: string, _baseBranch?: string): Promise<boolean>;
+
+/**
+ * A detected task candidate from package.json
+ */
+interface DetectedTask {
+    /** Suggested key for the task */
+    key: string;
+    /** Human-readable name */
+    name: string;
+    /** The npm script name that was detected */
+    scriptName: string;
+    /** The command to run (optimized direct path when possible) */
+    command: string;
+    /** Category for grouping (format, types, logic, build) */
+    category: "format" | "types" | "logic" | "build" | "other";
+    /** Parser to use for this task */
+    parser?: string;
+    /**
+     * Tasks that must pass for this task's failure to be reported.
+     * Auto-populated based on category (types/logic/build depend on format).
+     */
+    reportingDependsOn?: string[];
+}
+/**
+ * Detect tasks with proper package manager commands
+ * Uses optimized direct paths when possible, falls back to package manager
+ */
+declare function detectTasks(cwd: string): DetectedTask[];
+
+/**
+ * Output format for the generated config
+ */
+type OutputFormat = "ts" | "mts" | "js" | "mjs";
+/**
+ * Generate config content from selected tasks
+ */
+declare function generateConfigContent(tasks: DetectedTask[], format: OutputFormat): string;
+
+/**
+ * Options for the init command
+ */
+interface InitOptions {
+    /** Custom config output path */
+    config?: string;
+    /** Force overwrite existing file */
+    force: boolean;
+    /** Skip interactive prompts */
+    yes: boolean;
+    /** Working directory */
+    cwd: string;
+}
+/**
+ * Result of the init command
+ */
+interface InitResult {
+    /** Whether init succeeded */
+    success: boolean;
+    /** Path to the created config file (if successful) */
+    configPath?: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Run the init command
+ */
+declare function runInit(options: InitOptions): Promise<InitResult>;
+
+/**
+ * Parser for Biome linter/formatter output
+ * Extracts issue counts and file counts from biome check output
+ */
+declare const biomeParser: OutputParser;
+
+/**
+ * Generic fallback parser - just reports exit code
+ * This parser always returns a result (never null)
+ */
+declare const genericParser: {
+    readonly id: "generic";
+    readonly parse: (_output: string, exitCode: number) => ParsedResult;
+};
+
+/**
+ * Parser for Go test output
+ * Counts packages passed/failed from go test output
+ */
+declare const gotestParser: OutputParser;
+
+/**
+ * Parser for TypeScript compiler (tsc/tsgo) output
+ * Counts type errors and extracts diagnostics info
+ */
+declare const tscParser: OutputParser;
+
+/**
+ * Parser for vitest output
+ * Extracts test counts from vitest summary
+ */
+declare const vitestParser: OutputParser;
+
+/**
+ * Registry for output parsers
+ */
+declare class ParserRegistry {
+    private parsers;
+    constructor();
+    /**
+     * Register a custom parser
+     */
+    register(parser: OutputParser): void;
+    /**
+     * Get a parser by ID
+     */
+    get(id: string): OutputParser | undefined;
+    /**
+     * Auto-detect parser based on command
+     */
+    detectParser(cmd: string): string;
+    /**
+     * Parse output using the specified or auto-detected parser
+     */
+    parse(output: string, exitCode: number, parserId?: string, cmd?: string): ParsedResult;
+}
+declare const defaultRegistry: ParserRegistry;
+
+/**
+ * Reporter interface
+ */
+interface Reporter {
+    /** Called before any tasks start - initialize display */
+    onStart?(tasks: VerificationNode[]): void;
+    /** Called when a task starts */
+    onTaskStart(path: string, key: string): void;
+    /** Called when a task completes */
+    onTaskComplete(result: TaskResult): void;
+    /** Called when all tasks complete - cleanup display */
+    onFinish?(): void;
+    /** Called to output task logs */
+    outputLogs(results: TaskResult[], logsMode: "all" | "failed" | "none"): void;
+    /** Called to output final summary */
+    outputSummary(result: VerifyResult): void;
+}
+/**
+ * Base Reporter - common functionality for all reporters
+ */
+declare abstract class BaseReporter implements Reporter {
+    protected colorEnabled: boolean;
+    protected stream: NodeJS.WriteStream;
+    protected taskDepths: Map<string, number>;
+    constructor(options?: VerifyOptions);
+    /**
+     * Apply ANSI color code to string (if colors enabled)
+     */
+    protected c(code: string, s: string): string;
+    /**
+     * Get success mark (✓ or OK)
+     */
+    protected okMark(): string;
+    /**
+     * Get failure mark (✗ or FAIL)
+     */
+    protected failMark(): string;
+    /**
+     * Get suppressed mark (⊘ or SUPPRESSED)
+     */
+    protected suppressedMark(): string;
+    /**
+     * Get arrow symbol (→ or ->)
+     */
+    protected arrow(): string;
+    /**
+     * Get indentation string for a given depth
+     */
+    protected getIndent(depth: number): string;
+    /**
+     * Get task depth from path
+     */
+    protected getTaskDepth(path: string): number;
+    /**
+     * Recursively collect task depths from verification tree
+     */
+    protected collectTaskDepths(nodes: VerificationNode[], parentPath: string, depth: number): void;
+    /**
+     * Extract summary from task result
+     */
+    protected extractSummary(result: TaskResult): string;
+    /**
+     * Flatten nested task results into a single array
+     */
+    protected flattenResults(results: TaskResult[]): TaskResult[];
+    /**
+     * Output task logs
+     */
+    outputLogs(results: TaskResult[], logsMode: "all" | "failed" | "none"): void;
+    /**
+     * Output final summary
+     */
+    outputSummary(result: VerifyResult): void;
+    abstract onStart(tasks: VerificationNode[]): void;
+    abstract onTaskStart(path: string, key: string): void;
+    abstract onTaskComplete(result: TaskResult): void;
+    abstract onFinish(): void;
+}
+/**
+ * Live Dashboard Reporter - animated in-place updates for TTY
+ */
+declare class LiveDashboardReporter extends BaseReporter {
+    private topLevelOnly;
+    private tasks;
+    private taskOrder;
+    private spinner;
+    private lineCount;
+    constructor(options?: VerifyOptions);
+    /**
+     * Initialize task list from verification nodes
+     */
+    onStart(tasks: VerificationNode[]): void;
+    /**
+     * Recursively collect tasks from verification tree
+     */
+    private collectTasks;
+    /**
+     * Get display key - shows :key for nested, key for root
+     */
+    private getDisplayKey;
+    /**
+     * Check if task should be displayed based on topLevelOnly flag
+     */
+    private shouldDisplay;
+    /**
+     * Format a single task line
+     */
+    private formatLine;
+    /**
+     * Redraw all visible task lines
+     */
+    private redraw;
+    onTaskStart(path: string, _key: string): void;
+    onTaskComplete(result: TaskResult): void;
+    onFinish(): void;
+}
+/**
+ * Sequential Reporter - line-by-line output for non-TTY
+ * No indentation since parallel execution means output order doesn't reflect hierarchy
+ */
+declare class SequentialReporter extends BaseReporter {
+    private topLevelOnly;
+    constructor(options?: VerifyOptions);
+    onStart(tasks: VerificationNode[]): void;
+    /**
+     * Check if task should be displayed based on topLevelOnly flag
+     */
+    private shouldDisplay;
+    onTaskStart(path: string, _key: string): void;
+    onTaskComplete(result: TaskResult): void;
+    onFinish(): void;
+}
+/**
+ * JSON Reporter - machine-readable output
+ */
+declare class JSONReporter implements Reporter {
+    onStart(_tasks: VerificationNode[]): void;
+    onTaskStart(_path: string, _key: string): void;
+    onTaskComplete(_result: TaskResult): void;
+    onFinish(): void;
+    outputLogs(_results: TaskResult[], _logsMode: "all" | "failed" | "none"): void;
+    outputSummary(result: VerifyResult): void;
+    private serializeTasks;
+}
+/**
+ * Quiet Reporter - minimal output (summary only)
+ */
+declare class QuietReporter extends BaseReporter {
+    onStart(_tasks: VerificationNode[]): void;
+    onTaskStart(_path: string, _key: string): void;
+    onTaskComplete(_result: TaskResult): void;
+    onFinish(): void;
+    outputLogs(_results: TaskResult[], _logsMode: "all" | "failed" | "none"): void;
+    outputSummary(result: VerifyResult): void;
+}
+/**
+ * Create appropriate reporter based on options
+ */
+declare function createReporter(options: VerifyOptions): Reporter;
+
+interface RunnerCallbacks {
+    onTaskStart?: (path: string, key: string) => void;
+    onTaskComplete?: (result: TaskResult) => void;
+}
+/**
+ * Verification runner
+ */
+declare class VerificationRunner {
+    private registry;
+    private options;
+    private callbacks;
+    private dependencyTracker;
+    constructor(options?: VerifyOptions, registry?: ParserRegistry, callbacks?: RunnerCallbacks);
+    /**
+     * Run all verification tasks
+     */
+    run(tasks: VerificationNode[]): Promise<VerifyResult>;
+    /**
+     * Run a list of nodes with the appropriate strategy
+     */
+    private runNodes;
+    /**
+     * Run a single node (leaf or group)
+     */
+    private runNode;
+}
+
+/**
+ * Run verification with the given config and options
+ */
+declare function verify(config: VerifyConfig, cliOptions?: Partial<VerifyOptions>): Promise<VerifyResult>;
+/**
+ * Run verification from config file in cwd
+ */
+declare function verifyFromConfig(cwd?: string, cliOptions?: Partial<VerifyOptions>): Promise<VerifyResult>;
+
+export { type DetectedTask, type DiscoveredPackage, type ExecutionStrategy, type InitOptions, type InitResult, JSONReporter, LiveDashboardReporter, type OutputFormat, type OutputParser, type PackageDiscoveryOptions, type ParsedResult, ParserRegistry, QuietReporter, type Reporter, type RunnerCallbacks, SequentialReporter, SequentialReporter as TTYReporter, type TaskResult, type VerificationCommand, type VerificationNode, VerificationRunner, type VerifyConfig, type VerifyOptions, type VerifyResult, biomeParser, createReporter, defaultRegistry, defineConfig, defineTask, detectTasks, discoverPackages, findConfigFile, generateConfigContent, genericParser, gotestParser, hasPackageChanged, loadConfig, loadConfigFromCwd, mergeOptions, runInit, tscParser, verify, verifyFromConfig, vitestParser };