@diffci.com/diffci 0.1.0-alpha.3

package/dist-client/src/repo/test-discovery.js

@@ -0,0 +1,383 @@
+/**
+ * Test discovery from test-runner configuration (2026-08-23, deepseek-harness benchmark Phase 2).
+ *
+ * Before this module DiffCI recognised a test file purely by the `.test.` / `.spec.` filename
+ * convention, hardcoded in three places (analyzer discovery, graph node flag, impact classification).
+ * On deepseek-harness that silently left 22 `*.snapshot.ts` and 136 `*.e2e.ts` suites - each run by
+ * its own `vitest run --config vitest.<family>.config.ts` CI job - outside the modelled test universe.
+ *
+ * This module reads the repository's OWN declaration of what a test is: the `include` globs of
+ * Vitest/Jest configuration files at the repository root. It is deliberately STATIC - config files
+ * are never imported or executed (they are repo code); string literals are lifted out of
+ * `include: [ ... ]` arrays (and `testMatch` for Jest) by a tolerant scanner. Anything it cannot read
+ * is simply not added, so the worst case is the pre-existing `.test.`/`.spec.` behaviour.
+ *
+ * Families are derived from the filename token between the last two dots (`foo.e2e.ts` -> e2e) -
+ * a convention, not a deepseek-specific rule - and the config file name (`vitest.e2e.config.ts`).
+ * Families matter downstream: a snapshot or e2e file is a real test that can be SELECTED, but it is
+ * executed by a different command (and may need credentials/browsers), so execution validation must
+ * treat families separately. Nothing here changes selection policy; it only widens what counts as a
+ * test. Repositories with no such config, or whose configs only restate `.test.`/`.spec.`, are
+ * unaffected.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { compileIgnoreRegexes, extractTestPatterns, isIgnoredPath, isUnderRoots } from "./runner-universe.js";
+import { join } from "node:path";
+export const DEFAULT_TEST_PATTERNS = [
+    "**/*.test.{ts,tsx,js,jsx,mjs,cjs,mts,cts}",
+    "**/*.spec.{ts,tsx,js,jsx,mjs,cjs,mts,cts}",
+];
+const FAMILY_TOKENS = {
+    test: "unit", spec: "unit", unit: "unit",
+    snapshot: "snapshot", snap: "snapshot",
+    e2e: "e2e",
+    integration: "integration", int: "integration", it: "integration",
+    bench: "benchmark", benchmark: "benchmark", perf: "benchmark",
+};
+/** Family of a test file from its filename token: `name.<token>.<ext>`. Undefined when the file has
+ * no recognised token (then it is only a test if a config include says so; treated as "unit"). */
+export function testFamilyOfPath(filePath) {
+    const base = filePath.slice(filePath.lastIndexOf("/") + 1);
+    const parts = base.split(".");
+    if (parts.length < 3)
+        return undefined;
+    const token = parts[parts.length - 2].toLowerCase();
+    return FAMILY_TOKENS[token];
+}
+function familyOfConfigName(file) {
+    // vitest.<token>.config.ts / jest.<token>.config.js -> token; plain vitest.config.ts -> undefined
+    const m = /^(?:vitest|jest)\.([a-z0-9-]+)\.config\./i.exec(file);
+    if (!m)
+        return undefined;
+    const token = m[1].toLowerCase();
+    if (token in FAMILY_TOKENS)
+        return FAMILY_TOKENS[token];
+    if (token.includes("e2e"))
+        return "e2e";
+    if (token.includes("snapshot"))
+        return "snapshot";
+    if (token.includes("integration"))
+        return "integration";
+    return undefined; // e.g. "web", "web-stress": family comes from each file's token instead
+}
+const CONFIG_NAME = /^(vitest|jest)(\.[a-z0-9-]+)?\.config\.(ts|mts|cts|js|mjs|cjs)$/i;
+/**
+ * Lift string literals out of `include: [ ... ]` / `testMatch: [ ... ]` arrays. Tolerates spreads,
+ * comments and conditional entries inside the array (their literals are lifted too - over-inclusion
+ * only makes MORE files count as tests, never fewer). Also follows one level of indirection:
+ * `include: someIdent` where `const someIdent = [ ... ]` is declared in the same file.
+ */
+/** Removes JS comments while leaving string literals untouched - a naive regex would eat the `/**\/`
+ * inside a glob like `tests/**\/*.spec.ts`. */
+export function stripComments(source) {
+    let out = "";
+    let i = 0;
+    let quote;
+    while (i < source.length) {
+        const ch = source[i];
+        const next = source[i + 1];
+        if (quote) {
+            out += ch;
+            if (ch === "\\" && next !== undefined) {
+                out += next;
+                i += 2;
+                continue;
+            }
+            if (ch === quote)
+                quote = undefined;
+            i++;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === "`") {
+            quote = ch;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < source.length && source[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            const end = source.indexOf("*/", i + 2);
+            i = end === -1 ? source.length : end + 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+/** Blanks `coverage: { ... }` blocks: their `include` lists INSTRUMENTED SOURCE files, not tests, and
+ * lifting them would mark every source file as a test (observed on deepseek-harness: +1,382 files). */
+export function blankCoverageBlocks(source) {
+    let out = source;
+    for (let guard = 0; guard < 32; guard++) {
+        const m = /\bcoverage\s*:\s*\{/.exec(out);
+        if (!m)
+            break;
+        const open = m.index + m[0].length - 1;
+        let depth = 0;
+        let close = -1;
+        for (let i = open; i < out.length; i++) {
+            if (out[i] === "{")
+                depth++;
+            else if (out[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    close = i;
+                    break;
+                }
+            }
+        }
+        if (close === -1)
+            break;
+        out = out.slice(0, m.index) + " ".repeat(close + 1 - m.index) + out.slice(close + 1);
+    }
+    return out;
+}
+export function extractIncludeGlobs(source) {
+    const stripped = blankCoverageBlocks(stripComments(source));
+    // Bracket-depth aware: returns the body of the array literal opening at `open` (index of "[").
+    const arrayBodyAt = (open) => {
+        let depth = 0;
+        for (let i = open; i < stripped.length; i++) {
+            const ch = stripped[i];
+            if (ch === "[")
+                depth++;
+            else if (ch === "]") {
+                depth--;
+                if (depth === 0)
+                    return stripped.slice(open + 1, i);
+            }
+        }
+        return undefined;
+    };
+    const arrays = new Map();
+    for (const m of stripped.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*\[/g)) {
+        const body = arrayBodyAt(m.index + m[0].length - 1);
+        if (body !== undefined)
+            arrays.set(m[1], body);
+    }
+    const globs = [];
+    const lift = (body) => { for (const s of body.matchAll(/['"`]([^'"`\n]+)['"`]/g))
+        globs.push(s[1]); };
+    for (const m of stripped.matchAll(/\b(?:include|testMatch)\s*:\s*(\[|([A-Za-z_$][\w$]*))/g)) {
+        if (m[1] === "[") {
+            const body = arrayBodyAt(m.index + m[0].length - 1);
+            if (body !== undefined)
+                lift(body);
+        }
+        else if (m[2] && arrays.has(m[2]))
+            lift(arrays.get(m[2]));
+    }
+    // Only keep things that look like file globs (contain a slash or a glob char) - drops e.g. env names
+    return Array.from(new Set(globs.filter((g) => /[*/]/.test(g) && !g.startsWith("!"))));
+}
+function scriptsInvoking(scripts, runner, configFile, isDefault) {
+    const result = [];
+    for (const [name, cmd] of Object.entries(scripts)) {
+        if (!new RegExp(`\\b${runner}\\b`).test(cmd))
+            continue;
+        const cfg = /--config(?:=|\s+)(\S+)/.exec(cmd)?.[1];
+        if (cfg ? cfg === configFile || cfg.endsWith(`/${configFile}`) : isDefault)
+            result.push(name);
+    }
+    return result.sort();
+}
+/** Static discovery of test-runner configs at the repository root. Never throws; never executes. */
+export function discoverTestRunnerConfigs(repoPath, scripts = {}) {
+    const configs = [];
+    let entries = [];
+    try {
+        entries = existsSync(repoPath) ? readdirSync(repoPath) : [];
+    }
+    catch {
+        entries = [];
+    }
+    for (const name of entries.sort()) {
+        const m = CONFIG_NAME.exec(name);
+        if (!m)
+            continue;
+        const full = join(repoPath, name);
+        try {
+            if (!statSync(full).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let source = "";
+        try {
+            source = readFileSync(full, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const runner = m[1].toLowerCase();
+        const isDefault = m[2] === undefined;
+        const extracted = extractTestPatterns(source);
+        configs.push({
+            file: name,
+            runner,
+            includes: extracted.includes,
+            scripts: scriptsInvoking(scripts, runner, name, isDefault),
+            family: familyOfConfigName(name),
+            excludeGlobs: extracted.excludeGlobs,
+            ignoreRegexSources: extracted.ignoreRegexSources,
+            roots: extracted.roots,
+            declaresTests: extracted.declaresTests,
+            isDefault,
+            authoritative: extracted.declaresTests && extracted.complete && extracted.includes.length > 0,
+        });
+    }
+    // THE REPLACEMENT RULE, and it is deliberately narrow.
+    //
+    // Only the DEFAULT config (`jest.config.ts`, `vitest.config.ts`) describes what the bare runner
+    // executes, so only the default config may replace the runner built-in globs. A named variant
+    // (`vitest.e2e.config.ts`) is a SEPARATE job: it ADDS its includes and says nothing about what
+    // plain `vitest` runs. Treating a variant as authority over the default universe would drop every
+    // `*.spec.ts` in a repository whose only config file happens to be an e2e one - narrowing on
+    // evidence that does not bear on the question.
+    //
+    // And the default config must have been COMPLETELY understood. Wrong-wide costs compute;
+    // wrong-narrow can hide a test the runner executes, which is the shape of a false green. Every
+    // ambiguity resolves wide.
+    const defaults = configs.filter((c) => c.isDefault);
+    const replacedDefaults = defaults.length > 0 && defaults.every((c) => c.authoritative);
+    const patterns = new Set(replacedDefaults ? [] : DEFAULT_TEST_PATTERNS);
+    for (const c of configs)
+        for (const g of c.includes)
+            patterns.add(g);
+    // Excludes, ignores and roots are NARROWING, so they are honoured only from configs whose
+    // declaration was fully understood - and only when the declaration is actually in force.
+    // Narrowing metadata is honoured ONLY from an authoritative DEFAULT config. A variant roots or
+    // ignore list governs that variant own job, and applying it repository-wide would over-narrow.
+    const authoritative = replacedDefaults ? defaults : [];
+    return {
+        configs,
+        patterns: Array.from(patterns),
+        replacedDefaults,
+        excludeGlobs: Array.from(new Set(authoritative.flatMap((c) => c.excludeGlobs))),
+        ignoreRegexSources: Array.from(new Set(authoritative.flatMap((c) => c.ignoreRegexSources))),
+        roots: Array.from(new Set(authoritative.flatMap((c) => c.roots))),
+    };
+}
+// --- glob matching (shared by analyzer / graph / impact so "is this a test?" has ONE answer) ---
+function expandBraces(pattern) {
+    const match = /\{([^{}]*)\}/.exec(pattern);
+    if (!match)
+        return [pattern];
+    const prefix = pattern.slice(0, match.index);
+    const suffix = pattern.slice(match.index + match[0].length);
+    const out = [];
+    for (const alt of match[1].split(","))
+        out.push(...expandBraces(`${prefix}${alt}${suffix}`));
+    return out;
+}
+function escapeRegexLiteral(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Extended-glob groups - `?(a|b)`, `*(a|b)`, `+(a|b)`, `@(a|b)` - are not exotic: they appear in the
+ * published default include globs of both vitest (`**\/*.{test,spec}.?(c|m)[jt]s?(x)`) and jest, and
+ * in every config that copies them. Passed through to `RegExp` unchanged, `?(x)` reads as "an
+ * optional preceding character, then a literal x", so `__tests__/base.js` matched nothing at all.
+ * Measured cost before this fix (Phase 01 baseline, 2026-08-26): immerjs/immer discovered ZERO test
+ * files from its own explicit `include: ["**\/__tests__\/**\/*.[jt]s?(x)"]`, while still classifying
+ * 5 of 5 commits SELECTIVE at COMPLETE confidence.
+ *
+ * `!(...)` (negation) is deliberately not modelled - it needs real parsing to be correct. It is
+ * widened to "any single path segment", which OVER-includes. Over-inclusion counts extra files as
+ * tests; under-inclusion silently empties the test universe. The former is the safe direction.
+ *
+ * A bare `?` outside a group is a single-character wildcard (`[^/]`), which it also was not: it
+ * previously reached the regex as a quantifier over whatever preceded it.
+ */
+/**
+ * Wildcards inside an extglob body, translated by the same rules as the rest of the pattern.
+ *
+ * `?(*.)` in jest's `**\/?(*.)+(spec|test).[jt]s?(x)` means "optionally: anything, then a dot". The
+ * body is a glob in its own right, so escaping it as a literal turns it into "optionally the two
+ * characters `*` and `.`" - which no real path contains, so `src/foo.test.js` matched NOTHING while
+ * the bare `test.js` still matched. Found 2026-08-30 while diagnosing Prettier, where it was one of
+ * two defects in the same area (see the duplicate matcher deleted from impact.ts).
+ *
+ * Bracket expressions such as `[jt]` are left alone deliberately: they are already valid regex
+ * character classes and mean the same thing in both syntaxes.
+ */
+function translateExtglobBody(body) {
+    return body.replace(/\\/g, "\\\\").replace(/\./g, "\\.").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+}
+function globToRegex(pattern) {
+    // Extglob bodies contain `*`, `?` and `|` that must not be rewritten by the wildcard rules below,
+    // so they are lifted out behind placeholders first and restored last.
+    const groups = [];
+    let working = pattern.replace(/([?*+@!])\(([^()]*)\)/g, (_match, operator, body) => {
+        const alternatives = body.split("|").map(translateExtglobBody).join("|");
+        const source = operator === "!"
+            ? "[^/]*"
+            : `(?:${alternatives})${operator === "?" ? "?" : operator === "*" ? "*" : operator === "+" ? "+" : ""}`;
+        groups.push(source);
+        return `\0X${groups.length - 1}\0`;
+    });
+    working = working.replace(/\\/g, "\\\\").replace(/\./g, "\\.");
+    working = working
+        .replace(/\*\*\//g, "\0GS\0")
+        .replace(/\/\*\*/g, "\0SG\0")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/\0GS\0/g, "(?:.*/)?")
+        .replace(/\0SG\0/g, "(?:/.*)?");
+    working = working.replace(/\0X(\d+)\0/g, (_match, index) => groups[Number(index)]);
+    return new RegExp(`^${working}$`);
+}
+/** Matches a repo-relative posix path against one glob, with brace and extglob support. Exported so
+ * analyzer discovery, graph node flags and impact classification all share ONE definition of a
+ * match rather than the two near-identical copies that existed before Phase 01. */
+export function matchesGlob(path, pattern) {
+    return expandBraces(pattern).some((p) => globToRegex(p).test(path));
+}
+function compile(patterns) {
+    return patterns.flatMap((p) => expandBraces(p.includes("/") ? p : `**/${p}`)).map(globToRegex);
+}
+/** Builds a matcher over repo-relative posix paths. Patterns without a slash (bare filename globs)
+ * are treated as `**\/<pattern>` so a config's `*.spec.ts` still means "anywhere". */
+export function createTestFileMatcher(patterns, options = {}) {
+    const regexes = compile(patterns);
+    const excludes = compile(options.excludePatterns ?? []);
+    const authoritative = compile(options.authoritativePatterns ?? []);
+    const ignoreRegexes = options.ignoreRegexes ?? [];
+    const roots = options.roots ?? [];
+    const fn = ((path) => {
+        // Runner-universe vetoes come FIRST, ahead of even the authoritative patterns. A file the
+        // configured runner will not execute is not a test DiffCI can select, however strongly
+        // DiffCI conventions or the repository own include globs say it looks like one.
+        if (!isUnderRoots(path, roots))
+            return false;
+        if (isIgnoredPath(path, ignoreRegexes))
+            return false;
+        if (authoritative.some((r) => r.test(path)))
+            return true;
+        if (excludes.some((r) => r.test(path)))
+            return false;
+        return regexes.some((r) => r.test(path));
+    });
+    Object.defineProperty(fn, "patterns", { value: Object.freeze([...patterns]) });
+    return fn;
+}
+/** The one place that turns a profile into a matcher, so analyzer discovery, graph node flags and
+ * impact classification cannot disagree about what a test is. */
+export function testFileMatcherForProfile(profile) {
+    if (!profile.testPatterns)
+        return DEFAULT_TEST_FILE_MATCHER;
+    return createTestFileMatcher(profile.testPatterns, {
+        excludePatterns: profile.testExcludePatterns,
+        authoritativePatterns: profile.testAuthoritativePatterns,
+        ignoreRegexes: compileIgnoreRegexes(profile.testIgnoreRegexSources ?? []),
+        roots: profile.testRoots,
+    });
+}
+/** The pre-2026-08-23 behaviour, kept as the fallback when no profile is available. */
+export const DEFAULT_TEST_FILE_MATCHER = createTestFileMatcher(DEFAULT_TEST_PATTERNS);

package/dist-client/src/repo/test-fixture-ownership.js

@@ -0,0 +1,76 @@
+/**
+ * Conservative test-fixture ownership (2026-08-23, deepseek-harness benchmark Phase 3).
+ *
+ * Recorded fixtures such as `examples/acp-agent/tests/snapshots/<case>/session.jsonl` are read at
+ * runtime by the suite beside them (`examples/acp-agent/tests/acp.snapshot.ts` builds the directory
+ * from `import.meta.url` + 'snapshots'). The import graph cannot see that edge, so before this module
+ * every such change was "Unknown changed file" -> full fallback (157 files on one deepseek merge).
+ *
+ * These files are TEST INPUTS, never documentation: a change must SELECT the tests that read it, or
+ * a conservative superset, or stay unknown. The relationship is expressed purely structurally:
+ *
+ *   <scope>/<tests-dir>/<fixture-dir>/...   is owned by the test files that live in <scope>/<tests-dir>
+ *
+ * with every step guarded:
+ *   1. the nearest ancestor directory named `tests`, `test` or `__tests__` is the tests dir T;
+ *   2. the segment directly under T must be a fixture directory by name (`snapshots`,
+ *      `goal-snapshots`, `fixtures`, `__fixtures__`, `__snapshots__`, ...) - a `.jsonl` elsewhere
+ *      under T (or outside any tests dir) is NOT claimed;
+ *   3. owners are the recognised test files (profile test patterns) that are DIRECT children of T.
+ *      When the fixture dir is snapshot-named and T has snapshot-family tests, only those are owned
+ *      (a snapshots dir is read by snapshot suites); otherwise all direct test children; if T has no
+ *      direct test children, every recognised test under T/** (wider superset);
+ *   4. if that still yields nothing - or the caller has no HEAD inventory to look in - the result is
+ *      undefined and the file stays "unknown" (fallback). Deleted fixtures resolve against HEAD: the
+ *      tests dir still exists -> its tests are selected; tests dir gone -> unknown.
+ *
+ * Ownership is by directory convention only; nothing here inspects file contents or file extensions,
+ * so the same rule covers `.jsonl`, `.json`, `.txt`, `.expected.*` fixtures alike.
+ */
+import { testFamilyOfPath } from "./test-discovery.js";
+const TESTS_DIR_NAMES = new Set(["tests", "test", "__tests__"]);
+const FIXTURE_DIR = /(^|[-_.])(snapshots?|fixtures?)([-_.]|$)|^__(snapshots|fixtures)__$/i;
+export function resolveTestFixtureOwners(changedPath, isTestFile, repositoryFiles) {
+    if (!repositoryFiles)
+        return undefined;
+    if (isTestFile(changedPath))
+        return undefined; // a test is a test, not a fixture
+    const segments = changedPath.split("/");
+    // nearest tests-dir ancestor (search from the deepest directory upward)
+    let t = -1;
+    for (let i = segments.length - 2; i >= 0; i--) {
+        if (TESTS_DIR_NAMES.has(segments[i])) {
+            t = i;
+            break;
+        }
+    }
+    if (t === -1)
+        return undefined;
+    const fixtureSegment = segments[t + 1];
+    // must be a fixture DIRECTORY (at least one more segment = the file itself), and fixture-named
+    if (fixtureSegment === undefined || t + 1 >= segments.length - 1 || !FIXTURE_DIR.test(fixtureSegment))
+        return undefined;
+    const testsDir = segments.slice(0, t + 1).join("/");
+    const prefix = `${testsDir}/`;
+    const direct = [];
+    const recursive = [];
+    for (const f of repositoryFiles) {
+        if (!f.startsWith(prefix) || !isTestFile(f))
+            continue;
+        recursive.push(f);
+        if (!f.slice(prefix.length).includes("/"))
+            direct.push(f);
+    }
+    if (recursive.length === 0)
+        return undefined;
+    const fixtureDir = `${testsDir}/${fixtureSegment}`;
+    if (direct.length > 0) {
+        if (/snapshot/i.test(fixtureSegment)) {
+            const snapshotOwners = direct.filter((f) => testFamilyOfPath(f) === "snapshot");
+            if (snapshotOwners.length > 0)
+                return { testsDir, fixtureDir, scope: "direct-snapshot-family", owners: snapshotOwners.sort() };
+        }
+        return { testsDir, fixtureDir, scope: "direct", owners: direct.sort() };
+    }
+    return { testsDir, fixtureDir, scope: "recursive", owners: recursive.sort() };
+}

package/dist-client/src/repo/test-framework.js

@@ -0,0 +1,117 @@
+/** End-to-end runners. They are real test frameworks, but a unit-test file that no config claims
+ * should not be routed to one, so they are never chosen as a repository's primary runner. */
+export const END_TO_END_FRAMEWORKS = new Set(["playwright", "cypress"]);
+/** Each framework's own published default include globs, transcribed. */
+export const FRAMEWORK_DEFAULT_INCLUDES = {
+    // vitest: `include` defaults to ['**\/*.{test,spec}.?(c|m)[jt]s?(x)']
+    vitest: ["**/*.{test,spec}.?(c|m)[jt]s?(x)"],
+    // jest: `testMatch` defaults to ["**\/__tests__\/**\/*.[jt]s?(x)", "**\/?(*.)+(spec|test).[jt]s?(x)"]
+    jest: ["**/__tests__/**/*.[jt]s?(x)", "**/?(*.)+(spec|test).[jt]s?(x)"],
+    // mocha: `spec` defaults to './test/*.{js,cjs,mjs}'; TypeScript repositories run the same layout
+    // through a loader, so the TS extensions are included alongside.
+    mocha: ["test/*.{js,cjs,mjs,ts,mts,cts}"],
+    // ava: files defaults to test.js, test-*.js, test/**, **\/__tests__\/**, **\/*.spec.js,
+    // **\/*.test.js (ava also accepts .cjs/.mjs/.ts under its own compilation step).
+    ava: [
+        "test.{js,cjs,mjs,ts}",
+        "test-*.{js,cjs,mjs,ts}",
+        "test/**/*.{js,cjs,mjs,ts}",
+        "**/__tests__/**/*.{js,cjs,mjs,ts}",
+        "**/*.spec.{js,cjs,mjs,ts}",
+        "**/*.test.{js,cjs,mjs,ts}",
+    ],
+    // tap: defaults to test/ and tap-snapshots/, plus *.test.* anywhere.
+    tap: ["test/**/*.{js,cjs,mjs,ts,mts,cts}", "**/*.test.{js,cjs,mjs,ts,mts,cts}"],
+    // node:test: the runner's own default discovery is **\/*.test.?(c|m)[jt]s plus files under a
+    // test/ directory.
+    "node:test": ["**/*.test.?(c|m)[jt]s", "test/**/*.{js,cjs,mjs,ts,mts,cts}"],
+    // jasmine: `spec_files` defaults to "**\/*[sS]pec.?(m)js", resolved under `spec_dir` ("spec").
+    jasmine: ["spec/**/*[sS]pec.?(m)js", "**/*[sS]pec.{js,mjs,ts}"],
+    // bun test: discovers *.test.{js,jsx,ts,tsx}, *_test.*, *.spec.* and *_spec.*
+    "bun:test": ["**/*.{test,spec}.{js,jsx,ts,tsx}", "**/*_{test,spec}.{js,jsx,ts,tsx}"],
+    // playwright: `testMatch` defaults to **\/*.@(spec|test).?(c|m)[jt]s?(x)
+    playwright: ["**/*.@(spec|test).?(c|m)[jt]s?(x)"],
+    // cypress: `specPattern` defaults to cypress/e2e/**\/*.cy.{js,jsx,ts,tsx}
+    cypress: ["cypress/e2e/**/*.cy.{js,jsx,ts,tsx}", "**/*.cy.{js,jsx,ts,tsx}"],
+};
+const MARKERS = [
+    { framework: "vitest", packages: ["vitest"], script: /(?:^|[\s;&|])vitest(?:$|[\s;&|])/ },
+    { framework: "jest", packages: ["jest", "ts-jest", "@swc/jest", "jest-cli"], script: /(?:^|[\s;&|/])jest(?:$|[\s;&|])/ },
+    { framework: "mocha", packages: ["mocha", "ts-mocha"], script: /(?:^|[\s;&|/])mocha(?:$|[\s;&|])/ },
+    { framework: "ava", packages: ["ava"], script: /(?:^|[\s;&|/])ava(?:$|[\s;&|])/ },
+    { framework: "tap", packages: ["tap", "libtap"], script: /(?:^|[\s;&|/])tap(?:$|[\s;&|])/ },
+    { framework: "node:test", packages: [], script: /(?:node|tsx)\s[^;&|]*--test(?:$|[\s;&|=])/ },
+    { framework: "jasmine", packages: ["jasmine", "jasmine-core"], script: /(?:^|[\s;&|/])jasmine(?:$|[\s;&|])/ },
+    { framework: "bun:test", packages: [], script: /(?:^|[\s;&|])bun\s+test(?:$|[\s;&|])/ },
+    // End-to-end runners last, so that a repository with both gets a unit-test runner as its primary.
+    { framework: "playwright", packages: ["@playwright/test", "playwright"], script: /(?:^|[\s;&|/])playwright(?:$|[\s;&|])/ },
+    { framework: "cypress", packages: ["cypress"], script: /(?:^|[\s;&|/])cypress(?:$|[\s;&|])/ },
+];
+/**
+ * Frameworks the repository declares. A dependency is stronger evidence than a script mention, but
+ * either is sufficient - a monorepo root often runs a framework it does not itself depend on, and a
+ * repository can depend on a framework it invokes only through a wrapper.
+ */
+export function detectDeclaredFrameworks(packageJson) {
+    if (!packageJson)
+        return { frameworks: [], evidence: {} };
+    const deps = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
+    const scripts = packageJson.scripts ?? {};
+    const frameworks = [];
+    const evidence = {};
+    for (const marker of MARKERS) {
+        const declaredPackage = marker.packages.find((p) => deps[p] !== undefined);
+        if (declaredPackage !== undefined) {
+            frameworks.push(marker.framework);
+            evidence[marker.framework] = `dependency:${declaredPackage}`;
+            continue;
+        }
+        const scriptEntry = Object.entries(scripts).find(([, command]) => marker.script.test(command));
+        if (scriptEntry) {
+            frameworks.push(marker.framework);
+            evidence[marker.framework] = `script:${scriptEntry[0]}`;
+        }
+    }
+    return { frameworks, evidence };
+}
+/**
+ * Each framework's own published default EXCLUDES, transcribed - the other half of the defaults, and
+ * not optional. ava's defaults exclude `**\/fixtures\/**` and `**\/helpers\/**`; without that,
+ * `sindresorhus/execa` reports 337 test files where 193 of them are process fixtures ava would never
+ * run (measured 2026-08-26). An inflated test universe is a wrong denominator in every downstream
+ * savings figure, so "over-include and move on" is not good enough here.
+ *
+ * These apply only to files a framework's DEFAULT includes pulled in. A file that matches DiffCI's
+ * conventional `.test.`/`.spec.` patterns, or a glob the repository declared explicitly in its own
+ * config, is a test regardless of where it sits - the repository said so.
+ */
+export const FRAMEWORK_DEFAULT_EXCLUDES = {
+    vitest: ["**/node_modules/**", "**/dist/**", "**/cypress/**"],
+    jest: ["**/node_modules/**"],
+    mocha: ["**/node_modules/**"],
+    ava: ["**/fixtures/**", "**/helpers/**", "**/__helper__/**", "**/node_modules/**"],
+    tap: ["**/fixtures/**", "**/node_modules/**"],
+    "node:test": ["**/node_modules/**"],
+    jasmine: ["**/node_modules/**"],
+    "bun:test": ["**/node_modules/**"],
+    playwright: ["**/node_modules/**"],
+    cypress: ["**/node_modules/**", "**/cypress/support/**", "**/cypress/fixtures/**"],
+};
+/** The union of every declared framework's default include globs. */
+export function defaultIncludesFor(frameworks) {
+    const patterns = new Set();
+    for (const framework of frameworks) {
+        for (const pattern of FRAMEWORK_DEFAULT_INCLUDES[framework])
+            patterns.add(pattern);
+    }
+    return Array.from(patterns);
+}
+/** The union of every declared framework's default exclude globs. */
+export function defaultExcludesFor(frameworks) {
+    const patterns = new Set();
+    for (const framework of frameworks) {
+        for (const pattern of FRAMEWORK_DEFAULT_EXCLUDES[framework])
+            patterns.add(pattern);
+    }
+    return Array.from(patterns);
+}

package/dist-client/src/repo/types.js

@@ -0,0 +1 @@
+export {};

package/docs/distribution.md

@@ -0,0 +1,81 @@
+# DiffCI Distribution
+
+DiffCI has three install surfaces with the same initial contract: observe CI, write a report, and do
+not change what the host repository runs.
+
+## GitHub App
+
+The DiffCI Shadow GitHub App is the lowest-friction research and design-partner path. It receives
+repository events, runs shadow analysis outside the repository's CI jobs, and reconciles predictions
+against real CI outcomes. Use it when a maintainer wants observation without adding a workflow step.
+
+## GitHub Action
+
+The GitHub Action is the OSS dependency-graph path. A repository installs DiffCI as its own
+continue-on-error job:
+
+```yaml
+jobs:
+  diffci:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: DiffCI/DiffCI.com@v1
+```
+
+For the strongest supply-chain posture, pin the Action to a full commit SHA. `npx @diffci.com/diffci verify-workflow`
+checks that the job is dedicated, read-only, not required by other jobs, and unable to alter the rest
+of CI.
+
+## npm CLI
+
+The CLI is the standalone npm package surface. The package name is `@diffci.com/diffci`:
+
+```bash
+npx @diffci.com/diffci observe
+npx @diffci.com/diffci verify-workflow
+```
+
+`observe` writes a JSON report outside the checkout by default. It never runs, skips, cancels, or
+reorders tests. A hosted endpoint is opt-in: reports are sent only when both `DIFFCI_API_URL` and
+`DIFFCI_TOKEN` are set, or when equivalent CLI flags are passed.
+
+## Report Shape
+
+A shadow report should answer the adoption question before it asks for operational trust:
+
+```text
+DiffCI - last 30 days
+
+CI runs observed                 423
+Compute time                    18,240 min
+Potentially avoidable           6,810 min
+Potential reduction             37.3%
+
+Estimated compute avoided       xxx CPU-hours
+Estimated electricity           xxx kWh
+Estimated CO2                   xxx kg
+Estimated water                 xxx L
+```
+
+That makes the open-source proposition explicit: install DiffCI Shadow, change nothing in CI, and learn
+how much compute may be wasted.
+
+## Future Package Managers
+
+npm plus the GitHub Action are enough to establish the pattern. Later package surfaces can wrap the
+same observer contract:
+
+```bash
+pip install diffci
+cargo install diffci
+brew install diffci
+```
+
+Those should ship only after the npm CLI and Action have signed releases, provenance, pinned build
+workflows, and repeatable package verification.