@blzsky/variant 0.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+                                     MIT License
+
+                        Copyright (c) 2026-present, Bluesky Labs.
+
+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

@@ -0,0 +1,177 @@
+# variant
+
+[![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)
+```
+
+`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).
+
+---
+
+## Requirements
+
+| | 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 |
+
+Optional: **[hyperfine](https://github.com/sharkdp/hyperfine)**, required by `pnpm bench`.
+
+---
+
+## Installation
+
+```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
+
+```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)
+```
+
+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.
+
+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/` |
+
+```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
+```
+
+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.
+
+---
+
+## 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.
+
+```bash
+pnpm publish            # prepublishOnly runs `pnpm test:all && pnpm build`
+```
+
+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).
+
+---
+
+## 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.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/build-2LO7GD2S.js

@@ -0,0 +1,63 @@
+import {
+  executeTarget,
+  renderDryRunPlan,
+  reportRunInsights
+} from "./chunk-4LLK2S4R.js";
+import "./chunk-LXKLCLL6.js";
+import "./chunk-ISRF5F3Q.js";
+import {
+  createContext,
+  toRunOptions
+} from "./chunk-SWPVR2DF.js";
+import "./chunk-V5CTGXMM.js";
+import "./chunk-RGD422OM.js";
+import "./chunk-YYGCSKIQ.js";
+import "./chunk-GDSZFIHM.js";
+import "./chunk-MZZOE7L4.js";
+import "./chunk-3E5LBU3O.js";
+import "./chunk-RVXUCJYA.js";
+import "./chunk-XUBWCTJZ.js";
+import "./chunk-6J4XDG44.js";
+import "./chunk-V22IPJ7A.js";
+
+// src/core/scope/task-filter.ts
+function taskPackage(taskName) {
+  const colon = taskName.indexOf(":");
+  return colon === -1 ? null : taskName.slice(0, colon);
+}
+function affectedTaskFilter(packages) {
+  return (taskName) => {
+    const pkg = taskPackage(taskName);
+    return pkg === null || packages.has(pkg);
+  };
+}
+function bothFilters(first, second) {
+  if (first === void 0) return second;
+  return (taskName) => first(taskName) && second(taskName);
+}
+
+// src/cli/commands/build.ts
+async function registerBuildAction(opts = {}) {
+  const ctx = await createContext();
+  if (opts.dryRun) {
+    renderDryRunPlan("build", ctx.graph.toLevels("build"));
+    return;
+  }
+  const runOptions = toRunOptions(ctx, opts);
+  if (opts.affected && ctx.affectedPackages !== void 0) {
+    runOptions.taskFilter = bothFilters(
+      runOptions.taskFilter,
+      affectedTaskFilter(ctx.affectedPackages)
+    );
+  }
+  const results = await executeTarget(
+    "build",
+    ctx,
+    runOptions,
+    "Running build tasks..."
+  );
+  await reportRunInsights(ctx, results);
+}
+export {
+  registerBuildAction
+};

package/dist/check-ZTKGGF4M.js

@@ -0,0 +1,44 @@
+import {
+  createContext
+} from "./chunk-SWPVR2DF.js";
+import "./chunk-V5CTGXMM.js";
+import "./chunk-RGD422OM.js";
+import "./chunk-YYGCSKIQ.js";
+import "./chunk-MZZOE7L4.js";
+import "./chunk-3E5LBU3O.js";
+import {
+  ConfigError
+} from "./chunk-RVXUCJYA.js";
+import "./chunk-XUBWCTJZ.js";
+import {
+  lines
+} from "./chunk-6J4XDG44.js";
+import {
+  getPrinter
+} from "./chunk-V22IPJ7A.js";
+
+// src/core/graph/validation.ts
+function validateTaskGraph(tasks, graph) {
+  for (const [name, task] of Object.entries(tasks)) {
+    for (const dependency of task.dependsOn ?? []) {
+      if (!(dependency in tasks)) {
+        throw new ConfigError(
+          `Task "${name}" depends on unknown task "${dependency}"`
+        );
+      }
+    }
+  }
+  for (const name of Object.keys(tasks)) {
+    graph.toLevels(name);
+  }
+}
+
+// src/cli/commands/check.ts
+async function registerCheckAction() {
+  const ctx = await createContext(process.cwd(), { scope: false });
+  validateTaskGraph(ctx.config.tasks, ctx.graph);
+  lines(getPrinter(), "Config and graph are valid.");
+}
+export {
+  registerCheckAction
+};

package/dist/chunk-3E5LBU3O.js

