leanest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leanest Contributors
+
+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,198 @@
+# Leanest
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/baronunread/leanest/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/leanest)](https://www.npmjs.com/package/leanest)
+[![CI](https://github.com/baronunread/leanest/actions/workflows/ci.yml/badge.svg)](https://github.com/baronunread/leanest/actions)
+
+> Leanest does not predict which tests will fail. It determines which tests are safe enough not to run.
+
+Local-first test selection using [Jev](https://typesafe.ai) semantic judgments. Leanest sits in front of your existing test runner and runs only the tests that matter for a given code change. Everything else it skips, on purpose, out loud.
+
+---
+
+## Install
+
+Requires [Bun](https://bun.sh): the CLI runs on it directly, no build step.
+
+```bash
+bun add -D leanest
+```
+
+Set your TypeSafe API key:
+
+```bash
+export TYPESAFE_API_KEY="..."
+```
+
+## Quick Start
+
+```bash
+npx leanest playwright                       # select + actually run the affected e2e tests
+npx leanest playwright --base origin/main     # diff against a specific base
+npx leanest select playwright                 # just show the selection, don't run anything
+npx leanest inspect playwright                # rank every test by relevance, for debugging
+```
+
+## How It Works
+
+```
+Repository
+   |
+   +-- Git change (base...head)
+   +-- Discovered test files
+   |
+   v
+Leanest
+   |
+   +-- Change resolver     (git diff)
+   +-- Test discovery      (respects the framework's own config, e.g. playwright.config.ts testDir)
+   +-- Context builder     (packages the diff + each test's source for Jev)
+   +-- Jev evaluator       (one semantic judgment per test, in parallel)
+   +-- Selection policy    (RUN / SKIP, fail-open on low confidence)
+   |
+   v
+Selected test files
+   |
+   v
+Your existing runner (playwright / vitest), unmodified
+```
+
+For each discovered test, Leanest asks:
+
+> **Could the current code change affect behavior verified by this test?**
+
+Tests that are confidently irrelevant get skipped. Everything else runs through your existing runner exactly as it would outside Leanest: same reporter, same exit code, same flags.
+
+## Core Principles
+
+- **Fail open**: uncertainty means RUN. A missing API key, an API timeout, or a malformed response always falls back to running the full suite, loudly (`⚠ Jev unavailable (...), running the full suite.`).
+- **Deterministic overrides**: a test whose own file changed always runs. No threshold decides that.
+- **Leanest doesn't run tests itself**: it selects file paths and hands them to your actual runner (`playwright test <paths>`, `vitest run <paths>`). It leaves reporters, retries, sharding, and CI-required-check behavior alone.
+- **Static checks are out of scope on purpose**: lint/format/typecheck are already fast at full scope, and semantic per-rule selection would add latency for no real payoff. Leanest spends its Jev budget only on suites that are expensive to run in full: e2e today, more later.
+
+## Adapters
+
+| Framework  | Status      | Command                   |
+| ---------- | ----------- | -------------------------- |
+| Playwright | First-class | `npx leanest playwright`  |
+| Vitest     | First-class | `npx leanest vitest`      |
+| Jest       | Planned     | —                          |
+| Pytest     | Planned     | —                          |
+
+## CLI Usage
+
+### Select and run (the normal case)
+
+```bash
+npx leanest playwright
+```
+
+### Working tree only (uncommitted changes)
+
+```bash
+npx leanest playwright --changed
+```
+
+### Specific base branch
+
+```bash
+npx leanest playwright --base main
+```
+
+### Target a different directory
+
+```bash
+npx leanest playwright --dir ~/projects/my-app
+```
+
+### Machine-readable output
+
+```bash
+npx leanest playwright --json
+```
+
+### Selection only, no execution
+
+```bash
+npx leanest select playwright --base origin/main
+```
+
+### Full suite, no selection
+
+```bash
+npx leanest playwright --full
+```
+
+### Shadow mode
+
+Runs the full suite for real (it skips nothing), but logs what Leanest would have skipped, so you can build trust in the selection before turning it on:
+
+```bash
+npx leanest playwright --shadow
+```
+
+### Inspect mode (debugging / ranking)
+
+```bash
+npx leanest inspect playwright
+```
+
+```
+RUN   tests/e2e/admin-users-export.pw.ts
+RUN   tests/e2e/downgrade.pw.ts
+SKIP  tests/e2e/qr-generator.pw.ts
+SKIP  tests/e2e/avatar.pw.ts
+...
+```
+
+## Configuration
+
+Leanest loads `.env` for local convenience. The API key is never persisted or logged.
+
+```dotenv
+TYPESAFE_API_KEY=...
+```
+
+That's the only configuration knob today. Framework choice, base ref, and target directory are all CLI flags (`--base`, `--dir`), so there's nothing else to set up per project.
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+
+- uses: baronunread/leanest@v1
+  with:
+    framework: playwright
+    typesafe-api-key: ${{ secrets.TYPESAFE_API_KEY }}
+```
+
+This installs Bun, installs `leanest`, and replaces your existing "run e2e tests" step: same reporter output, same exit code, just fewer tests executed.
+
+### Any other CI
+
+```bash
+bun add -g leanest
+leanest playwright --base origin/main
+```
+
+Works anywhere you can run a shell command and set an env var: GitLab CI, CircleCI, Buildkite.
+
+## Development
+
+```bash
+bun install
+bun run check   # lint + format check + typecheck + test
+bun test        # just the test suite
+```
+
+## Contributing
+
+See [SIEVE_SPEC.md](./SIEVE_SPEC.md) for the design rationale behind the selection policy.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "leanest",
+	"version": "0.1.0",
+	"description": "Local-first test selector using Jev judgments to determine which tests are affected by a code change",
+	"type": "module",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"bin": {
+		"leanest": "src/cli.ts"
+	},
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts"
+		}
+	},
+	"files": ["src/**", "!src/**/*.test.ts"],
+	"scripts": {
+		"lint": "bunx oxlint",
+		"format": "bunx oxfmt",
+		"test": "bun test",
+		"check": "bunx oxlint && bunx oxfmt --check && bunx style-doctor README.md && bun run typecheck && bun test",
+		"typecheck": "bunx tsc --noEmit",
+		"prepare": "bun run check",
+		"prepublishOnly": "bun run check"
+	},
+	"keywords": ["test", "selector", "jest", "vitest", "playwright", "jev", "typesafe", "ci"],
+	"author": "Leanest Contributors",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/baronunread/leanest.git"
+	},
+	"bugs": {
+		"url": "https://github.com/baronunread/leanest/issues"
+	},
+	"homepage": "https://github.com/baronunread/leanest#readme",
+	"packageManager": "bun@1.4.1",
+	"dependencies": {
+		"dotenv": "^17.4.2"
+	},
+	"devDependencies": {
+		"@oxlint/plugins": "1.83.0",
+		"@types/bun": "^1.4.2",
+		"@types/node": "^22.20.3",
+		"oxfmt": "0.68.0",
+		"oxlint": "1.83.0",
+		"style-doctor": "0.3.0",
+		"tsx": "^4.23.13",
+		"typescript": "^7.0.2"
+	}
+}

package/src/change-resolver.ts

@@ -0,0 +1,77 @@
+import { execSync } from "child_process";
+
+export interface GitChange {
+  base: string;
+  head: string;
+  changedFiles: string[];
+  diff: string;
+  baseRef: string;
+}
+
+export class ChangeResolver {
+  private baseRef: string;
+
+  constructor(baseRef?: string) {
+    this.baseRef = baseRef ?? "main";
+  }
+
+  resolve(headRef?: string): GitChange {
+    const head = headRef ?? "HEAD";
+    const base = this.baseRef;
+    try {
+      // SAFETY: execSync returns a Buffer, we convert to string for text processing
+      const diff = execSync(`git diff ${base}...${head}`, { timeout: 30000 }) as Buffer;
+      // SAFETY: execSync returns a Buffer, we convert to string for file listing
+      const filesOutput = execSync(`git diff ${base}...${head} --name-only`, {
+        timeout: 30000,
+      }) as Buffer;
+      const changedFiles: string[] = filesOutput
+        .toString()
+        .trim()
+        .split("\n")
+        .filter((f: string) => f.length > 0);
+      return {
+        base,
+        head,
+        changedFiles,
+        diff: diff.toString(),
+        baseRef: base,
+      };
+    } catch {
+      return {
+        base,
+        head,
+        changedFiles: [],
+        diff: "",
+        baseRef: base,
+      };
+    }
+  }
+
+  resolveChangedOnly(): GitChange {
+    try {
+      // SAFETY: execSync returns a Buffer, we convert to string for file listing
+      const diff = execSync(`git diff --name-only`, { timeout: 30000 }) as Buffer;
+      const changedFiles: string[] = diff
+        .toString()
+        .trim()
+        .split("\n")
+        .filter((f: string) => f.length > 0);
+      return {
+        base: "working-tree",
+        head: "HEAD",
+        changedFiles,
+        diff: diff.toString(),
+        baseRef: "",
+      };
+    } catch {
+      return {
+        base: "working-tree",
+        head: "HEAD",
+        changedFiles: [],
+        diff: "",
+        baseRef: "",
+      };
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env bun
+
+import { Sieve } from "./sieve.js";
+import { SelectionPolicy } from "./selection-policy.js";
+import { runTests } from "./runner.js";
+
+interface Flags {
+  _: string[];
+  changed?: boolean;
+  json?: boolean;
+  shadow?: boolean;
+  full?: boolean;
+  base?: string;
+  dir?: string;
+  [key: string]: boolean | string | string[] | undefined;
+}
+
+async function main(): Promise<number> {
+  const args = Bun.argv.slice(2);
+  const rawCommand = args[0] ?? "help";
+  const command = rawCommand === "--help" ? "help" : rawCommand;
+  const rest = rawCommand === "--help" ? args : args.slice(1);
+  const flags = parseFlags(rest);
+  const framework = flags._[0] ?? "playwright";
+  const changed = flags.changed === true;
+  const json = flags.json === true;
+  const shadow = flags.shadow === true;
+  const full = flags.full === true;
+  // SAFETY: flags.dir is a directory path string or undefined
+  const cwd = (flags.dir as string | undefined) ?? ".";
+  // SAFETY: flags.base is a git ref string or undefined
+  const base = flags.base as string | undefined;
+
+  const sieve = new Sieve(cwd, base);
+
+  if (command === "help" || !command) {
+    printHelp();
+    return 0;
+  }
+
+  switch (command) {
+    case "inspect": {
+      const result = await sieve.inspect(framework);
+      printInspect(result);
+      return 0;
+    }
+    case "select": {
+      const result = await sieve.select(framework, changed);
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printSelect(result);
+      }
+      return 0;
+    }
+    case "playwright":
+    case "vitest": {
+      const result = await sieve.select(command, changed);
+      if (result.status === "error") {
+        console.error(`⚠ Jev unavailable (${result.error}), running the full suite.`);
+      }
+
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printSelect(result);
+      }
+
+      if (shadow) {
+        console.log(
+          `\nShadow mode: would run ${result.selectedTests.length} of ${result.totalTests} tests. Running full suite for real.`,
+        );
+        return await runTests(command, [], cwd);
+      }
+
+      if (full) {
+        console.log(`\nRunning the full suite (--full)...`);
+        return await runTests(command, [], cwd);
+      }
+
+      if (result.selectedTests.length === 0) {
+        console.log(`\nNothing to run.`);
+        return 0;
+      }
+
+      const paths = result.selectedTests.map((t) => t.identity.path);
+      console.log(`\nRunning ${command} on ${paths.length} selected test file(s)...`);
+      return await runTests(command, paths, cwd);
+    }
+    default: {
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      return 1;
+    }
+  }
+}
+
+function parseFlags(args: string[]): Flags {
+  const flags: Flags = { _: [] };
+  for (const arg of args) {
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (flags[key] === undefined) {
+        flags[key] = true;
+      } else if (Array.isArray(flags[key])) {
+        // SAFETY: flags[key] is already confirmed as string[] via Array.isArray check
+        (flags[key] as string[]).push(arg);
+      }
+    } else if (arg.startsWith("-")) {
+      const key = arg.slice(1);
+      flags[key] = true;
+    } else {
+      flags._.push(arg);
+    }
+  }
+  return flags;
+}
+
+function printInspect(result: any): void {
+  const { change, discovered } = result;
+  const noChanges = change.changedFiles.length === 0;
+  if (noChanges && discovered.count > 0) {
+    console.log(`No changes detected against ${change.base}...${change.head}`);
+    console.log(`Evaluating all ${discovered.count} tests conservatively...\n`);
+  } else {
+    console.log(`Change: ${change.base}...${change.head}`);
+    console.log(`\nChanged:`);
+    for (const f of change.changedFiles.slice(0, 20)) {
+      console.log(`  ${f}`);
+    }
+    if (change.changedFiles.length > 20) {
+      console.log(`  ... and ${change.changedFiles.length - 20} more`);
+    }
+    console.log(``);
+  }
+  console.log(`Discovering ${discovered.framework} tests...`);
+  console.log(`  ${discovered.count} tests found`);
+  if (result.evaluated.length > 0) {
+    console.log(`\nEvaluating semantic impact...`);
+    console.log(`  ${result.evaluated.length} tests evaluated`);
+    console.log(`\nSelected ${result.selected.length} / ${discovered.count} tests`);
+    const policy = new SelectionPolicy();
+    const ranked = result.evaluated.sort((a: any, b: any) => b.probability - a.probability);
+    for (const entry of ranked.slice(0, 20)) {
+      const decision = policy.decide(entry.probability, entry.confidence, false);
+      console.log(`  ${decision} ${entry.test.identity.path}`);
+    }
+    if (ranked.length > 20) {
+      console.log(`  ... and ${ranked.length - 20} more`);
+    }
+  }
+  console.log(`\nSkipping ${result.skipped} tests.`);
+}
+
+function printSelect(result: any): void {
+  const noChanges = result.changedFiles.length === 0;
+  if (noChanges && result.totalTests > 0) {
+    console.log(`No changes detected.`);
+    console.log(`Evaluating all ${result.totalTests} tests conservatively...\n`);
+  } else {
+    console.log(`Changed:`);
+    for (const f of result.changedFiles.slice(0, 20)) {
+      console.log(`  ${f}`);
+    }
+    console.log(``);
+  }
+  console.log(`${result.totalTests} tests found`);
+  console.log(`\nSelected ${result.selectedTests.length} / ${result.totalTests} tests`);
+  for (const test of result.selectedTests.slice(0, 20)) {
+    console.log(`  RUN ${test.identity.path}`);
+  }
+  if (result.skippedTests > 0) {
+    console.log(`\nSkipping ${result.skippedTests} tests.`);
+  }
+}
+
+function printHelp(): void {
+  console.log(`Usage: leanest <command> [options]
+
+Commands:
+  inspect <framework>   Rank tests by relevance (no execution)
+  select <framework>    Select tests to run vs skip (no execution)
+  playwright [options]  Select, then actually run Playwright on the selection
+  vitest [options]      Select, then actually run Vitest on the selection
+
+Options:
+  --changed             Only changed files
+  --base <ref>          Base branch (default: main)
+  --dir <path>          Target directory (default: current directory)
+  --json                Output JSON
+  --shadow              Run the full suite, but also log what would have been skipped
+  --full                Skip selection, run the full suite
+  --help                Show this help
+
+Examples:
+  npx leanest inspect playwright
+  npx leanest select playwright --base origin/main
+  npx leanest playwright --changed
+  npx leanest playwright --changed --json
+  npx leanest playwright --shadow
+  npx leanest playwright --full
+  npx leanest inspect playwright --dir /path/to/repo
+  leanest vitest --dir ~/projects/my-app --changed
+`);
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/src/context-builder.ts

@@ -0,0 +1,19 @@
+import type { ChangeContext, TestCase } from "./types.js";
+
+export class ContextBuilder {
+  buildState(change: ChangeContext, tests: TestCase[]) {
+    return {
+      changedFiles: change.changedFiles,
+      diff: change.diff.slice(0, 15000),
+      base: change.base,
+      head: change.head,
+      tests: tests.map((t) => ({
+        id: t.identity.hash,
+        path: t.identity.path,
+        suite: t.identity.suite,
+        name: t.identity.name,
+        source: t.source.slice(0, 2000),
+      })),
+    };
+  }
+}

package/src/git-diff.ts

@@ -0,0 +1,83 @@
+import { execSync } from "child_process";
+
+export interface GitChange {
+  base: string;
+  head: string;
+  changedFiles: string[];
+  diff: string;
+  baseRef: string;
+}
+
+export class ChangeResolver {
+  private baseRef: string;
+  private cwd: string;
+
+  constructor(baseRef?: string, cwd?: string) {
+    this.baseRef = baseRef ?? "main";
+    this.cwd = cwd ?? ".";
+  }
+
+  resolve(headRef?: string): GitChange {
+    const head = headRef ?? "HEAD";
+    const base = this.baseRef;
+    try {
+      // SAFETY: execSync returns a Buffer, we convert to string for text processing
+      const diff = execSync(`git diff ${base}...${head}`, {
+        timeout: 30000,
+        cwd: this.cwd,
+      }) as Buffer;
+      // SAFETY: execSync returns a Buffer, we convert to string for file listing
+      const filesOutput = execSync(`git diff ${base}...${head} --name-only`, {
+        timeout: 30000,
+        cwd: this.cwd,
+      }) as Buffer;
+      const changedFiles: string[] = filesOutput
+        .toString()
+        .trim()
+        .split("\n")
+        .filter((f: string) => f.length > 0);
+      return {
+        base,
+        head,
+        changedFiles,
+        diff: diff.toString(),
+        baseRef: base,
+      };
+    } catch {
+      return {
+        base,
+        head,
+        changedFiles: [],
+        diff: "",
+        baseRef: base,
+      };
+    }
+  }
+
+  resolveChangedOnly(): GitChange {
+    try {
+      // SAFETY: execSync returns a Buffer, we convert to string for file listing
+      const diff = execSync(`git diff --name-only`, { timeout: 30000, cwd: this.cwd }) as Buffer;
+      const changedFiles: string[] = diff
+        .toString()
+        .trim()
+        .split("\n")
+        .filter((f: string) => f.length > 0);
+      return {
+        base: "working-tree",
+        head: "HEAD",
+        changedFiles,
+        diff: diff.toString(),
+        baseRef: "",
+      };
+    } catch {
+      return {
+        base: "working-tree",
+        head: "HEAD",
+        changedFiles: [],
+        diff: "",
+        baseRef: "",
+      };
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { runSieve, Sieve } from "./sieve.js";
+export { SelectionPolicy } from "./selection-policy.js";
+export { ChangeResolver } from "./git-diff.js";
+export { ContextBuilder } from "./context-builder.js";
+export { TestDiscovery } from "./test-discovery.js";
+export { JevClient } from "./jev-client.js";
+export type {
+  TestCase,
+  ChangeContext,
+  SelectionResult,
+  TestIdentity,
+  PipelineResult,
+} from "./types.js";

package/src/jev-client.ts

@@ -0,0 +1,78 @@
+import { config } from "dotenv";
+
+config({ quiet: true });
+
+export const API_KEY = process.env.TYPESAFE_API_KEY ?? "";
+export const API_BASE = process.env.TYPESAFE_API_BASE ?? "https://api.typesafe.ai/v1";
+export const MODEL = process.env.TYPESAFE_MODEL ?? "jev-latest";
+
+export interface JevQuestion {
+  type: "noul" | "choice" | "score";
+  instructions: string | object;
+  criteria?: object;
+}
+
+export interface JevState {
+  changedFiles: string[];
+  diff: string;
+  base: string;
+  head: string;
+  tests?: Array<{
+    id: string;
+    path: string;
+    suite: string[];
+    name: string;
+    source: string;
+  }>;
+}
+
+export interface JevResponse {
+  answers: Record<string, { noul?: number; choice?: string; score?: number; confidence?: number }>;
+  model?: string;
+}
+
+export class JevClient {
+  private apiKey: string;
+  private baseUrl: string;
+  private model: string;
+
+  constructor(apiKey?: string, baseUrl?: string, model?: string) {
+    this.apiKey = apiKey ?? API_KEY;
+    this.baseUrl = baseUrl ?? API_BASE;
+    this.model = model ?? MODEL;
+  }
+
+  get hasApiKey(): boolean {
+    return this.apiKey.length > 0;
+  }
+
+  async evaluate(state: JevState, questions: Record<string, JevQuestion>): Promise<JevResponse> {
+    if (!this.hasApiKey) {
+      throw new Error("TYPESAFE_API_KEY is not set. Export it or create a .env file.");
+    }
+
+    const body = {
+      state,
+      questions,
+      model: this.model,
+    };
+
+    const response = await fetch(`${this.baseUrl}/systemone`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`TypeSafe API error (${response.status}): ${text}`);
+    }
+
+    // SAFETY: TypeSafe /v1/systemone always returns a JSON response matching JevResponse shape
+    const data = (await response.json()) as JevResponse;
+    return data;
+  }
+}

package/src/runner.ts

@@ -0,0 +1,16 @@
+const RUN_COMMANDS = {
+  playwright: (paths: string[]) => ["bunx", "playwright", "test", ...paths],
+  vitest: (paths: string[]) => ["bunx", "vitest", "run", ...paths],
+} satisfies Record<string, (paths: string[]) => string[]>;
+
+export function buildRunCommand(framework: string, paths: string[]): string[] {
+  // SAFETY: an unknown framework key just misses the lookup and falls back below
+  const build = RUN_COMMANDS[framework as keyof typeof RUN_COMMANDS] ?? RUN_COMMANDS.playwright;
+  return build(paths);
+}
+
+export async function runTests(framework: string, paths: string[], cwd: string): Promise<number> {
+  const argv = buildRunCommand(framework, paths);
+  const proc = Bun.spawn(argv, { cwd, stdio: ["inherit", "inherit", "inherit"] });
+  return await proc.exited;
+}

package/src/selection-policy.ts

@@ -0,0 +1,20 @@
+import type { TestCase } from "./types.js";
+
+export class SelectionPolicy {
+  decide(
+    probability: number | undefined | null,
+    confidence: number | undefined | null,
+    testChanged: boolean,
+  ): "RUN" | "SKIP" {
+    if (testChanged) return "RUN";
+    if (probability === undefined || probability === null) return "RUN";
+    if (confidence === undefined || confidence === null) return "RUN";
+    if (confidence < 0.5) return "RUN";
+    if (probability < 0.3) return "SKIP";
+    return "RUN";
+  }
+
+  rank(tests: Array<{ test: TestCase; probability: number; confidence: number }>) {
+    return [...tests].sort((a, b) => b.probability - a.probability);
+  }
+}

package/src/sieve.ts

@@ -0,0 +1,191 @@
+import { JevClient, type JevQuestion, type JevResponse } from "./jev-client.js";
+import { ChangeResolver } from "./git-diff.js";
+import { TestDiscovery } from "./test-discovery.js";
+import { ContextBuilder } from "./context-builder.js";
+import { SelectionPolicy } from "./selection-policy.js";
+import type { TestCase, SelectionResult, PipelineResult } from "./types.js";
+
+export class Sieve {
+  private jev: JevClient;
+  private git: ChangeResolver;
+  private discovery: TestDiscovery;
+  private context: ContextBuilder;
+  private policy: SelectionPolicy;
+
+  private cwd: string;
+
+  constructor(cwd?: string, baseRef?: string) {
+    this.cwd = cwd ?? ".";
+    this.jev = new JevClient();
+    this.git = new ChangeResolver(baseRef, this.cwd);
+    this.discovery = new TestDiscovery();
+    this.context = new ContextBuilder();
+    this.policy = new SelectionPolicy();
+  }
+
+  async inspect(framework: string): Promise<PipelineResult> {
+    const change = this.git.resolve();
+    const discovery =
+      framework === "playwright"
+        ? this.discovery.discoverPlaywright(this.cwd)
+        : this.discovery.discoverVitest(this.cwd);
+
+    if (discovery.tests.length === 0) {
+      return {
+        change,
+        discovered: { framework, count: 0, tests: [] },
+        evaluated: [],
+        selected: [],
+        skipped: 0,
+        decision: "RUN",
+      };
+    }
+
+    const state = this.context.buildState(change, discovery.tests);
+    const questions = this.buildQuestions(discovery.tests, change.changedFiles.length === 0);
+    let response: JevResponse;
+    try {
+      response = await this.jev.evaluate(state, questions);
+    } catch {
+      return {
+        change,
+        discovered: { framework, count: discovery.tests.length, tests: discovery.tests },
+        evaluated: [],
+        selected: [],
+        skipped: 0,
+        decision: "RUN",
+      };
+    }
+
+    const evaluated = discovery.tests.map((test, _i) => {
+      const answer = response.answers[test.identity.hash];
+      const probability = extractNoul(answer);
+      const confidence = extractConfidence(answer);
+      return { test, probability, confidence };
+    });
+
+    const ranked = this.policy.rank(evaluated);
+    const selected = ranked
+      .filter((e) => this.policy.decide(e.probability, e.confidence, false) === "RUN")
+      .map((e) => e.test);
+
+    return {
+      change,
+      discovered: { framework, count: discovery.tests.length, tests: discovery.tests },
+      evaluated,
+      selected,
+      skipped: discovery.tests.length - selected.length,
+      decision: "RUN",
+    };
+  }
+
+  async select(framework: string, changedOnly: boolean = false): Promise<SelectionResult> {
+    const change = changedOnly ? this.git.resolveChangedOnly() : this.git.resolve();
+    const discovery =
+      framework === "playwright"
+        ? this.discovery.discoverPlaywright(this.cwd)
+        : this.discovery.discoverVitest(this.cwd);
+
+    const tests = discovery.tests;
+    if (tests.length === 0) {
+      return {
+        command: "select",
+        args: [framework],
+        status: "complete",
+        totalTests: 0,
+        selectedTests: [],
+        skippedTests: 0,
+        runTests: [],
+        changedFiles: change.changedFiles,
+        diff: change.diff,
+      };
+    }
+
+    const state = this.context.buildState(change, tests);
+    const questions = this.buildQuestions(tests, change.changedFiles.length === 0);
+    let response: JevResponse;
+    try {
+      response = await this.jev.evaluate(state, questions);
+    } catch (error) {
+      return {
+        command: "select",
+        args: [framework],
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+        totalTests: tests.length,
+        selectedTests: tests,
+        skippedTests: 0,
+        runTests: tests,
+        changedFiles: change.changedFiles,
+        diff: change.diff,
+      };
+    }
+
+    const evaluated = tests.map((test, _i) => {
+      const answer = response.answers[test.identity.hash];
+      return {
+        test,
+        probability: extractNoul(answer),
+        confidence: extractConfidence(answer),
+      };
+    });
+
+    const ranked = this.policy.rank(evaluated);
+    const runTests: TestCase[] = [];
+    const skipTests: TestCase[] = [];
+
+    for (const entry of ranked) {
+      if (this.policy.decide(entry.probability, entry.confidence, false) === "RUN") {
+        runTests.push(entry.test);
+      } else {
+        skipTests.push(entry.test);
+      }
+    }
+
+    return {
+      command: "select",
+      args: [framework],
+      status: "complete",
+      totalTests: tests.length,
+      selectedTests: runTests,
+      skippedTests: skipTests.length,
+      runTests,
+      changedFiles: change.changedFiles,
+      diff: change.diff,
+    };
+  }
+
+  private buildQuestions(tests: TestCase[], noChanges: boolean = false) {
+    const questions: Record<string, JevQuestion> = {};
+    for (const test of tests) {
+      questions[test.identity.hash] = {
+        type: "noul",
+        instructions: noChanges
+          ? `No code changes detected. Could ${test.identity.framework} test at ${test.identity.path} still be affected by any latent issue?`
+          : `Could the current code change affect behavior verified by ${test.identity.framework} test at ${test.identity.path}?`,
+      };
+    }
+    return questions;
+  }
+}
+
+function extractNoul(answer: { noul?: number; confidence?: number }): number {
+  return answer.noul ?? 0;
+}
+
+function extractConfidence(answer: { noul?: number; confidence?: number }): number {
+  // The API's "noul" answers carry no explicit confidence field. Derive it
+  // from how decisive the probability itself is: a noul near 0 or 1 is a
+  // confident answer, a noul near 0.5 is genuine uncertainty (fail open).
+  if (answer.confidence !== undefined) return answer.confidence;
+  const noul = answer.noul ?? 0.5;
+  return Math.abs(noul - 0.5) * 2;
+}
+
+export async function runSieve(framework: string, command: string, cwd?: string): Promise<any> {
+  const sieve = new Sieve(cwd);
+  if (command === "inspect") {
+    return await sieve.inspect(framework);
+  }
+  return await sieve.select(framework);
+}

package/src/test-discovery.ts

@@ -0,0 +1,106 @@
+import { readFileSync, existsSync } from "fs";
+import { Glob } from "bun";
+import type { TestCase } from "./types.js";
+
+export interface DiscoveryResult {
+  framework: string;
+  tests: TestCase[];
+  count: number;
+}
+
+const FRAMEWORK_PATTERNS = {
+  playwright: [
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.pw.ts",
+    "**/*.pw.tsx",
+  ],
+  vitest: ["**/*.spec.ts", "**/*.spec.tsx", "**/*.test.ts", "**/*.test.tsx"],
+} satisfies Record<string, string[]>;
+
+export class TestDiscovery {
+  discoverPlaywright(baseDir: string = "."): DiscoveryResult {
+    const testDir = this.readPlaywrightTestDir(baseDir);
+    const scanDir = testDir ? `${baseDir === "." ? "" : `${baseDir}/`}${testDir}` : baseDir;
+    const tests = this.discoverTests("playwright", scanDir);
+    return { framework: "playwright", tests, count: tests.length };
+  }
+
+  private readPlaywrightTestDir(baseDir: string): string | null {
+    for (const name of ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs"]) {
+      const configPath = `${baseDir === "." ? "." : baseDir}/${name}`;
+      if (!existsSync(configPath)) continue;
+      try {
+        const source = readFileSync(configPath, "utf-8");
+        const match = source.match(/testDir\s*:\s*["']([^"']+)["']/);
+        if (match) return match[1].replace(/^\.\//, "");
+      } catch {
+        // fall through to default scan
+      }
+    }
+    return null;
+  }
+
+  discoverVitest(baseDir: string = "."): DiscoveryResult {
+    const tests = this.discoverTests("vitest", baseDir);
+    return { framework: "vitest", tests, count: tests.length };
+  }
+
+  private discoverTests(framework: string, baseDir: string): TestCase[] {
+    const tests: TestCase[] = [];
+    // SAFETY: an unknown framework key just misses the lookup and falls back below
+    const patterns =
+      FRAMEWORK_PATTERNS[framework as keyof typeof FRAMEWORK_PATTERNS] ??
+      FRAMEWORK_PATTERNS.playwright;
+    const seen = new Set<string>();
+
+    for (const pattern of patterns) {
+      const glob = new Glob(pattern);
+      for (const file of glob.scanSync({ cwd: baseDir })) {
+        if (file.includes("node_modules/") || file.includes("dist/")) continue;
+        const path = baseDir === "." ? file : `${baseDir}/${file}`;
+        if (seen.has(path)) continue;
+        seen.add(path);
+        const test = this.extractTest(framework, path);
+        if (test) tests.push(test);
+      }
+    }
+
+    return tests;
+  }
+
+  private extractTest(framework: string, filePath: string): TestCase | null {
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      const dir = filePath.split("/").slice(0, -1).join("/");
+      const filename = filePath.split("/").pop() ?? filePath;
+      const hash = this.hashString(filePath);
+
+      return {
+        identity: {
+          framework,
+          path: filePath,
+          suite: [dir],
+          name: filename,
+          hash,
+        },
+        source,
+        context: source.slice(0, 500),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private hashString(str: string): string {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash).toString(36);
+  }
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+export interface TestIdentity {
+  framework: string;
+  path: string;
+  suite: string[];
+  name: string;
+  hash: string;
+}
+
+export interface TestCase {
+  identity: TestIdentity;
+  source: string;
+  context: string;
+  relevance?: number;
+  decision?: "RUN" | "SKIP";
+}
+
+export interface ChangeContext {
+  base: string;
+  head: string;
+  changedFiles: string[];
+  diff: string;
+  baseRef: string;
+}
+
+export interface TestContext {
+  framework: string;
+  relativePath: string;
+  suite: string[];
+  testName: string;
+  source: string;
+  helperContext: string;
+}
+
+export interface SelectionResult {
+  command: string;
+  args: string[];
+  status: string;
+  error?: string;
+  totalTests: number;
+  selectedTests: TestCase[];
+  skippedTests: number;
+  runTests: TestCase[];
+  decision?: string;
+  changedFiles: string[];
+  diff: string;
+}
+
+export interface PipelineResult {
+  change: ChangeContext;
+  discovered: { framework: string; count: number; tests: TestCase[] };
+  evaluated: Array<{
+    test: TestCase;
+    probability: number;
+    confidence: number;
+  }>;
+  selected: TestCase[];
+  skipped: number;
+  decision: "RUN" | "SKIP";
+}