@blzsky/variant 0.2.1 → 0.3.0-canary.1

package/dist/vitest.d.cts

@@ -0,0 +1,181 @@
+import { Reporter } from 'vitest/node';
+
+/**
+ * @module
+ * Shadow-mode prediction log (the seed of a shared build history). Every
+ * `variant impact` run appends its prediction to
+ * `.variant/history/impact.jsonl` so prediction-vs-reality can be measured
+ * before test skipping is ever enabled — the measured false-skip rate, not an
+ * asserted number, is what earns the right to skip.
+ *
+ * Logging is best-effort by design: a history write failure must never fail
+ * the command, so these functions return booleans / empty lists instead of
+ * throwing.
+ */
+interface ImpactPrediction {
+    /** ISO timestamp of the prediction. */
+    at: string;
+    baseRef: string;
+    /**
+     * The commit the prediction was made against. This is what lets a
+     * prediction be matched to the test run that actually happened — without
+     * it the log records what variant thought, with nothing to check it
+     * against. Null when the working tree is not a git repository.
+     */
+    headSha: string | null;
+    changedFiles: string[];
+    affectedFiles: number;
+    affectedPackages: string[];
+    /** The predicted run set — reality reconciliation diffs failures against it. */
+    affectedTests: string[];
+    totalTests: number;
+    selectAll: boolean;
+    verdict: string;
+    confidence: number;
+    notes: string[];
+}
+
+/**
+ * @module
+ * `variant impact verify` — the other half of shadow mode. `predict.ts` records
+ * what variant thought; this reads what actually happened and diffs the two.
+ *
+ * A failing test the prediction did not select is a **false skip**: had
+ * skipping been enabled, that failure would have been missed. That number, over
+ * many runs, is the only thing that can earn the right to skip. Everything else
+ * `impact` prints is a description of a graph.
+ */
+
+interface VerifyResult {
+    prediction: ImpactPrediction;
+    /** How the prediction was located — reported so a mismatch is visible. */
+    matchedBy: "head-sha" | "most-recent";
+    /** Test files the runner reported as failing, workspace-relative POSIX. */
+    failedTests: string[];
+    /** Failures the prediction selected. Skipping would not have missed these. */
+    caught: string[];
+    /** Failures the prediction did NOT select. Skipping would have missed these. */
+    falseSkips: string[];
+    /**
+     * `falseSkips / failedTests`. Zero when the run had no failures — a clean
+     * run is evidence of nothing, which is why the count matters more than the
+     * rate until many runs accumulate.
+     */
+    falseSkipRate: number;
+    /**
+     * Test files the runner reported, and how many of them the prediction
+     * selected. The share a prediction would skip is measured against these:
+     * its own `totalTests` counts every file that looks like a test, including
+     * helpers and suites this run never ran.
+     */
+    ranTests: number;
+    predictedRan: number;
+    /** False when the reconciliation could not be persisted. */
+    historyLogged: boolean;
+}
+
+/**
+ * @module
+ * The shared vocabulary `pr check` and `impact` report their conclusions in.
+ * Both walk a set of classified file changes and reduce it to one
+ * recommendation, and they must agree — a change that is "build required" for
+ * one command cannot be "safe to skip" for the other.
+ */
+
+type Resolution = "high" | "medium" | "low";
+
+/**
+ * @module
+ * What every runner adapter shares: start a prediction as the run starts,
+ * reconcile it as the run ends, say one line, record. Nothing here knows a
+ * runner's types.
+ *
+ * This runs inside someone else's test process, so its rules are not the
+ * CLI's. It never throws and never sets an exit code: a failure in variant
+ * must not fail a suite. The prediction runs in a child process, so ts-morph
+ * never loads beside the tests and a hang there cannot hold them up. And it
+ * runs alongside the tests, not before them: nothing is skipped, so the tests
+ * do not depend on it.
+ */
+
+interface ShadowOptions {
+    /**
+     * Run outside CI too. By default the adapter is on only when `CI` is set
+     * (or `VARIANT_SHADOW=1`): a local run is often one file, which makes a
+     * poor reconciliation and a line of output nobody asked for.
+     */
+    local?: boolean;
+    /** Record without printing. */
+    silent?: boolean;
+    /** How long to wait for the prediction once the tests have ended. */
+    timeoutMs?: number;
+}
+/** One test file's outcome, as the runner reported it. */
+interface FileResult {
+    file: string;
+    failed: boolean;
+}
+/** The parts of `impact --json` the adapter reads. */
+interface PredictionSummary {
+    resolution: Resolution;
+    selectAll: boolean;
+    unreached: number;
+    unselectedTests: number;
+}
+type PredictionOutcome = {
+    kind: "predicted";
+    summary: PredictionSummary;
+}
+/** Nothing to compare against: not a failure, and not a prediction. */
+ | {
+    kind: "none";
+    reason: string;
+} | {
+    kind: "failed";
+    reason: string;
+};
+interface PredictionHandle {
+    result: Promise<PredictionOutcome>;
+    cancel: () => void;
+}
+/** Everything with an effect, so the flow can be tested without processes. */
+interface ShadowDeps {
+    env: Readonly<Record<string, string | undefined>>;
+    now: () => number;
+    repositoryRoot: (cwd: string) => Promise<string>;
+    headSha: (root: string) => Promise<string | null>;
+    predict: (root: string, headSha: string) => PredictionHandle;
+    reconcile: (root: string, results: readonly FileResult[], headSha: string) => Promise<VerifyResult | null>;
+    write: (line: string) => void;
+    appendSummary: (file: string, text: string) => Promise<void>;
+}
+
+/**
+ * @module
+ * The Vitest adapter. It translates Vitest's reporter hooks into a shadow run
+ * and holds no logic of its own; see `shadow.ts`.
+ *
+ * ```ts
+ * import variant from "@blzsky/variant/vitest";
+ * export default defineConfig({ test: { reporters: ["default", variant()] } });
+ * ```
+ *
+ * or, in a config that sets no reporters of its own:
+ *
+ * ```ts
+ * import { variantReporters } from "@blzsky/variant/vitest";
+ * export default defineConfig({ test: { reporters: variantReporters() } });
+ * ```
+ */
+
+type VariantReporterOptions = ShadowOptions;
+declare function variantReporter(options?: VariantReporterOptions, deps?: ShadowDeps): Reporter;
+/**
+ * Vitest's own default reporters with the adapter after them, for a config
+ * that names none. Setting `reporters` replaces the defaults, and one of
+ * them exists only on GitHub Actions: writing `["default", variant()]` into
+ * such a config would quietly take the annotations off every pull request.
+ */
+declare function variantReporters(options?: VariantReporterOptions): Array<string | Reporter>;
+
+export { type VariantReporterOptions, variantReporter as default, variantReporter, variantReporters };

