vitest-bats 0.0.1

package/index.d.ts

@@ -0,0 +1,655 @@
+import { Plugin } from "vitest/config";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/vitest-kcov-types.d.ts
+/**
+ * TypeScript module augmentation for Vitest coverage options.
+ *
+ * @remarks
+ * Extends Vitest's `CoverageOptions` interface to include custom `kcov` configuration.
+ * This allows `defineConfig()` to properly type-check kcov options without `@ts-expect-error`.
+ *
+ * **Usage:**
+ * ```typescript
+ * import { defineConfig } from "vitest/config";
+ * import "./lib/vitest-kcov-plugin/vitest-kcov-types.js";
+ *
+ * export default defineConfig({
+ *   test: {
+ *     coverage: {
+ *       kcov: {
+ *         enabled: true,
+ *         // ... other kcov options are now type-checked
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Log verbosity level for the kcov coverage provider.
+ *
+ * @remarks
+ * Controls the amount of output displayed during coverage collection:
+ * - `verbose`: Show all messages including debug and informational
+ * - `debug`: Show debug messages and errors
+ * - `errors-only`: Only show errors and warnings
+ * @public
+ */
+type LogLevel = "verbose" | "debug" | "errors-only";
+/**
+ * Hyperlink format for terminal output.
+ *
+ * @remarks
+ * Controls how file paths are formatted in terminal output:
+ * - `auto`: Auto-detect terminal support for HTE links (VSCode, iTerm 3.1+, WezTerm)
+ * - `default`: Plain text paths (e.g., "coverage/vitest/index.html")
+ * - `hte`: Hypertext Escape sequences (OSC 8) for clickable links in compatible terminals
+ * @public
+ */
+type LinkFormat = "auto" | "default" | "hte";
+/**
+ * Coverage thresholds for kcov shell script coverage.
+ *
+ * @remarks
+ * Defines minimum coverage percentages required for tests to pass.
+ *
+ * **Important Limitation:**
+ * Kcov does NOT actually track branch coverage for bash scripts. The `branches` field is
+ * included for format compatibility with standard coverage reports, but kcov always reports
+ * `branch-rate="1.0"` (100%) in cobertura.xml for all shell scripts, regardless of actual
+ * branch execution.
+ *
+ * **What this means:**
+ * - Line coverage: Fully supported and accurate
+ * - Branch coverage: Always shows 100% (not meaningful for bash scripts with kcov)
+ * - Branch thresholds: Will always pass since kcov reports 100%
+ *
+ * **Recommendation:**
+ * Set branch threshold to 100% to maintain format compatibility, but rely on line coverage
+ * for actual quality metrics.
+ * @public
+ */
+interface KcovThresholds {
+  /**
+   * Enforce thresholds per file instead of globally
+   *
+   * @remarks
+   * When `true` or `undefined` (default), thresholds are checked for each individual file.
+   * When `false`, thresholds are checked against overall coverage across all files.
+   *
+   * @defaultValue `true`
+   */
+  perFile?: boolean;
+  /** Minimum line coverage percentage (0-100) */
+  lines?: number;
+  /**
+   * Minimum branch coverage percentage (0-100)
+   *
+   * @remarks
+   * **Note:** Kcov always reports 100% branch coverage for bash scripts.
+   * This field exists for format compatibility but is not meaningful for shell script coverage.
+   */
+  branches?: number;
+}
+/**
+ * Configuration options for kcov coverage collection.
+ *
+ * @remarks
+ * These options control how kcov collects and reports coverage for shell scripts.
+ * All options are optional and have sensible defaults.
+ *
+ * @see {@link KcovOptions.incremental} for timestamped report directories useful for debugging
+ * @public
+ */
+interface KcovOptions {
+  /**
+   * Subdirectory within reportsDirectory for kcov output.
+   *
+   * @remarks
+   * Reports are output to a subdirectory to keep them organized and separated from other files.
+   *
+   * **Path resolution:**
+   * - The subdir is resolved relative to reportsDirectory
+   * - Can be multiple levels deep (e.g., "foo/bar")
+   *
+   * @example
+   * ```typescript
+   * // Default: subdir: "kcov"
+   * // Reports output to: coverage/kcov
+   *
+   * // Custom: subdir: "foo/bar"
+   * // Reports output to: coverage/foo/bar
+   * ```
+   *
+   * @defaultValue "kcov"
+   */
+  subdir?: string;
+  /**
+   * Directory for BATS cache files.
+   *
+   * @remarks
+   * The cache directory stores generated .bats files and kcov output directories.
+   *
+   * **Path resolution:**
+   * - Relative paths are resolved from the reports directory
+   * - Use `../` to place cache as a sibling to the reports directory
+   * - Absolute paths can be used for system-wide cache locations
+   *
+   * @example
+   * ```typescript
+   * // Default: cacheDir: "../bats-cache"
+   * // With subdir: "kcov" -> cache at: coverage/bats-cache
+   *
+   * // Custom relative path
+   * subdir: "foo/bar"
+   * cacheDir: "../bats-cache"  // Resolves to: coverage/foo/bats-cache
+   *
+   * // Absolute path
+   * cacheDir: "/tmp/bats-cache"
+   * ```
+   *
+   * @defaultValue "../bats-cache"
+   */
+  cacheDir?: string;
+  /**
+   * Whether to clean the resolved reports output directory before running tests.
+   *
+   * @remarks
+   * When true, removes the entire reports directory (reportsDirectory + subdir) before
+   * running tests to ensure a fresh start.
+   *
+   * @defaultValue true
+   */
+  clean?: boolean;
+  /**
+   * Whether to clean the resolved cache directory before running tests.
+   *
+   * @remarks
+   * When true, removes the cache directory before running tests to ensure fresh
+   * .bats files are generated and no stale kcov data exists.
+   *
+   * @defaultValue true
+   */
+  cleanCache?: boolean;
+  /**
+   * Whether to use incremental (timestamped) report directories.
+   *
+   * @remarks
+   * When true, a timestamp folder is inserted into the path one level above the final segment,
+   * allowing multiple test runs to be preserved for debugging purposes.
+   *
+   * **Path Resolution with Incremental:**
+   * - The timestamp format is `YYYY-MM-DD_HH-MM-SS` (e.g., "2025-11-12_14-30-45")
+   * - The timestamp is inserted before the last segment of the subdir path
+   * - Assumes tests won't run more than once per second
+   *
+   * @example
+   * ```typescript
+   * // Without incremental (default)
+   * subdir: "foo/bar"
+   * // Reports: coverage/foo/bar
+   *
+   * // With incremental: true (custom subdir)
+   * subdir: "foo/bar"
+   * cacheDir: "../bats-cache"
+   * incremental: true
+   * // Reports: coverage/foo/2025-11-12_14-30-45/bar
+   * // Cache: coverage/foo/2025-11-12_14-30-45/bats-cache
+   *
+   * // With incremental: true (no subdir - uses defaults)
+   * incremental: true
+   * // Reports: coverage/2025-11-12_14-30-45/kcov
+   * // Cache: coverage/2025-11-12_14-30-45/kcov-cache
+   * ```
+   *
+   * @defaultValue false
+   */
+  incremental?: boolean;
+  /**
+   * Log verbosity level: `verbose` | `debug` | `errors-only`
+   * @defaultValue `errors-only`
+   * */
+  logLevel?: LogLevel;
+  /**
+   * Hyperlink format for terminal output
+   *
+   * @remarks
+   * - `auto`: Auto-detect terminal support for HTE links (VSCode, iTerm 3.1+, WezTerm)
+   * - `default`: Plain text paths (e.g., "coverage/vitest/index.html")
+   * - `hte`: Hypertext Escape sequences (OSC 8) for clickable links in compatible terminals
+   * @defaultValue `auto`
+   * */
+  links?: LinkFormat;
+  /**
+   * Coverage thresholds for shell scripts.
+   *
+   * @remarks
+   * Unlike v8/Istanbul, kcov only tracks line coverage for shell scripts.
+   * Functions and statements thresholds are not applicable.
+   *
+   * **Important:** Kcov does NOT track branch coverage for bash scripts - it always reports
+   * 100% branch coverage. The branch threshold exists for format compatibility but will
+   * always pass. Use line coverage thresholds for actual quality enforcement.
+   *
+   * @example
+   * ```typescript
+   * kcov: {
+   *   thresholds: {
+   *     perFile: true,
+   *     lines: 90,        // Enforced - tracks actual line execution
+   *     branches: 100     // Not enforced - kcov always reports 100%
+   *   }
+   * }
+   * ```
+   */
+  thresholds?: KcovThresholds;
+  /**
+   * Optional path to custom reporter module for coverage display.
+   *
+   * @remarks
+   * Defaults to the built-in KcovReporter located alongside the provider.
+   * Only specify this if you want to use a custom reporter implementation.
+   */
+  customReporter?: string;
+}
+declare module "vitest/node" {
+  interface CustomProviderOptions {
+    /**
+     * Kcov-specific coverage options for shell script testing.
+     *
+     * @remarks
+     * Only applies when using the custom kcov coverage provider:
+     * ```typescript
+     * coverage: {
+     *   provider: "custom",
+     *   customProviderModule: "./lib/vitest-kcov-plugin/vitest-kcov-provider.ts",
+     *   kcov: {
+     *     // ... kcov options
+     *   }
+     * }
+     * ```
+     */
+    kcov?: KcovOptions;
+  }
+}
+//#endregion
+//#region src/runtime.d.ts
+/**
+ * A single recorded invocation of a mocked command, captured back to the test as
+ * part of {@link BatsResult.calls}.
+ * @public
+ */
+interface MockCall {
+  args: string[];
+}
+/**
+ * The raw fields decoded from a BATS run, wrapped by the {@link BatsResult} class.
+ * @public
+ */
+interface BatsResultData {
+  status: number;
+  output: string;
+  stderr: string;
+  calls: Record<string, MockCall[]>;
+}
+/**
+ * Symbol brand identifying a BatsResult instance. Used by matchers to
+ * detect BatsResult inputs in a way that survives:
+ * - Module-graph duplication (per-entry self-contained bundles produced as
+ *   the workaround for savvy-web/rslib-builder#158, where each entry has
+ *   its own copy of the BatsResult class — `instanceof` would fail).
+ * - Property name minification (a `constructor.name === "BatsResult"`
+ *   check would break under any minifier that renames classes).
+ *
+ * Registered with `Symbol.for(...)` so the symbol is shared across module
+ * graphs (the global symbol registry is process-wide).
+ * @internal
+ */
+declare const BATS_RESULT_BRAND: unique symbol;
+/**
+ * The value returned by `ScriptBuilder.run()`/`.exec()`. Wraps the raw exit status,
+ * stdout/stderr (whole and split into lines), and recorded mock calls; assert
+ * against it with the `expect.extend` matchers from `vitest-bats/setup`.
+ * @public
+ */
+declare class BatsResult {
+  /** @internal */
+  readonly [BATS_RESULT_BRAND] = true;
+  readonly status: number;
+  readonly output: string;
+  readonly stderr: string;
+  readonly lines: string[];
+  readonly stderr_lines: string[];
+  readonly calls: Record<string, MockCall[]>;
+  private _jsonCache;
+  constructor(data: BatsResultData);
+  json<T = unknown>(): T;
+}
+/**
+ * Resets every live `ScriptBuilder`'s `env()`/`flags()`/`mock()` configuration.
+ * Called automatically between tests by `vitest-bats/setup`'s `beforeEach` hook.
+ * @public
+ */
+declare function resetAllBuilders(): void;
+/**
+ * Test-writing API returned by a `.sh` import. Configure with `env()`/`flags()`/
+ * `mock()`, then terminate with `run(...args)` or `exec(shellExpr)` to get a
+ * {@link BatsResult}.
+ * @public
+ */
+declare class ScriptBuilder {
+  readonly path: string;
+  readonly name: string;
+  private _env;
+  private _flags;
+  private _stubs;
+  constructor(path: string, name: string);
+  env(vars: Record<string, string>): this;
+  flags(value: string): this;
+  mock(cmd: string, responses?: Record<string, string>): this;
+  run(...args: string[]): BatsResult;
+  exec(shellExpr: string): BatsResult;
+  reset(): void;
+  private execute;
+}
+//#endregion
+//#region src/bats-executor.d.ts
+/**
+ * Options for {@link executeBats}.
+ * @internal
+ */
+interface ExecuteOptions {
+  batsPath: string;
+  batsContent: string;
+  recorderDir: string;
+  timeoutMs?: number;
+}
+/**
+ * Parses the base64-encoded result payload written by the generated BATS test file.
+ * @internal
+ */
+declare function parseExecutionResult(recorderDir: string): BatsResultData;
+/**
+ * Spawns `bats` against a generated `.bats` file and parses the recorded result.
+ * @internal
+ */
+declare function executeBats(opts: ExecuteOptions): BatsResultData;
+//#endregion
+//#region src/bats-generator.d.ts
+/**
+ * Resolved paths to the `bats` binary and the `bats-support` library, detected by
+ * `BatsPlugin` and threaded through to {@link generateBatsFile}.
+ * @internal
+ */
+interface BatsDeps {
+  batsPath: string;
+  batsSupportPath: string;
+}
+/**
+ * Resolved kcov binary path and output directory for a single script run.
+ * @internal
+ */
+interface KcovConfig {
+  kcovPath: string;
+  outputDir: string;
+}
+/**
+ * A single `mock()` call's command name and pattern-to-response map, as recorded
+ * by `ScriptBuilder`.
+ * @internal
+ */
+interface StubSpec {
+  cmd: string;
+  responses: Record<string, string>;
+}
+/**
+ * Whether the generated `.bats` file invokes the script with argv (`run()`) or as a
+ * raw shell expression (`exec()`).
+ * @internal
+ */
+type RunMode = {
+  kind: "args";
+} | {
+  kind: "shell";
+  expression: string;
+};
+/**
+ * Input to {@link generateBatsFile}.
+ * @internal
+ */
+interface GenerateInput {
+  scriptPath: string;
+  args: string[];
+  env: Record<string, string>;
+  flags: string;
+  stubs: StubSpec[];
+  recorderDir: string;
+  deps: BatsDeps;
+  mode: RunMode;
+  kcov?: KcovConfig;
+}
+/**
+ * Renders a `.bats` file body for a single `ScriptBuilder` invocation: setup (deps,
+ * env, recorder, mock shims, kcov), the `run` command, and the base64 result capture.
+ * @internal
+ */
+declare function generateBatsFile(input: GenerateInput): string;
+//#endregion
+//#region src/coverage-reporter.d.ts
+/**
+ * Coverage thresholds applied to the merged v8/kcov CoverageMap.
+ * @public
+ */
+interface CoverageThresholds {
+  statements: number;
+  branches: number;
+  functions: number;
+  lines: number;
+}
+/**
+ * Vitest coverage reporter that merges kcov's shell-script coverage into the v8
+ * Istanbul CoverageMap, with synthetic branch/function entries so threshold checks
+ * pass (kcov only tracks statements/lines). Always injected by {@link BatsPlugin}
+ * when coverage is enabled.
+ * @public
+ */
+declare class BatsCoverageReporter {
+  private cacheDir;
+  private thresholds;
+  private statementPassThrough;
+  private readonly xmlParser;
+  constructor(cacheDir: string, options?: {
+    thresholds?: CoverageThresholds;
+    statementPassThrough?: boolean;
+  });
+  onInit(): void;
+  onCoverage(coverage: unknown): void;
+  private buildSyntheticCoverageEntry;
+  private gcd;
+  /** Returns the smallest total/covered pair that gives exactly threshold%. */
+  private thresholdFraction;
+  /** Pad statements to an exact multiple and mark the right fraction as covered. */
+  private applySyntheticStatements;
+  /** Create synthetic branch entries for exact threshold coverage. */
+  private applySyntheticBranches;
+  /** Create synthetic function entries for exact threshold coverage. */
+  private applySyntheticFunctions;
+  private buildZeroCoverageEntry;
+  private isExecutableLine;
+  /**
+   * Collect real coverage data from kcov cobertura.xml files.
+   * Returns a map of absolute script path to Istanbul file coverage.
+   */
+  private collectKcovCoverage;
+  private findCoberturaFiles;
+  private parseCoberturaToIstanbul;
+}
+//#endregion
+//#region src/matchers.d.ts
+/**
+ * The `{ pass, message }` shape expected by Vitest's `expect.extend`.
+ * @public
+ */
+interface MatcherResult {
+  pass: boolean;
+  message: () => string;
+}
+/**
+ * The 23 `expect.extend` matchers registered by `vitest-bats/setup` (auto-injected
+ * by {@link BatsPlugin}). Cover status, stdout/stderr, lines, mock calls, JSON
+ * values, and schema validation against a `BatsResult`.
+ * @public
+ */
+declare const batsMatchers: {
+  toSucceed(received: unknown): MatcherResult;
+  toFail(received: unknown, code?: number): MatcherResult;
+  toHaveOutput(received: unknown, text: string): MatcherResult;
+  toContainOutput(received: unknown, text: string): MatcherResult;
+  toMatchOutput(received: unknown, pattern: RegExp | string): MatcherResult;
+  toHaveEmptyOutput(received: unknown): MatcherResult;
+  toHaveStderr(received: unknown, text: string): MatcherResult;
+  toContainStderr(received: unknown, text: string): MatcherResult;
+  toMatchStderr(received: unknown, pattern: RegExp | string): MatcherResult;
+  toHaveLine(received: unknown, index: number, text: string): MatcherResult;
+  toHaveLineContaining(received: unknown, text: string, index?: number): MatcherResult;
+  toHaveLineMatching(received: unknown, pattern: RegExp | string, index?: number): MatcherResult;
+  toHaveLineCount(received: unknown, n: number): MatcherResult;
+  toOutputJson(received: unknown): MatcherResult;
+  toEqualJson(received: unknown, expected: unknown): MatcherResult;
+  toMatchJson(received: unknown, partial: object): MatcherResult;
+  toHaveJsonValue(received: unknown, path: string, expected: unknown): MatcherResult;
+  toHaveJsonPath(received: unknown, path: string): MatcherResult;
+  toMatchSchema(received: unknown, schema: unknown): MatcherResult;
+  toMatchJsonSchema(received: unknown, schema: object): MatcherResult;
+  toHaveInvoked(received: unknown, cmd: string, opts?: {
+    args?: string[];
+  }): MatcherResult;
+  toHaveInvokedTimes(received: unknown, cmd: string, n: number): MatcherResult;
+  toHaveInvokedExactly(received: unknown, cmd: string, calls: {
+    args: string[];
+  }[]): MatcherResult;
+};
+declare module "vitest" {
+  interface Assertion {
+    toSucceed(): void;
+    toFail(code?: number): void;
+    toHaveOutput(text: string): void;
+    toContainOutput(text: string): void;
+    toMatchOutput(pattern: RegExp | string): void;
+    toHaveEmptyOutput(): void;
+    toHaveStderr(text: string): void;
+    toContainStderr(text: string): void;
+    toMatchStderr(pattern: RegExp | string): void;
+    toHaveLine(index: number, text: string): void;
+    toHaveLineContaining(text: string, index?: number): void;
+    toHaveLineMatching(pattern: RegExp | string, index?: number): void;
+    toHaveLineCount(n: number): void;
+    toOutputJson(): void;
+    toEqualJson(expected: unknown): void;
+    toMatchJson(partial: object): void;
+    toHaveJsonValue(path: string, expected: unknown): void;
+    toHaveJsonPath(path: string): void;
+    toMatchSchema(schema: unknown): void;
+    toMatchJsonSchema(schema: object): void;
+    toHaveInvoked(cmd: string, opts?: {
+      args?: string[];
+    }): void;
+    toHaveInvokedTimes(cmd: string, n: number): void;
+    toHaveInvokedExactly(cmd: string, calls: {
+      args: string[];
+    }[]): void;
+  }
+  interface AsymmetricMatchersContaining {
+    toSucceed(): void;
+    toFail(code?: number): void;
+    toHaveOutput(text: string): void;
+    toContainOutput(text: string): void;
+    toMatchOutput(pattern: RegExp | string): void;
+    toHaveEmptyOutput(): void;
+    toHaveStderr(text: string): void;
+    toContainStderr(text: string): void;
+    toMatchStderr(pattern: RegExp | string): void;
+    toHaveLine(index: number, text: string): void;
+    toHaveLineContaining(text: string, index?: number): void;
+    toHaveLineMatching(pattern: RegExp | string, index?: number): void;
+    toHaveLineCount(n: number): void;
+    toOutputJson(): void;
+    toEqualJson(expected: unknown): void;
+    toMatchJson(partial: object): void;
+    toHaveJsonValue(path: string, expected: unknown): void;
+    toHaveJsonPath(path: string): void;
+    toMatchSchema(schema: unknown): void;
+    toMatchJsonSchema(schema: object): void;
+    toHaveInvoked(cmd: string, opts?: {
+      args?: string[];
+    }): void;
+    toHaveInvokedTimes(cmd: string, n: number): void;
+    toHaveInvokedExactly(cmd: string, calls: {
+      args: string[];
+    }[]): void;
+  }
+}
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Options for {@link BatsPlugin}.
+ * @public
+ */
+interface BatsPluginOptions {
+  /**
+   * Shell script coverage mode. Default: "auto"
+   * - "auto": include .sh in coverage when kcov is available, exclude when not
+   * - true: require kcov, throw if unavailable, include .sh in coverage
+   * - false: always exclude .sh from coverage
+   */
+  coverage?: "auto" | boolean;
+  /**
+   * How to handle missing system dependencies (bats, kcov, jq, etc.).
+   * Default: "error"
+   * - "error": throw on missing required deps, blocking all tests
+   * - "warn": log warnings but continue; BATS integration tests will
+   *   fail individually at runtime, pure TS unit tests run normally
+   */
+  deps?: "error" | "warn";
+  /** Log level for detection output. Default: "errors-only" */
+  logLevel?: LogLevel;
+  /** Hyperlink format for reporter. Default: "auto" */
+  links?: LinkFormat;
+}
+/**
+ * Vitest plugin that wires up `.sh` imports, dependency detection, coverage
+ * option handling, matcher setup-file injection, and coverage reporter injection.
+ * @public
+ */
+declare function BatsPlugin(options?: BatsPluginOptions): Plugin;
+//#endregion
+//#region src/schema.d.ts
+/**
+ * Result of {@link validate}: either success, or failure with human-readable issue
+ * strings, used internally by the `toMatchSchema`/`toMatchJsonSchema` matchers.
+ * @internal
+ */
+type ValidationResult = {
+  ok: true;
+} | {
+  ok: false;
+  issues: string[];
+};
+/**
+ * Detects whether `schema` implements the Standard Schema (`~standard`) interface,
+ * used by the `toMatchSchema` matcher to route to Standard Schema vs. JSON Schema
+ * validation.
+ * @internal
+ */
+declare function isStandardSchema(schema: unknown): schema is StandardSchemaV1;
+/**
+ * Validates `value` against a Standard Schema validator or a raw JSON Schema
+ * object, backing the `toMatchSchema`/`toMatchJsonSchema` matchers.
+ * @internal
+ */
+declare function validate(schema: unknown, value: unknown): ValidationResult;
+//#endregion
+export { BatsCoverageReporter, type BatsDeps, BatsPlugin, type BatsPluginOptions, BatsResult, type BatsResultData, type CoverageThresholds, type ExecuteOptions, type GenerateInput, type KcovConfig, type KcovOptions, type KcovThresholds, type LinkFormat, type LogLevel, type MatcherResult, type MockCall, type RunMode, ScriptBuilder, type StubSpec, type ValidationResult, batsMatchers, executeBats, generateBatsFile, isStandardSchema, parseExecutionResult, resetAllBuilders, validate };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,9 @@
+import { executeBats, parseExecutionResult } from "./bats-executor.js";
+import { generateBatsFile } from "./bats-generator.js";
+import { BatsCoverageReporter } from "./coverage-reporter.js";
+import { BatsResult, ScriptBuilder, resetAllBuilders } from "./runtime.js";
+import { isStandardSchema, validate } from "./schema.js";
+import { batsMatchers } from "./matchers.js";
+import { BatsPlugin } from "./plugin.js";
+
+export { BatsCoverageReporter, BatsPlugin, BatsResult, ScriptBuilder, batsMatchers, executeBats, generateBatsFile, isStandardSchema, parseExecutionResult, resetAllBuilders, validate };