@useblacksmith/vitest 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blacksmith Software, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @useblacksmith/vitest
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Speed up vitest execution by only running tests impacted by a change, with automatic caching when run on Blacksmith.
+
+> **Alpha.** The plugin is under active development; options and the cache format may change between releases.
+
+## Usage
+
+```sh
+npm install --save-dev @useblacksmith/vitest
+```
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import blacksmith from '@useblacksmith/vitest'
+
+export default defineConfig({
+	plugins: [blacksmith()],
+})
+```
+
+With the plugin, vitest only runs tests impacted by changes since the last successful run. `--shard=i/n` works as usual; the plugin assigns files to shards itself so each shard's cache stays stable.
+
+Requires Vitest 5.1 or newer.
+
+## Running locally
+
+The same selection applies locally: a run reruns what changed on disk since the last successful run, committed or not. To run every test locally and select only in CI:
+
+```ts
+plugins: [blacksmith({ runAllTests: !process.env.CI })],
+```
+
+## How it works
+
+The plugin uses Vitest's dependency tracking: each run records which modules and files every test depends on, and the next run compares the checkout against that record to calculate the impacted test set; a test the last successful run did not cover always runs. The record is stored in the Actions cache when run on Blacksmith, so runs on different runners pick up where the last successful run left off.
+
+## Options
+
+| option | default | effect |
+|---|---|---|
+| `runAllTests` | `false` | Run every test instead of the affected selection. |
+| `shadow` | `false` | Run every test, but log what the affected selection would have run and which failing test files it would have skipped, i.e. failures the selection would have missed. Use it to evaluate the plugin on a repo before relying on the selection. |
+| `dependencies` | `{}` | Dependencies the tracking cannot see, as globs of test files mapped to the glob(s) of the files they depend on, relative to the config root: `{ 'tests/**/*.spec.ts': 'fixtures/**' }`. A change to a matching file reruns the mapped tests. |
+
+## Caveats
+
+- **Only dependencies in the test process are tracked.** `import`, `require`, and `fs` are automatically tracked. Files read from a child process, `globalSetup`, or outside of node are not; declare them with the `dependencies` option.
+- **Shards must be stable for maximal efficacy.** The plugin assigns test files to shards by a hash of their path, so a file stays in its shard as others are added or removed. A custom `test.sequence.sequencer` is honoured, but every test that moves to another shard reruns there.
+
+## Development
+
+```sh
+npm ci
+npm run check:types
+npm run build          # dist/ (not committed; built on publish)
+npm test               # runs the fixtures under test/ with a fake backend
+```

package/dist/affected.d.ts

@@ -0,0 +1,124 @@
+import { BloomFilter } from './bloom.js';
+import type { Reporter, TestModule, TestRunEndReason, TestSpecification, VCSProvider, VCSProviderOptions, Vitest } from 'vitest/node';
+import { type Tree } from './git.js';
+export declare const SNAPSHOT_FILE = "blacksmith.json";
+declare const SNAPSHOT_VERSION = 4;
+/** A `dependencies` entry, compiled: test files matching `tests` depend on files matching `deps`; both root-relative. */
+export interface DependencyRule {
+    tests: (file: string) => boolean;
+    deps: (file: string) => boolean;
+}
+export declare function compileDependencies(dependencies: Readonly<Record<string, string | readonly string[]>> | undefined): DependencyRule[];
+export interface Shard {
+    index: number;
+    count: number;
+}
+/**
+ * Written beside vitest's `dependencies.json` after a run that covered every
+ * test the shard owns; `tree` anchors every path the dependency records name.
+ */
+export interface Snapshot {
+    version: typeof SNAPSHOT_VERSION;
+    head: string;
+    shard: Shard | null;
+    /** Names of the projects the run covered (`--project` narrows them). */
+    projects: string[];
+    tree: Tree;
+    /** Repo-relative test files the run covered: ran, or deselected by our provider as unchanged. A test outside this set reruns whatever its record says. */
+    tests: BloomFilter;
+}
+/**
+ * `blacksmith.json`, or `blacksmith.<hash>.json` when `--project` narrowed the
+ * run: invocations covering different project sets keep separate anchors.
+ */
+export declare function snapshotPath(vitest: Vitest, dir: string): string;
+/**
+ * Decides which files changed since the snapshot was written by diffing the
+ * stored anchor against the recorded paths as they are now. Falls back
+ * to "everything" whenever the snapshot cannot vouch for this shard.
+ */
+declare const PROVIDER_BRAND: unique symbol;
+/** True for a `TreeSnapshotProvider` from any copy of this module (a project with its own root re-evaluates the config file, so it gets its own copy). */
+export declare function isTreeSnapshotProvider(value: unknown): value is TreeSnapshotProvider;
+/** The provider vitest loaded: the root config's `experimental.vcsProvider`, when it is ours. */
+export declare function configuredProvider(vitest: Vitest): TreeSnapshotProvider | null;
+export declare class TreeSnapshotProvider implements VCSProvider {
+    readonly [PROVIDER_BRAND] = true;
+    vitest: Vitest;
+    /**
+     * Recorded test files none of whose recorded imports changed: the provider
+     * vouches that they need not run, whatever filters the run also applies.
+     */
+    deselected: Set<string>;
+    /** The plugin's `dependencies` option, compiled. */
+    dependencies: DependencyRule[];
+    findChangedFiles(options: VCSProviderOptions): Promise<string[]>;
+    /**
+     * Changed files to hand vitest, or `null` when every test of the shard has
+     * to run; `dir` is where the record and anchor live (vitest's `cacheDir`,
+     * or a shadow run's copy of it).
+     */
+    select({ root }: Pick<VCSProviderOptions, 'root'>, dependencies: ReadonlyArray<{
+        file: string;
+        recordedAt?: number | undefined;
+    }>, dir: string, log: (message: string) => void): Promise<string[] | null>;
+}
+export interface ShadowResult {
+    /** Test files (absolute) the affected selection would have run, `'all'` when it would have run everything, `null` when there was nothing to compare against. */
+    wouldRun: Set<string> | 'all' | null;
+    changed: number;
+    head: string | null;
+    key: string | null;
+    /** Why there is nothing to compare, or why everything would have run. */
+    reason: string | null;
+}
+/**
+ * Shadow mode: fetches the shard's last record and anchor into a temporary
+ * directory while the full run executes, and works out what the affected
+ * selection would have run, without touching vitest's `cacheDir` or the run.
+ */
+export declare class ShadowAnalysis {
+    private readonly vitest;
+    private readonly dependencies;
+    readonly result: Promise<ShadowResult>;
+    constructor(vitest: Vitest, dependencies: DependencyRule[]);
+    private run;
+}
+/**
+ * Writes the snapshot once a passing run has covered every test the shard owns,
+ * so the next `--changed` run can trust the dependency records for all of them.
+ */
+declare const RECORDER_BRAND: unique symbol;
+/** True for a `SnapshotRecorder` from any copy of this module (a project's config bundles its own). */
+export declare function isSnapshotRecorder(reporter: unknown): boolean;
+export declare class SnapshotRecorder implements Reporter {
+    private readonly provider;
+    private readonly options;
+    readonly [RECORDER_BRAND] = true;
+    private vitest;
+    private started;
+    private partial;
+    constructor(provider: TreeSnapshotProvider, options?: {
+        shadow?: ShadowAnalysis | undefined;
+    });
+    /** Shadow mode's verdict for this run, logged once the run has finished. */
+    private reportShadow;
+    /** The provider vitest is using: the root config's, which may come from another copy of this module. */
+    private activeProvider;
+    onInit(vitest: Vitest): void;
+    onTestRunStart(specifications: ReadonlyArray<TestSpecification>): void;
+    onTestRunEnd(modules: ReadonlyArray<TestModule>, _errors: ReadonlyArray<unknown>, reason: TestRunEndReason): Promise<void>;
+    /** Puts the record and this anchor in the Actions cache when a run can reach it. */
+    private publish;
+    /** The tests this shard owns, when every one of them ran or was deselected by our own provider; `null` when the run covered less. */
+    private coveredTests;
+}
+/**
+ * Before selection: when the Actions cache is reachable and Vitest's cache
+ * directory (`cacheDir`, wherever the config puts it) holds no record yet,
+ * pulls the newest record for this shard and project set into it. The
+ * directory itself may exist: every `vitest run` on one config shares it
+ * (its hash is the root `test.name`, not the `--project` filter).
+ */
+export declare function restoreDependencyCache(vitest: Vitest): Promise<void>;
+export {};