@@ -0,0 +1,180 @@
+// src/core/graph/package-graph.ts
+import { readFile, stat } from "fs/promises";
+import path from "path";
+var WORKSPACE_GLOBS_FALLBACK = ["packages/*", "apps/*", "services/*"];
+async function loadPackageGraph(cwd) {
+  const fg = (await import("fast-glob")).default;
+  const globs = await readWorkspaceGlobs(cwd);
+  const dirs = await fg(globs, {
+    cwd,
+    onlyDirectories: true,
+    absolute: true
+  });
+  const packages = (await Promise.all(dirs.sort().map(readPackage))).filter(
+    (pkg) => pkg !== null
+  );
+  const byName = new Map(packages.map((p) => [p.manifest.name, p]));
+  const edges = /* @__PURE__ */ new Map();
+  for (const p of packages) {
+    const set = /* @__PURE__ */ new Set();
+    const all = {
+      ...p.manifest.dependencies ?? {},
+      ...p.manifest.devDependencies ?? {},
+      ...p.manifest.peerDependencies ?? {}
+    };
+    for (const dep of Object.keys(all)) {
+      if (byName.has(dep)) set.add(dep);
+    }
+    edges.set(p.manifest.name, set);
+  }
+  return { packages, edges };
+}
+var ownersByGraph = /* @__PURE__ */ new WeakMap();
+function ownersOf(graph) {
+  let owners = ownersByGraph.get(graph);
+  if (owners === void 0) {
+    owners = /* @__PURE__ */ new Map();
+    for (const pkg of graph.packages) {
+      const dir = path.resolve(pkg.dir);
+      if (!owners.has(dir)) owners.set(dir, pkg);
+    }
+    ownersByGraph.set(graph, owners);
+  }
+  return owners;
+}
+function packageForFile(filePath, graph) {
+  const owners = ownersOf(graph);
+  if (owners.size === 0) return null;
+  let current = path.resolve(filePath);
+  while (true) {
+    const owner = owners.get(current);
+    if (owner !== void 0) return owner;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function tasksFromPackageGraph(graph, existing, scripts = ["build", "test", "lint"], pm = "pnpm") {
+  const out = { ...existing };
+  for (const pkg of graph.packages) {
+    const pkgScripts = pkg.manifest.scripts ?? {};
+    for (const script of scripts) {
+      if (!pkgScripts[script]) continue;
+      const taskName = `${pkg.manifest.name}:${script}`;
+      if (out[taskName]) continue;
+      const dependsOn = [];
+      for (const upstream of graph.edges.get(pkg.manifest.name) ?? []) {
+        if (scripts.includes(script)) {
+          dependsOn.push(`${upstream}:${script}`);
+        }
+      }
+      out[taskName] = {
+        command: `${pm} --filter ${pkg.manifest.name} run ${script}`,
+        dependsOn,
+        inputs: [
+          path.posix.join(
+            path.relative(process.cwd(), pkg.dir).replace(/\\/g, "/"),
+            "**/*.{ts,tsx,js,jsx,json}"
+          )
+        ]
+      };
+    }
+  }
+  for (const script of scripts) {
+    const workspaceTasks = Object.keys(out).filter(
+      (name) => name.endsWith(`:${script}`) && !existing[name]
+    );
+    if (workspaceTasks.length > 0 && out[script] !== void 0) {
+      const existingDeps = out[script].dependsOn ?? [];
+      const newDeps = workspaceTasks.filter((t) => !existingDeps.includes(t));
+      out[script] = {
+        ...out[script],
+        dependsOn: [...existingDeps, ...newDeps]
+      };
+    }
+  }
+  return out;
+}
+function computeAffectedPackages(changed, graph) {
+  const rdeps = /* @__PURE__ */ new Map();
+  for (const [name, deps] of graph.edges) {
+    for (const dep of deps) {
+      let s = rdeps.get(dep);
+      if (!s) {
+        s = /* @__PURE__ */ new Set();
+        rdeps.set(dep, s);
+      }
+      s.add(name);
+    }
+  }
+  const affected = new Set(changed);
+  let frontier = new Set(changed);
+  while (frontier.size > 0) {
+    const next = /* @__PURE__ */ new Set();
+    for (const pkg of frontier) {
+      for (const dependent of rdeps.get(pkg) ?? []) {
+        if (!affected.has(dependent)) {
+          affected.add(dependent);
+          next.add(dependent);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return affected;
+}
+async function readWorkspaceGlobs(cwd) {
+  const pnpm = path.join(cwd, "pnpm-workspace.yaml");
+  if (await fileExists(pnpm)) {
+    const text = await readFile(pnpm, "utf8");
+    const lines = text.split("\n");
+    const globs = [];
+    let inPackages = false;
+    for (const line of lines) {
+      const t = line.trim();
+      if (t.startsWith("packages:")) {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages) {
+        const m = /^-\s*['"]?([^'"\s]+)['"]?/.exec(t);
+        const glob = m?.[1];
+        if (glob !== void 0) globs.push(glob);
+        else if (t && !t.startsWith("#")) inPackages = false;
+      }
+    }
+    if (globs.length) return globs;
+  }
+  const root = path.join(cwd, "package.json");
+  if (await fileExists(root)) {
+    const json = JSON.parse(await readFile(root, "utf8"));
+    const ws = Array.isArray(json.workspaces) ? json.workspaces : json.workspaces?.packages;
+    if (ws?.length) return ws;
+  }
+  return WORKSPACE_GLOBS_FALLBACK;
+}
+async function readPackage(dir) {
+  const manifestPath = path.join(dir, "package.json");
+  try {
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    if (!manifest?.name) return null;
+    return { name: manifest.name, dir, manifest };
+  } catch {
+    return null;
+  }
+}
+async function fileExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  loadPackageGraph,
+  packageForFile,
+  tasksFromPackageGraph,
+  computeAffectedPackages
+};