@blzsky/variant 0.2.0 → 0.2.1

package/README.md

@@ -1,176 +1,227 @@
-# variant
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./public/new-dark-mode.png">
+    <source media="(prefers-color-scheme: light)" srcset="./public/new-light-mode.png">
+    <img alt="variant: know what changed. know what matters." src="./public/new-light-mode.png" width="560">
+  </picture>
+</p>
+
+## What is variant?
+
+variant tells you which tests a change in a TypeScript monorepo actually needs.
+It reads the diff at the level of the syntax tree, not the line, classifies
+each changed file by what it does to the file's exported surface, and follows
+every test file's imports across workspace packages to see which ones reach the
+change.
 
-[![npm version](https://img.shields.io/npm/v/@blzsky/variant.svg)](https://www.npmjs.com/package/@blzsky/variant)
-[![CI](https://github.com/saintparish4/variant/actions/workflows/ci.yml/badge.svg)](https://github.com/saintparish4/variant/actions/workflows/ci.yml)
-
-Change intelligence for TypeScript monorepos. variant reads a diff at the AST level and answers one question: **which tests does this change actually need, and how sure are we?**
-
-```console
-$ npx @blzsky/variant impact --base HEAD~1
-
-Base ref: HEAD~1
-
-You changed 1 file.
-  internal       src/math.ts
-
-Impact: 1 file
-
-Run:   1 test file
-Skip:  1 test file (of 2 total)
-
-Verdict:    build recommended
-Confidence: 100%  (report-only — run the full suite; skipping unlocks after shadow-mode validation)
+```bash
+npx @blzsky/variant impact --base origin/main
 ```
 
-`internal` means the exported signature did not change — only the body — so a dependent that never imports the changed names is not selected. That distinction is the point: test runners and build orchestrators decide "affected" from the file or package graph; variant decides it from the exported surface.
-
-No config file is required. Published to npm as **`@blzsky/variant`**; the command it installs is **`variant`**.
-
-**`impact` is report-only and stays that way until it is measured.** Every prediction is appended to `.variant/history/impact.jsonl` so a false-skip rate can be reconciled against real test results. The printed confidence is a graph-resolution score, not a safety number. Until that rate is published, run the full suite.
-
-A cached task DAG (`build`, `run`, `insight`) sits underneath, and dogfoods the repo.
-
-The rest of this README is for working **on** variant. Using it in your own project is documented in [docs/](./docs/getting-started.md).
+<p align="center">
+  <img alt="Running `variant impact --base main` after changing formatPrice's signature and documenting slugify: price.ts is breaking, slug.ts is non-impacting, 2 of 4 test files run" src="./docs/assets/impact.gif" width="840">
+</p>
 
----
+In that repository, `shop` and `blog` both depend on `utils`. A tool that works
+from the package graph would run all four test files. variant follows the
+imports: only `shop` reaches the changed `price.ts`, and a doc comment on
+`slug.ts` selects nothing.
 
-## Requirements
+It does not skip anything. Every prediction is logged, and
+`variant impact verify` checks it against the test run you did anyway,
+counting each failure the prediction would have missed. That count, the
+false-skip rate, is what has to be measured before skipping is worth turning
+on, and it is the point of the project right now.
 
-| | Version | Notes |
-|---|---|---|
-| Node | ≥ 20 | Enforced via `engines`; CI tests 20, 22, and 24 |
-| pnpm | ≥ 10 | Pinned by `packageManager` |
-| git | any recent | Needed to exercise `--affected`, `diff`, `impact`, and `pr *` — they no-op without a repo |
+The same analysis powers `pr check`, which rolls a branch's changes into one
+build verdict for a pull request comment, and `workspace check`, which fails CI
+when a package imports something it never declared.
 
-Optional: **[hyperfine](https://github.com/sharkdp/hyperfine)**, required by `pnpm bench`.
+> **Status**: `0.x`, report-only. `impact`, `impact verify`, `diff`,
+> `pr check`, `pr report` and `workspace check` work today and are where
+> development happens. Test skipping is **not implemented**, deliberately, and
+> will not be until the false-skip rate is measured on real repositories; see
+> [Help measure it](#help-measure-it). The task runner underneath (`build`,
+> `run`, `insight`) works but is frozen. Any minor release can break, and every
+> break is in the [CHANGELOG](./CHANGELOG.md).
 
----
+## Install
 
-## Installation
+variant needs Node 20 or newer and a git repository with at least one commit
+before the one you are checking. There is nothing to configure.
 
 ```bash
-git clone https://github.com/saintparish4/variant.git
-cd variant
-pnpm install
-pnpm build               # required before the CLI or E2E tests can run
-node dist/cli.js --help  # smoke test
-```
-
----
-
-## Development
+# run it once
+npx @blzsky/variant impact --base origin/main
 
-```bash
-pnpm build             # compile all three entry points to dist/ via tsup
-pnpm clean             # delete dist/
-pnpm format            # biome format --write .
-pnpm format:check      # biome format (read-only)
-pnpm lint              # biome check . (static analysis, read-only)
-pnpm typecheck         # tsc --noEmit
-pnpm check             # biome check --write — local autofix (format + lint + organize imports)
-pnpm bench             # benchmark harness (pnpm bench:quick for a fast pass)
+# keep it in a project
+npm install -D @blzsky/variant    # or pnpm add -D / yarn add -D
 ```
 
-The default branch is `master`, and it is expected to be lint-clean — if `pnpm format:check`, `pnpm lint`, or `pnpm typecheck` is red, your change caused it.
-
-There is no watch build. The loop is `pnpm build && node dist/cli.js <command>`, run against a scratch project or one of the fixture workspaces in `src/__tests__/fixtures/`.
-
-`src/cli/index.ts` registers every command with a dynamic `import()` inside its `action()` callback, deferring execa, jiti, and fast-glob until a command actually runs. That is what keeps `variant --help` fast, and it is the one sanctioned exception to the project's prefer-top-level-imports rule — the benchmark job fails if startup regresses past 200 ms.
+The package is `@blzsky/variant`; the binary it installs is `variant`.
+`npx variant` fetches an unrelated package, so always use the scope with `npx`.
 
-Benchmark methodology and how to reproduce the published numbers: [benchmarks/README.md](./benchmarks/README.md).
-
----
-
-## Testing
-
-Three tiers, each answering a different question. Write a test at the cheapest tier that can answer yours.
-
-| Tier | Tests | Lives in | Runs against |
-|------|-------|----------|--------------|
-| Unit | Isolated behavior — one module, collaborators substituted | `src/**/__tests__/*.test.ts` | Source |
-| Integration | Boundaries — real modules meeting, or a real edge (filesystem, git, config) | `src/__tests__/integration/` | Source |
-| E2E | User workflows through the shipped binary | `src/__tests__/e2e/` | Built `dist/` |
+### Upgrade
 
 ```bash
-pnpm test              # watch mode
-pnpm test:run          # every tier, once
-pnpm test:integration  # boundaries only
-pnpm test:e2e          # workflows only — run pnpm build first
-pnpm test:all          # everything + coverage
-pnpm vitest run src/core/graph/__tests__/dag.test.ts   # a single file
+npm install -D @blzsky/variant@latest
 ```
 
-Unit tests never shell out — `runTasksWithDeps` takes a `TaskExecutor`, so tests inject a mock. Fixture workspaces are shared across tiers at `src/__tests__/fixtures/`. Coverage gates in CI: 70% lines/statements/functions, 60% branches.
-
----
+Because variant is `0.x`, pin a version in CI (`npx --yes @blzsky/variant@0.2.1`)
+and read the CHANGELOG before moving to a new minor version.
 
-## Environment Variables
-
-variant takes no configuration from the environment — that lives in `variant.config.ts`. What it reads are standard terminal and CI signals:
-
-| Variable | Read by | Effect |
-|---|---|---|
-| `NO_COLOR` | `visuals/color.ts` | Disables color everywhere. Highest-priority env signal. |
-| `FORCE_COLOR` | `visuals/color.ts` | Forces color on when output is not a TTY. |
-| `CLICOLOR_FORCE` | `visuals/color.ts` | Same as `FORCE_COLOR`. |
-| `CI` | picocolors, indirectly | Nothing in `src/` reads `CI`. picocolors counts it as color *support*, so CI logs keep color unless `NO_COLOR` is set. Animated progress stops in CI because stderr is not a TTY (`printer.ts:82`), not because of this variable. |
-| `JPY_SESSION_NAME` | `visuals/progress.ts` | Detects a Jupyter session and falls back to line-based output. |
-| `VARIANT_TEST_NO_CLI_PROGRESS` | `visuals/printer.ts`, `visuals/progress.ts` | Test-only. Suppresses progress bars so concurrent output stays assertable. |
-
-Color precedence: `--color <when>` → `--no-color` → `NO_COLOR` → `FORCE_COLOR`/`CLICOLOR_FORCE` → TTY detection. All of it resolves once in `visuals/color.ts:resolveColorChoice()`, applied process-wide by `writeGlobalColorChoice()`; renderers call `getColors()` and never consult the environment themselves. Adding a second color path is the mistake this design exists to prevent.
-
----
-
-## Architecture
-
-Layered, dependencies pointing one way: `cli → core → adapters`. Ports are owned by `core`; adapters implement them and import nothing from `core` except types.
-
-| Directory | Role |
-|---|---|
-| `src/cli/` | Commander wiring, option parsing, terminal rendering |
-| `src/core/` | Orchestration logic, grouped by capability — `semantic`, `impact`, `pr`, `cache`, `graph`, `execution`, `detection`, `plugins` |
-| `src/adapters/` | The outside world — package managers, runtimes, frameworks |
-| `src/types/` | Contracts shared across layers |
-
-`tsup` builds two entry points: `dist/index.js` (library API) and `dist/cli.js` (the `variant` binary).
-
-The request path for most commands: `cli/context.ts:createContext()` loads config, detects PM/runtime/framework, builds the task DAG, and computes git-diff scoping — then `core/execution:runTasksWithDeps()` walks DAG levels while `core/cache` hashes inputs against `.variant/cache/cache.json`.
-
-Along the way `core/provenance` records why each task was selected to run — cache miss, affected by the diff, or never cached. The runner attaches that record to the `VariantError` a failing task throws, and `cli/render/error.ts` prints it under the failure. It explains *selection*, never *cause*; see [docs/troubleshooting.md](./docs/troubleshooting.md) for the output and that distinction.
-
-Two rules to know before your first PR: business logic does not live in command handlers, and `core` never prints or exits — it throws `VariantError` subclasses and lets the CLI top level map them to exit codes (`VariantError` → 1, unexpected → 2). Full detail in [CLAUDE.md](./CLAUDE.md).
-
-Note the naming: `core/progress/reporter.ts` is a *port* — a bare `TaskEvent` interface with no output code. Everything that actually draws lives in `cli/visuals/` (progress, spinners, task events) and `cli/render/` (command output, errors). A file under `core/` never prints, whatever its name suggests.
-
----
-
-## Deployment
-
-variant ships as an npm package; there is no server to deploy.
+## Usage
 
 ```bash
-pnpm publish            # prepublishOnly runs `pnpm test:all && pnpm build`
+variant impact --base origin/main          # which tests does this branch need?
+npx vitest run --reporter=json --outputFile=report.json
+variant impact verify report.json          # did the prediction miss a failure?
+variant pr check --base origin/main        # one build verdict for the branch
+variant workspace check                    # undeclared dependencies (exits 1)
 ```
 
-Only `dist/` is published (`files: ["dist"]`). The package exposes `.` through the `exports` map, ESM-only (`"type": "module"`).
-
-Releases are **manual**; the only workflows in the repository are `ci.yml` and `benchmark.yml`. Before publishing: bump the version, update [CHANGELOG.md](./CHANGELOG.md), and confirm CI is green on `master`.
-
-The package is `0.x` and makes no semver stability promise yet. Breaking changes to the `@blzsky/variant` public API can ship in any minor release; each one is recorded in [CHANGELOG.md](./CHANGELOG.md).
-
----
+| Command | What it does |
+|---|---|
+| `impact` | Predict which test files a change requires, and how much of the import graph resolved. Report-only. |
+| `impact verify <report>` | Reconcile the last prediction against a Vitest or Jest JSON report and report false skips |
+| `diff <file>` | Classify one file's change and list the exported symbols that changed |
+| `pr check` | Classify every TypeScript change on the branch and roll them into one build verdict |
+| `pr report` | The `pr check` verdict as JSON, or as markdown for a PR comment |
+| `workspace check` | Fail when a package imports a dependency it does not declare |
+
+Run `variant <command> --help` for its flags, or see the
+[CLI reference](./docs/cli-reference.md). The [tutorial](./docs/tutorial.md)
+walks through every command on a sample monorepo in about fifteen minutes.
+
+Every changed file gets one of three classifications. `non-impacting` means
+only comments or formatting changed, and selects no tests. `internal` means the
+body changed but the exported surface did not, and selects every test that
+imports the file. `breaking` means an exported signature changed, and also
+follows the importers of the changed names for `pr check`'s verdict. A change
+to `package.json`, a lockfile, `tsconfig*.json`, a test runner config or a test
+setup file selects every test.
+
+### In CI
+
+Check out with `fetch-depth: 0` and pass `--base origin/<branch>`. A shallow
+clone has no base commit to compare against, and `actions/checkout` creates no
+local branch for the target; variant stops with `GIT_REF_ERROR` rather than
+guess.
+
+Ready-to-copy GitHub Actions workflows are in
+[`examples/github-actions`](./examples/github-actions):
+
+- [`pr-report.yml`](./examples/github-actions/pr-report.yml) keeps one sticky
+  comment with the verdict on every pull request.
+- [`workspace-check.yml`](./examples/github-actions/workspace-check.yml) fails
+  the build on an undeclared dependency.
+- [`impact-shadow.yml`](./examples/github-actions/impact-shadow.yml) logs a
+  prediction, runs the full suite anyway, and reconciles the two.
+
+### Help measure it
+
+A false skip is a test that failed and that the prediction did not select. The
+false-skip rate is false skips divided by failed test files, with flaky
+failures counted against variant. One repository is not enough to trust it.
+
+If you add `impact-shadow.yml` to your CI, it changes nothing about your build.
+It uploads the counts as a `variant-reconciliation` artifact: commit SHAs,
+branch names and numbers, no file paths and no source.
+[Share them in an issue](https://github.com/saintparish4/variant/issues/new?template=3.shadow_results.yml),
+and they go into the measurement that decides whether skipping ever ships.
+
+## Benchmarks
+
+Measured by CI on 2026-09-28 with [`benchmarks/bench.mjs`](./benchmarks/bench.mjs),
+on a generated git repository of 300 TypeScript files with 25 changed. Each
+number is the median of the runs shown. Machine: AMD EPYC 9V74 (4 cores),
+16 GB RAM, Linux, Node 22.23.2, hyperfine 1.18.0.
+
+| | Median | Runs |
+|---|---:|---:|
+| `variant --help` (startup) | 36.7 ms | 20 |
+| `variant impact`, 25 changed files of 300 | 988 ms | 10 |
+
+- **Startup is a CI gate.** The benchmark workflow fails when the `--help`
+  median passes 200 ms, because every command is loaded only when it runs.
+- **The symbol index is cached.** `.variant/graph/symbols.json` keeps each
+  file's exports and imports keyed by content hash, so a later run re-parses
+  only the files whose content changed.
+- **Large real repositories are not measured yet.** 300 generated files say
+  how the pipeline behaves, not what it costs on your monorepo. Whether the
+  analysis pays for itself depends on how long your suite takes, and that
+  number has to come from real runs.
+
+Reproduce with `pnpm build && pnpm bench`; the methodology is in
+[`benchmarks/README.md`](./benchmarks/README.md).
+
+## How it compares
+
+**Nx `affected`, Turborepo `--filter`.** These work at the level of projects
+and tasks: a change inside `utils` reruns the test target of `utils` and of
+every project that depends on it. In the example above, that is all four test
+files. variant works at the level of test files and follows each one's imports
+across packages, so it runs two. Nx and Turborepo also cache and orchestrate
+tasks; variant's `impact` does neither, and the two can be used together.
+
+**`vitest related`, `jest --findRelatedTests`.** These follow imports at the
+file level too, within one project. variant adds two things: import chains that
+cross workspace packages, and classification, so a change to comments or
+formatting selects no tests at all.
+
+**Not function-level.** Test selection is by file: a test that imports a changed
+file runs, whichever functions it calls. The exported-surface classification
+decides `pr check`'s build verdict and whether a change selects anything, not
+which functions a test touches.
+
+## Limitations
+
+Worth knowing before you trust a prediction. variant reads source statically,
+so it sees imports and nothing else. It widens the selection or lowers its
+confidence wherever it can tell it is missing something, but some edges it
+cannot see at all:
+
+- **Runtime-only wiring is invisible.** Dependency injection by token,
+  string-keyed registries, computed `require()` and `eval` never appear as
+  imports. A test that reaches code only this way is not selected, and nothing
+  in the output says so. This is the largest blind spot.
+- **Service boundaries end the graph.** An end-to-end test that calls a running
+  server imports none of the code it exercises.
+- **Setup files are recognized by name.** `vitest.setup.ts`, `setupTests.ts`,
+  `global-setup.ts` and the like select every test; a setup file named
+  anything else selects none. variant does not read the runner config.
+- **Fixtures, snapshots and non-TypeScript assets** a test reads at runtime are
+  outside its import closure. Unresolved imports lower the confidence score and
+  add a note, but the missing edges stay missing.
+- **Dynamic `import()` is assumed to use everything.** The change propagates
+  and a note is printed; the run gets wider, not narrower.
+- **Type-only changes are not narrowed.** Changing an interface selects every
+  test that imports the file, though no runtime behavior changed.
+- **The confidence score is not a safety number.** It says how much of the
+  import graph resolved. Only the false-skip rate says how safe a skip would
+  have been.
+
+The full list, with how each case is handled, is in
+[Impact & workspace](./docs/impact-and-workspace.md#limitations).
+
+## Documentation
+
+| | |
+|---|---|
+| [Tutorial](./docs/tutorial.md) | Every command, step by step, on a sample monorepo |
+| [Getting started](./docs/getting-started.md) | Run it on your own repository, then set up the task runner |
+| [Impact & workspace](./docs/impact-and-workspace.md) | How `impact` and `workspace check` work, and what static analysis cannot see |
+| [PR commands](./docs/pr-commands.md) | `pr check` and `pr report` |
+| [CLI reference](./docs/cli-reference.md) | Every command, flag, exit code and file |
+| [API reference](./docs/api.md) | `defineConfig`, the config types, and every JSON output |
+| [Monorepo setup](./docs/monorepo.md) | Workspace tasks and `--affected` |
+| [Config reference](./docs/config-reference.md) | Every `variant.config.ts` key |
+| [Troubleshooting](./docs/troubleshooting.md) | Common problems and what they mean |
 
 ## Contributing
 
-Read [CONTRIBUTORS.md](./CONTRIBUTORS.md) for the full workflow and [CLAUDE.md](./CLAUDE.md) for architecture and code-style rules. The short version:
-
-- All PRs must pass `pnpm format:check`, `pnpm lint`, `pnpm typecheck`, and `pnpm build`.
-- Changed behavior needs a test; a bug fix needs a test that fails before it.
-- Behavior changes that users can observe need a `docs/` update in the same PR.
-- Conventional commits: `<type>: <subject>`, imperative mood, ≤ 72 chars, no trailing period.
-- Bump one dependency at a time — never a blanket `pnpm update` — so lockfile diffs stay reviewable.
-
----
+See [CONTRIBUTORS.md](./CONTRIBUTORS.md) to set up the repository, run the
+tests, and check a change before opening a pull request.
 
 ## License
 

package/dist/{build-2LO7GD2S.js → build-3DSBMMI3.js}

@@ -2,23 +2,23 @@ import {
   executeTarget,
   renderDryRunPlan,
   reportRunInsights
-} from "./chunk-4LLK2S4R.js";
-import "./chunk-LXKLCLL6.js";
-import "./chunk-ISRF5F3Q.js";
+} from "./chunk-FA64KWJ2.js";
+import "./chunk-43VLELTL.js";
+import "./chunk-QRPI6TJE.js";
 import {
   createContext,
   toRunOptions
-} from "./chunk-SWPVR2DF.js";
+} from "./chunk-ZH2PQUNL.js";
 import "./chunk-V5CTGXMM.js";
-import "./chunk-RGD422OM.js";
+import "./chunk-26DHEXGS.js";
 import "./chunk-YYGCSKIQ.js";
 import "./chunk-GDSZFIHM.js";
-import "./chunk-MZZOE7L4.js";
+import "./chunk-7OPTWU6E.js";
 import "./chunk-3E5LBU3O.js";
-import "./chunk-RVXUCJYA.js";
-import "./chunk-XUBWCTJZ.js";
+import "./chunk-6BXSZPHC.js";
 import "./chunk-6J4XDG44.js";
-import "./chunk-V22IPJ7A.js";
+import "./chunk-EISTWXDW.js";
+import "./chunk-VYWPQKMS.js";
 
 // src/core/scope/task-filter.ts
 function taskPackage(taskName) {

package/dist/{check-ZTKGGF4M.js → check-SIQJU6Z2.js}

@@ -1,21 +1,21 @@
 import {
   createContext
-} from "./chunk-SWPVR2DF.js";
+} from "./chunk-ZH2PQUNL.js";
 import "./chunk-V5CTGXMM.js";
-import "./chunk-RGD422OM.js";
+import "./chunk-26DHEXGS.js";
 import "./chunk-YYGCSKIQ.js";
-import "./chunk-MZZOE7L4.js";
+import "./chunk-7OPTWU6E.js";
 import "./chunk-3E5LBU3O.js";
-import {
-  ConfigError
-} from "./chunk-RVXUCJYA.js";
-import "./chunk-XUBWCTJZ.js";
+import "./chunk-6BXSZPHC.js";
 import {
   lines
 } from "./chunk-6J4XDG44.js";
 import {
   getPrinter
-} from "./chunk-V22IPJ7A.js";
+} from "./chunk-EISTWXDW.js";
+import {
+  ConfigError
+} from "./chunk-VYWPQKMS.js";
 
 // src/core/graph/validation.ts
 function validateTaskGraph(tasks, graph) {

package/dist/{chunk-RGD422OM.js → chunk-26DHEXGS.js}

@@ -1,6 +1,6 @@
 import {
   ConfigError
-} from "./chunk-RVXUCJYA.js";
+} from "./chunk-VYWPQKMS.js";
 
 // src/core/config/loader.ts
 import { existsSync } from "fs";

package/dist/{chunk-LXKLCLL6.js → chunk-43VLELTL.js}

@@ -1,6 +1,6 @@
 import {
   CacheError
-} from "./chunk-RVXUCJYA.js";
+} from "./chunk-VYWPQKMS.js";
 
 // src/core/cache/store.ts
 import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "fs";

package/dist/{chunk-XUBWCTJZ.js → chunk-6BXSZPHC.js}

@@ -11,11 +11,15 @@ async function git(cwd, args) {
     return null;
   }
 }
+function isOptionLike(ref) {
+  return ref.startsWith("-");
+}
 function toFileList(stdout) {
   if (stdout === null) return null;
   return stdout.split("\n").map((s) => s.trim()).filter((s) => s.length > 0);
 }
 async function readFileAtRef(cwd, ref, relPath) {
+  if (isOptionLike(ref)) return null;
   return git(cwd, ["show", `${ref}:${toPosix(relPath)}`]);
 }
 var CAT_FILE_BATCH_SIZE = 256;
@@ -82,10 +86,23 @@ async function readHeadSha(cwd) {
   const sha = stdout?.trim();
   return sha === void 0 || sha === "" ? null : sha;
 }
+async function resolveCommit(cwd, ref) {
+  if (isOptionLike(ref)) return null;
+  const stdout = await git(cwd, [
+    "rev-parse",
+    "--verify",
+    "--quiet",
+    `${ref}^{commit}`
+  ]);
+  const sha = stdout?.trim();
+  return sha === void 0 || sha === "" ? null : sha;
+}
 async function listChangedFiles(cwd, ref) {
+  if (isOptionLike(ref)) return null;
   return toFileList(await git(cwd, ["diff", "--name-only", ref, "--"]));
 }
 async function listChangedFilesSinceMergeBase(cwd, ref) {
+  if (isOptionLike(ref)) return null;
   return toFileList(
     await git(cwd, ["diff", "--name-only", `${ref}...HEAD`, "--"])
   );
@@ -95,6 +112,7 @@ export {
   readFileAtRef,
   readFilesAtRef,
   readHeadSha,
+  resolveCommit,
   listChangedFiles,
   listChangedFilesSinceMergeBase
 };

package/dist/{chunk-MZZOE7L4.js → chunk-7OPTWU6E.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-3E5LBU3O.js";
 import {
   listChangedFiles
-} from "./chunk-XUBWCTJZ.js";
+} from "./chunk-6BXSZPHC.js";
 
 // src/core/cache/git-diff.ts
 import path from "path";

package/dist/{chunk-V22IPJ7A.js → chunk-EISTWXDW.js}

@@ -17,8 +17,12 @@ var Printer = class _Printer {
     if (flags.noProgress) return new _Printer("no-progress", streams);
     return new _Printer("default", streams);
   }
+  /**
+   * As in uv, `-q` quiets the commentary, not the answer: a script that asks
+   * for `--json` with `-q` still gets its JSON. Only `-qq` silences stdout.
+   */
   get stdoutEnabled() {
-    return this.mode !== "silent" && this.mode !== "quiet";
+    return this.mode !== "silent";
   }
   get stderrEnabled() {
     return this.mode !== "silent" && this.mode !== "quiet";

package/dist/{chunk-4LLK2S4R.js → chunk-FA64KWJ2.js}

@@ -4,30 +4,30 @@ import {
   readCache,
   writeCache,
   writeCacheSync
-} from "./chunk-LXKLCLL6.js";
+} from "./chunk-43VLELTL.js";
 import {
   renderInsights
-} from "./chunk-ISRF5F3Q.js";
+} from "./chunk-QRPI6TJE.js";
 import {
   recordCacheMiss,
   runScheduled
-} from "./chunk-SWPVR2DF.js";
+} from "./chunk-ZH2PQUNL.js";
 import {
   getColors
 } from "./chunk-YYGCSKIQ.js";
 import {
   mapLimit
 } from "./chunk-GDSZFIHM.js";
-import {
-  TaskExecutionError,
-  VariantError
-} from "./chunk-RVXUCJYA.js";
 import {
   lines
 } from "./chunk-6J4XDG44.js";
 import {
   getPrinter
-} from "./chunk-V22IPJ7A.js";
+} from "./chunk-EISTWXDW.js";
+import {
+  TaskExecutionError,
+  VariantError
+} from "./chunk-VYWPQKMS.js";
 
 // src/core/execution/runner.ts
 import { createHash as createHash2 } from "crypto";

package/dist/{chunk-LJDDS4RR.js → chunk-FZEXZBXB.js}

@@ -1,7 +1,20 @@
+import {
+  resolveCommit
+} from "./chunk-6BXSZPHC.js";
 import {
   collectExportedSurface,
   significantText
-} from "./chunk-O4LZKXNZ.js";
+} from "./chunk-RC23JQKI.js";
+import {
+  GitRefError
+} from "./chunk-VYWPQKMS.js";
+
+// src/core/vcs/base-ref.ts
+async function assertBaseRef(cwd, ref) {
+  if (await resolveCommit(cwd, ref) === null) {
+    throw new GitRefError(`"${ref}" does not name a commit in this repository`);
+  }
+}
 
 // src/core/semantic/differ.ts
 function createClassifier() {
@@ -87,5 +100,6 @@ function compareSurfaces(input, beforeFile, afterFile, tsm) {
 
 export {
   createClassifier,
-  classifyChange
+  classifyChange,
+  assertBaseRef
 };

package/dist/{chunk-NSNZOH5P.js → chunk-Q7RLUZSN.js}

@@ -1,9 +1,9 @@
 import {
   classifyChange
-} from "./chunk-LJDDS4RR.js";
+} from "./chunk-FZEXZBXB.js";
 import {
   readFileAtRef
-} from "./chunk-XUBWCTJZ.js";
+} from "./chunk-6BXSZPHC.js";
 
 // src/core/semantic/file-change.ts
 import { readFile } from "fs/promises";

package/dist/{chunk-ISRF5F3Q.js → chunk-QRPI6TJE.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-6J4XDG44.js";
 import {
   getPrinter
-} from "./chunk-V22IPJ7A.js";
+} from "./chunk-EISTWXDW.js";
 
 // src/cli/render/insight.ts
 function statusLabel(result) {