package/dist/vitest.d.ts

@@ -0,0 +1,181 @@
+import { Reporter } from 'vitest/node';
+
+/**
+ * @module
+ * Shadow-mode prediction log (the seed of a shared build history). Every
+ * `variant impact` run appends its prediction to
+ * `.variant/history/impact.jsonl` so prediction-vs-reality can be measured
+ * before test skipping is ever enabled — the measured false-skip rate, not an
+ * asserted number, is what earns the right to skip.
+ *
+ * Logging is best-effort by design: a history write failure must never fail
+ * the command, so these functions return booleans / empty lists instead of
+ * throwing.
+ */
+interface ImpactPrediction {
+    /** ISO timestamp of the prediction. */
+    at: string;
+    baseRef: string;
+    /**
+     * The commit the prediction was made against. This is what lets a
+     * prediction be matched to the test run that actually happened — without
+     * it the log records what variant thought, with nothing to check it
+     * against. Null when the working tree is not a git repository.
+     */
+    headSha: string | null;
+    changedFiles: string[];
+    affectedFiles: number;
+    affectedPackages: string[];
+    /** The predicted run set — reality reconciliation diffs failures against it. */
+    affectedTests: string[];
+    totalTests: number;
+    selectAll: boolean;
+    verdict: string;
+    confidence: number;
+    notes: string[];
+}
+
+/**
+ * @module
+ * `variant impact verify` — the other half of shadow mode. `predict.ts` records
+ * what variant thought; this reads what actually happened and diffs the two.
+ *
+ * A failing test the prediction did not select is a **false skip**: had
+ * skipping been enabled, that failure would have been missed. That number, over
+ * many runs, is the only thing that can earn the right to skip. Everything else
+ * `impact` prints is a description of a graph.
+ */
+
+interface VerifyResult {
+    prediction: ImpactPrediction;
+    /** How the prediction was located — reported so a mismatch is visible. */
+    matchedBy: "head-sha" | "most-recent";
+    /** Test files the runner reported as failing, workspace-relative POSIX. */
+    failedTests: string[];
+    /** Failures the prediction selected. Skipping would not have missed these. */
+    caught: string[];
+    /** Failures the prediction did NOT select. Skipping would have missed these. */
+    falseSkips: string[];
+    /**
+     * `falseSkips / failedTests`. Zero when the run had no failures — a clean
+     * run is evidence of nothing, which is why the count matters more than the
+     * rate until many runs accumulate.
+     */
+    falseSkipRate: number;
+    /**
+     * Test files the runner reported, and how many of them the prediction
+     * selected. The share a prediction would skip is measured against these:
+     * its own `totalTests` counts every file that looks like a test, including
+     * helpers and suites this run never ran.
+     */
+    ranTests: number;
+    predictedRan: number;
+    /** False when the reconciliation could not be persisted. */
+    historyLogged: boolean;
+}
+
+/**
+ * @module
+ * The shared vocabulary `pr check` and `impact` report their conclusions in.
+ * Both walk a set of classified file changes and reduce it to one
+ * recommendation, and they must agree — a change that is "build required" for
+ * one command cannot be "safe to skip" for the other.
+ */
+
+type Resolution = "high" | "medium" | "low";
+
+/**
+ * @module
+ * What every runner adapter shares: start a prediction as the run starts,
+ * reconcile it as the run ends, say one line, record. Nothing here knows a
+ * runner's types.
+ *
+ * This runs inside someone else's test process, so its rules are not the
+ * CLI's. It never throws and never sets an exit code: a failure in variant
+ * must not fail a suite. The prediction runs in a child process, so ts-morph
+ * never loads beside the tests and a hang there cannot hold them up. And it
+ * runs alongside the tests, not before them: nothing is skipped, so the tests
+ * do not depend on it.
+ */
+
+interface ShadowOptions {
+    /**
+     * Run outside CI too. By default the adapter is on only when `CI` is set
+     * (or `VARIANT_SHADOW=1`): a local run is often one file, which makes a
+     * poor reconciliation and a line of output nobody asked for.
+     */
+    local?: boolean;
+    /** Record without printing. */
+    silent?: boolean;
+    /** How long to wait for the prediction once the tests have ended. */
+    timeoutMs?: number;
+}
+/** One test file's outcome, as the runner reported it. */
+interface FileResult {
+    file: string;
+    failed: boolean;
+}
+/** The parts of `impact --json` the adapter reads. */
+interface PredictionSummary {
+    resolution: Resolution;
+    selectAll: boolean;
+    unreached: number;
+    unselectedTests: number;
+}
+type PredictionOutcome = {
+    kind: "predicted";
+    summary: PredictionSummary;
+}
+/** Nothing to compare against: not a failure, and not a prediction. */
+ | {
+    kind: "none";
+    reason: string;
+} | {
+    kind: "failed";
+    reason: string;
+};
+interface PredictionHandle {
+    result: Promise<PredictionOutcome>;
+    cancel: () => void;
+}
+/** Everything with an effect, so the flow can be tested without processes. */
+interface ShadowDeps {
+    env: Readonly<Record<string, string | undefined>>;
+    now: () => number;
+    repositoryRoot: (cwd: string) => Promise<string>;
+    headSha: (root: string) => Promise<string | null>;
+    predict: (root: string, headSha: string) => PredictionHandle;
+    reconcile: (root: string, results: readonly FileResult[], headSha: string) => Promise<VerifyResult | null>;
+    write: (line: string) => void;
+    appendSummary: (file: string, text: string) => Promise<void>;
+}
+
+/**
+ * @module
+ * The Vitest adapter. It translates Vitest's reporter hooks into a shadow run
+ * and holds no logic of its own; see `shadow.ts`.
+ *
+ * ```ts
+ * import variant from "@blzsky/variant/vitest";
+ * export default defineConfig({ test: { reporters: ["default", variant()] } });
+ * ```
+ *
+ * or, in a config that sets no reporters of its own:
+ *
+ * ```ts
+ * import { variantReporters } from "@blzsky/variant/vitest";
+ * export default defineConfig({ test: { reporters: variantReporters() } });
+ * ```
+ */
+
+type VariantReporterOptions = ShadowOptions;
+declare function variantReporter(options?: VariantReporterOptions, deps?: ShadowDeps): Reporter;
+/**
+ * Vitest's own default reporters with the adapter after them, for a config
+ * that names none. Setting `reporters` replaces the defaults, and one of
+ * them exists only on GitHub Actions: writing `["default", variant()]` into
+ * such a config would quietly take the annotations off every pull request.
+ */
+declare function variantReporters(options?: VariantReporterOptions): Array<string | Reporter>;
+
+export { type VariantReporterOptions, variantReporter as default, variantReporter, variantReporters };