@halecraft/verify 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -8,8 +8,13 @@ interface VerificationCommand {
     args: string[];
     /** Working directory (defaults to cwd) */
     cwd?: string;
-    /** Environment variables to set */
-    env?: Record<string, string>;
+    /**
+     * Environment variables to set.
+     * Set to null to explicitly unset an inherited variable.
+     */
+    env?: Record<string, string | null>;
+    /** Timeout in milliseconds (process killed with SIGTERM if exceeded) */
+    timeout?: number;
 }
 /**
  * Result from parsing command output
@@ -48,8 +53,8 @@ interface VerificationNode {
     key: string;
     /** Human-readable name */
     name?: string;
-    /** Command to run (leaf nodes only) */
-    run?: VerificationCommand | string | [string, string[]];
+    /** Command to run (leaf nodes only) - string commands are executed via shell */
+    run?: VerificationCommand | string;
     /** Child verification nodes */
     children?: VerificationNode[];
     /** Execution strategy for children (default: parallel) */
@@ -66,6 +71,20 @@ interface VerificationNode {
      * Can specify task keys (e.g., "format") or full paths (e.g., "types:tsc").
      */
     reportingDependsOn?: string[];
+    /**
+     * Timeout in milliseconds for string commands.
+     * Process is killed with SIGTERM if exceeded.
+     * For VerificationCommand objects, use the timeout field on the command itself.
+     */
+    timeout?: number;
+    /**
+     * Environment variables for this task and its children.
+     * Inherits from parent tasks and config-level env.
+     * Child tasks can override parent values.
+     * Set to null to explicitly unset an inherited variable.
+     * For VerificationCommand objects, command-level env takes precedence.
+     */
+    env?: Record<string, string | null>;
 }
 /**
  * Options for the verification runner
@@ -85,6 +104,8 @@ interface VerifyOptions {
     topLevelOnly?: boolean;
     /** Force sequential output (disable live dashboard) */
     noTty?: boolean;
+    /** Arguments to pass through to the underlying command (requires single task filter) */
+    passthrough?: string[];
 }
 /**
  * Package discovery options for monorepos
@@ -107,6 +128,12 @@ interface VerifyConfig {
     packages?: PackageDiscoveryOptions;
     /** Default options */
     options?: VerifyOptions;
+    /**
+     * Global environment variables applied to all tasks.
+     * Set to null to explicitly unset an inherited variable.
+     * Recommend setting NO_COLOR: "1" here to disable colors in output.
+     */
+    env?: Record<string, string | null>;
 }
 /**
  * Result of a single verification task
@@ -140,6 +167,11 @@ interface TaskResult {
      * Only set when suppressed is true.
      */
     suppressedBy?: string;
+    /**
+     * Whether this task was terminated due to timeout.
+     * Only set when the task exceeded its configured timeout.
+     */
+    timedOut?: boolean;
 }
 /**
  * Overall verification run result
@@ -157,6 +189,17 @@ interface VerifyResult {
     tasks: TaskResult[];
 }
 
+/**
+ * Error thrown when config validation fails
+ */
+declare class ConfigError extends Error {
+    readonly configPath?: string | undefined;
+    constructor(message: string, configPath?: string | undefined);
+}
+/**
+ * Validate a config object and return typed result
+ */
+declare function validateConfig(value: unknown, configPath?: string): VerifyConfig;
 /**
  * Helper function for defining config with type inference
  */
