@halecraft/verify 1.0.0 → 1.1.0

package/README.md

@@ -58,6 +58,13 @@ pnpm exec verify
 # Run specific task
 pnpm exec verify format
 
+# Run nested task with full path
+pnpm exec verify types:tsc
+
+# Run nested task with shortcut (if unambiguous)
+pnpm exec verify tsc
+# → Resolving "tsc" to "types:tsc"
+
 # Run with verbose output
 pnpm exec verify --verbose
 
@@ -87,11 +94,10 @@ interface VerificationNode {
   name?: string;
 
   // Command to run (leaf nodes only)
-  // Supports: string, object with cmd/args/cwd, or [cmd, args] tuple
+  // Supports: string, object with cmd/args/cwd/timeout
   run?:
     | string
-    | { cmd: string; args: string[]; cwd?: string }
-    | [string, string[]];
+    | { cmd: string; args: string[]; cwd?: string; timeout?: number };
 
   // Child tasks (for grouping)
   children?: VerificationNode[];
@@ -105,6 +111,9 @@ interface VerificationNode {
   // Tasks that must pass for this task's failure to be reported
   reportingDependsOn?: string[];
 
+  // Timeout in milliseconds (for string commands)
+  timeout?: number;
+
   // Custom success message template (optional)
   successLabel?: string;
 
@@ -222,6 +231,39 @@ Control how child tasks are executed:
 - `sequential`: Run tasks one after another
 - `fail-fast`: Run sequentially, stop on first failure
 
+### Command Timeouts
+
+Prevent hung processes by setting a timeout (in milliseconds):
+
+```typescript
+import { defineConfig } from "@halecraft/verify";
+
+export default defineConfig({
+  tasks: [
+    // String command with timeout
+    { key: "test", run: "vitest run", timeout: 60000 }, // 60 seconds
+
+    // Object command with timeout
+    {
+      key: "build",
+      run: {
+        cmd: "tsup",
+        args: [],
+        timeout: 120000, // 2 minutes
+      },
+    },
+  ],
+});
+```
+
+When a command exceeds its timeout:
+
+- The process is killed with `SIGTERM` (including child processes)
+- The task is marked as failed with `timedOut: true`
+- The summary shows: `task: timed out after 60000ms`
+
+**Note:** For object commands, the `timeout` on the command takes precedence over the node-level `timeout`.
+
 ## CLI Options
 
 ```
@@ -243,6 +285,50 @@ Options:
   --help, -h          Show this help message
 ```
 
+### Exit Codes
+
+- `0` - All tasks passed
+- `1` - Some tasks failed
+- `2` - Configuration/usage error (invalid task name, missing config)
+
+### Task Name Validation
+
+Verify validates task names before running any tasks. If you specify a task that doesn't exist, you'll get a helpful error:
+
+```bash
+$ verify test
+Error: Task "test" not found.
+
+Did you mean "types:tsc"?
+
+Available tasks:
+  format
+  logic
+  types
+  types:tsc
+  types:tsgo
+  build
+```
+
+**Child task shortcuts:** You can use just the child key if it's unambiguous:
+
+```bash
+$ verify tsc
+→ Resolving "tsc" to "types:tsc"
+✓ verified types:tsc
+```
+
+If the shortcut is ambiguous (multiple tasks have the same child key), you'll get an error listing the options:
+
+```bash
+$ verify test  # if both unit:test and e2e:test exist
+Error: Task "test" is ambiguous.
+
+Matches multiple tasks:
+  unit:test
+  e2e:test
+```
+
 ## Programmatic API
 
 ```typescript
@@ -293,6 +379,7 @@ interface TaskResult {
   summaryLine: string; // Parsed summary
   suppressed?: boolean; // True if output was suppressed
   suppressedBy?: string; // Path of dependency that caused suppression
+  timedOut?: boolean; // True if task exceeded its timeout
   children?: TaskResult[]; // Child results (for group nodes)
 }
 ```
@@ -301,14 +388,38 @@ interface TaskResult {
 
 Built-in parsers for common tools:
 
-- **vitest** - Vitest test runner
-- **tsc** - TypeScript compiler
-- **biome** - Biome linter/formatter
+- **vitest** - Vitest/Jest test runner
+- **tsc** - TypeScript compiler (tsc/tsgo)
+- **biome** - Biome/ESLint linter/formatter
 - **gotest** - Go test runner
 - **generic** - Fallback for unknown tools
 
 Parsers automatically extract metrics (passed/failed counts, duration) and provide concise summaries.
 
+### Parser ID Constants
+
+Use `parsers` for type-safe parser references instead of magic strings:
+
+```typescript
+import { defineConfig, parsers } from "@halecraft/verify";
+
+export default defineConfig({
+  tasks: [
+    { key: "test", run: "vitest run", parser: parsers.vitest },
+    { key: "types", run: "tsc --noEmit", parser: parsers.tsc },
+    { key: "lint", run: "biome check .", parser: parsers.biome },
+  ],
+});
+```
+
+Available constants:
+
+- `parsers.vitest` - `"vitest"`
+- `parsers.tsc` - `"tsc"`
+- `parsers.biome` - `"biome"`
+- `parsers.gotest` - `"gotest"`
+- `parsers.generic` - `"generic"`
+
 ## License
 
 MIT

package/bin/verify.mjs

@@ -1,140 +1,109 @@
 #!/usr/bin/env node
 
-import { runInit, verifyFromConfig } from "../dist/index.js"
-
-/**
- * Parse CLI arguments
- */
-function parseArgs(args) {
-  const options = {
-    json: false,
-    verbose: false,
-    quiet: false,
-    logs: undefined,
-    filter: [],
-    config: undefined,
-    help: false,
-    init: false,
-    force: false,
-    yes: false,
-    topLevelOnly: false,
-    noTty: false,
-  }
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]
-
-    if (arg === "--json") {
-      options.json = true
-    } else if (arg === "--verbose" || arg === "-v") {
-      options.verbose = true
-    } else if (arg === "--quiet" || arg === "-q") {
-      options.quiet = true
-    } else if (arg === "--help" || arg === "-h") {
-      options.help = true
-    } else if (arg === "--init") {
-      options.init = true
-    } else if (arg === "--force") {
-      options.force = true
-    } else if (arg === "--yes" || arg === "-y") {
-      options.yes = true
-    } else if (arg === "--top-level" || arg === "-t") {
-      options.topLevelOnly = true
-    } else if (arg === "--no-tty") {
-      options.noTty = true
-    } else if (arg.startsWith("--logs=")) {
-      options.logs = arg.slice(7)
-    } else if (arg === "--logs") {
-      options.logs = args[++i]
-    } else if (arg.startsWith("--config=")) {
-      options.config = arg.slice(9)
-    } else if (arg === "--config" || arg === "-c") {
-      options.config = args[++i]
-    } else if (arg.startsWith("--filter=")) {
-      options.filter.push(arg.slice(9))
-    } else if (arg === "--filter" || arg === "-f") {
-      options.filter.push(args[++i])
-    } else if (!arg.startsWith("-")) {
-      // Positional argument treated as filter
-      options.filter.push(arg)
-    }
-  }
-
-  return options
-}
-
-/**
- * Print help message
- */
-function printHelp() {
-  console.log(`
-@halecraft/verify - Hierarchical verification runner
-
-Usage:
-  verify [options] [filter...]
-
-Options:
-  --json              Output results as JSON
-  --verbose, -v       Show all task output
-  --quiet, -q         Show only final result
-  --top-level, -t     Show only top-level tasks (hide descendants)
-  --no-tty            Force sequential output (disable live dashboard)
-  --logs=MODE         Log verbosity: all, failed, none (default: failed)
-  --config, -c PATH   Path to config file (or output path for --init)
-  --filter, -f PATH   Filter to specific task paths
-  --init              Initialize a new verify.config.ts file
-  --force             Overwrite existing config file (with --init)
-  --yes, -y           Skip interactive prompts, auto-accept detected tasks
-  --help, -h          Show this help message
-
-Examples:
-  verify                    Run all verifications
-  verify logic              Run only 'logic' tasks
-  verify logic:ts           Run only 'logic:ts' task
-  verify --top-level        Show only top-level tasks
-  verify --json             Output JSON for CI
-  verify --logs=all         Show all output
-  verify --init             Create config interactively
-  verify --init -y          Create config with all detected tasks
-  verify --init --force     Overwrite existing config
-
-Config:
-  Create a verify.config.ts file in your project root:
-
-  import { defineConfig } from '@halecraft/verify'
-
-  export default defineConfig({
-    tasks: [
-      { key: 'format', run: 'pnpm verify:format' },
-      { key: 'types', run: 'pnpm verify:types' },
-      {
-        key: 'logic',
-        children: [
-          { key: 'ts', run: 'vitest run' },
-          { key: 'go', run: 'go test ./...' },
-        ],
+import { cli } from "cleye"
+import {
+  AmbiguousTaskError,
+  runInit,
+  TaskNotFoundError,
+  verifyFromConfig,
+} from "../dist/index.js"
+
+const argv = cli(
+  {
+    name: "verify",
+    version: "1.0.0",
+    description: "Hierarchical verification runner with parallel execution",
+
+    flags: {
+      json: {
+        type: Boolean,
+        description: "Output results as JSON",
+        default: false,
       },
-    ],
-  })
-`)
-}
+      verbose: {
+        type: Boolean,
+        alias: "v",
+        description: "Show all task output",
+        default: false,
+      },
+      quiet: {
+        type: Boolean,
+        alias: "q",
+        description: "Show only final result",
+        default: false,
+      },
+      topLevel: {
+        type: Boolean,
+        alias: "t",
+        description: "Show only top-level tasks (hide descendants)",
+        default: false,
+      },
+      noTty: {
+        type: Boolean,
+        description: "Force sequential output (disable live dashboard)",
+        default: false,
+      },
+      logs: {
+        type: String,
+        description: "Log verbosity: all, failed, none (default: failed)",
+      },
+      config: {
+        type: String,
+        alias: "c",
+        description: "Path to config file (or output path for --init)",
+      },
+      filter: {
+        type: [String],
+        alias: "f",
+        description: "Filter to specific task paths",
+        default: [],
+      },
+      init: {
+        type: Boolean,
+        description: "Initialize a new verify.config.ts file",
+        default: false,
+      },
+      force: {
+        type: Boolean,
+        description: "Overwrite existing config file (with --init)",
+        default: false,
+      },
+      yes: {
+        type: Boolean,
+        alias: "y",
+        description: "Skip interactive prompts, auto-accept detected tasks",
+        default: false,
+      },
+    },
+
+    help: {
+      examples: [
+        "verify                    Run all verifications",
+        "verify logic              Run only 'logic' tasks",
+        "verify logic:ts           Run only 'logic:ts' task",
+        "verify --top-level        Show only top-level tasks",
+        "verify --json             Output JSON for CI",
+        "verify --logs=all         Show all output",
+        "verify --init             Create config interactively",
+        "verify --init -y          Create config with all detected tasks",
+        "verify --init --force     Overwrite existing config",
+      ],
+    },
+  },
+  undefined,
+  undefined,
+)
 
 async function main() {
-  const args = process.argv.slice(2)
-  const options = parseArgs(args)
-
-  if (options.help) {
-    printHelp()
-    process.exit(0)
-  }
+  const { flags, _ } = argv
 
   // Handle --init command
-  if (options.init) {
+  if (flags.init) {
     try {
       const result = await runInit({
-        config: options.config,
-        force: options.force,
-        yes: options.yes,
+        config: flags.config,
+        force: flags.force,
+        yes: flags.yes,
         cwd: process.cwd(),
       })
       process.exit(result.success ? 0 : 1)
@@ -148,22 +117,29 @@ async function main() {
     }
   }
 
+  // Combine --filter flags with positional arguments
+  const allFilters = [...flags.filter, ..._]
+
   // Build verify options
   const verifyOptions = {
-    format: options.json ? "json" : "human",
+    format: flags.json ? "json" : "human",
     logs:
-      options.logs ??
-      (options.verbose ? "all" : options.quiet ? "none" : "failed"),
-    filter: options.filter.length > 0 ? options.filter : undefined,
-    cwd: options.config,
-    topLevelOnly: options.topLevelOnly,
-    noTty: options.noTty,
+      flags.logs ?? (flags.verbose ? "all" : flags.quiet ? "none" : "failed"),
+    filter: allFilters.length > 0 ? allFilters : undefined,
+    cwd: flags.config,
+    topLevelOnly: flags.topLevel,
+    noTty: flags.noTty,
   }
 
   try {
     const result = await verifyFromConfig(process.cwd(), verifyOptions)
     process.exit(result.ok ? 0 : 1)
   } catch (error) {
+    // Handle task not found / ambiguous task errors with exit code 2
+    if (error instanceof TaskNotFoundError || error instanceof AmbiguousTaskError) {
+      console.error(`Error: ${error.message}`)
+      process.exit(2)
+    }
     if (error instanceof Error) {
       console.error(`Error: ${error.message}`)
     } else {

package/dist/index.d.ts

@@ -10,6 +10,8 @@ interface VerificationCommand {
     cwd?: string;
     /** Environment variables to set */
     env?: Record<string, string>;
+    /** Timeout in milliseconds (process killed with SIGTERM if exceeded) */
+    timeout?: number;
 }
 /**
  * Result from parsing command output
@@ -48,8 +50,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 +68,12 @@ 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;
 }
 /**
  * Options for the verification runner
@@ -140,6 +148,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 +170,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 +233,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
  */
@@ -308,6 +379,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 +425,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 +487,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 +526,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;
     /**
@@ -520,6 +620,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 +655,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 };