@@ -209,6 +252,53 @@ declare function discoverPackages(rootDir: string, options?: PackageDiscoveryOpt
  */
 declare function hasPackageChanged(_packagePath: string, _baseBranch?: string): Promise<boolean>;
 
+/**
+ * Result of resolving a filter to a valid task path
+ */
+interface ResolvedFilter {
+    /** The original filter string provided by the user */
+    original: string;
+    /** The resolved full task path */
+    resolved: string;
+    /** Whether this was resolved via child shortcut (e.g., "tsc" → "types:tsc") */
+    wasShortcut: boolean;
+}
+/**
+ * Error thrown when a task filter doesn't match any existing task
+ */
+declare class TaskNotFoundError extends Error {
+    readonly filter: string;
+    readonly suggestion: string | undefined;
+    readonly availableTasks: string[];
+    readonly exitCode = 2;
+    constructor(filter: string, suggestion: string | undefined, availableTasks: string[]);
+}
+/**
+ * Error thrown when a task filter matches multiple tasks ambiguously
+ */
+declare class AmbiguousTaskError extends Error {
+    readonly filter: string;
+    readonly matches: string[];
+    readonly exitCode = 2;
+    constructor(filter: string, matches: string[]);
+}
+/**
+ * Find the single best suggestion using Levenshtein distance.
+ * Returns undefined if no good match (distance > threshold).
+ */
+declare function findBestSuggestion(availablePaths: string[], invalidFilter: string): string | undefined;
+/**
+ * Resolve and validate all filters before running any tasks.
+ * Fails fast on first invalid filter.
+ *
+ * @param nodes - The verification task tree
+ * @param filters - User-provided filter strings
+ * @returns Array of resolved filters
+ * @throws TaskNotFoundError if a filter doesn't match any task
+ * @throws AmbiguousTaskError if a filter matches multiple tasks
+ */
+declare function resolveFilters(nodes: VerificationNode[], filters: string[]): ResolvedFilter[];
+
 /**
  * A detected task candidate from package.json
  */
@@ -233,7 +323,7 @@ interface DetectedTask {
 }
 /**
  * Detect tasks with proper package manager commands
- * Uses optimized direct paths when possible, falls back to package manager
+ * Uses optimized direct binary names when possible, falls back to package manager
  */
 declare function detectTasks(cwd: string): DetectedTask[];
 
@@ -308,6 +398,35 @@ declare const tscParser: OutputParser;
  */
 declare const vitestParser: OutputParser;
 
+/**
+ * Parser ID constants for type-safe parser references.
+ * Use these instead of magic strings when specifying parsers in config.
+ *
+ * @example
+ * ```typescript
+ * import { parsers } from "@halecraft/verify"
+ *
+ * export default defineConfig({
+ *   tasks: [
+ *     { key: "test", run: "vitest run", parser: parsers.vitest },
+ *   ],
+ * })
+ * ```
+ */
+declare const parsers: {
+    /** Vitest/Jest test runner output parser */
+    readonly vitest: "vitest";
+    /** TypeScript compiler (tsc/tsgo) output parser */
+    readonly tsc: "tsc";
+    /** Biome/ESLint linter output parser */
+    readonly biome: "biome";
+    /** Go test runner output parser */
+    readonly gotest: "gotest";
+    /** Generic fallback parser */
+    readonly generic: "generic";
+};
+/** Type for valid parser IDs */
+type ParserId = (typeof parsers)[keyof typeof parsers];
 /**
  * Registry for output parsers
  */
@@ -325,7 +444,7 @@ declare class ParserRegistry {
     /**
      * Auto-detect parser based on command
      */
-    detectParser(cmd: string): string;
+    detectParser(cmd: string): ParserId;
     /**
      * Parse output using the specified or auto-detected parser
      */
@@ -387,9 +506,9 @@ declare abstract class BaseReporter implements Reporter {
      */
     protected getTaskDepth(path: string): number;
     /**
-     * Recursively collect task depths from verification tree
+     * Collect task depths from verification tree using walkNodes
      */
-    protected collectTaskDepths(nodes: VerificationNode[], parentPath: string, depth: number): void;
+    protected collectTaskDepths(nodes: VerificationNode[]): void;
     /**
      * Extract summary from task result
      */
@@ -426,7 +545,7 @@ declare class LiveDashboardReporter extends BaseReporter {
      */
     onStart(tasks: VerificationNode[]): void;
     /**
-     * Recursively collect tasks from verification tree
+     * Collect tasks from verification tree using walkNodes
      */
     private collectTasks;
     /**
@@ -505,7 +624,8 @@ declare class VerificationRunner {
     private options;
     private callbacks;
     private dependencyTracker;
-    constructor(options?: VerifyOptions, registry?: ParserRegistry, callbacks?: RunnerCallbacks);
+    private configEnv;
+    constructor(options?: VerifyOptions, registry?: ParserRegistry, callbacks?: RunnerCallbacks, configEnv?: Record<string, string | null>);
     /**
      * Run all verification tasks
      */
@@ -520,6 +640,32 @@ declare class VerificationRunner {
     private runNode;
 }
 
+/**
+ * Path separator used in task paths
+ */
+declare const PATH_SEPARATOR = ":";
+/**
+ * Build a task path from parent path and key
+ */
+declare function buildTaskPath(parentPath: string, key: string): string;
+/**
+ * Visitor function called for each node during tree traversal
+ */
+type NodeVisitor = (node: VerificationNode, path: string, depth: number) => void;
+/**
+ * Walk all nodes in a verification tree in depth-first order
+ *
+ * @param nodes - The nodes to walk
+ * @param visitor - Function called for each node with (node, path, depth)
+ * @param parentPath - Parent path prefix (used for recursion)
+ * @param depth - Current depth (used for recursion)
+ */
+declare function walkNodes(nodes: VerificationNode[], visitor: NodeVisitor, parentPath?: string, depth?: number): void;
+/**
+ * Collect all task paths from a verification tree
+ */
+declare function collectPaths(nodes: VerificationNode[]): string[];
+
 /**
  * Run verification with the given config and options
  */
@@ -529,4 +675,4 @@ declare function verify(config: VerifyConfig, cliOptions?: Partial<VerifyOptions
  */
 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 };
+export { AmbiguousTaskError, ConfigError, type DetectedTask, type DiscoveredPackage, type ExecutionStrategy, type InitOptions, type InitResult, JSONReporter, LiveDashboardReporter, type NodeVisitor, type OutputFormat, type OutputParser, PATH_SEPARATOR, type PackageDiscoveryOptions, type ParsedResult, type ParserId, ParserRegistry, QuietReporter, type Reporter, type ResolvedFilter, type RunnerCallbacks, SequentialReporter, SequentialReporter as TTYReporter, TaskNotFoundError, type TaskResult, type VerificationCommand, type VerificationNode, VerificationRunner, type VerifyConfig, type VerifyOptions, type VerifyResult, biomeParser, buildTaskPath, collectPaths, createReporter, defaultRegistry, defineConfig, defineTask, detectTasks, discoverPackages, findBestSuggestion, findConfigFile, generateConfigContent, genericParser, gotestParser, hasPackageChanged, loadConfig, loadConfigFromCwd, mergeOptions, parsers, resolveFilters, runInit, tscParser, validateConfig, verify, verifyFromConfig, vitestParser, walkNodes };