bivium

只运行变更可能影响的测试，不要错过任何一个。

Bivium为存储库构建一个静态的、文件级的依赖关系图，并将其从更改所涉及的文件回溯到到达这些文件的测试。它关闭失败：任何它不能读取的东西（非文字） import()（未解析的说明符，没有声明输入的磁盘读取）计数取决于所有内容，并且它无法进行的更改运行整个套件，这是有原因的。它挑选测试；你的跑步者负责跑步。

它没有依赖关系，也不需要安装它计划的存储库：它从不读取git索引和工作树 node_modules． CI可以在跳过安装的作业中进行计划，并跳过选择为 none． 它运行在Node≥22和Bun上。它是从 carbon-components-svelte的 test:changed.

bun add -d bivium

// bivium.config.ts
import { defineConfig } from "bivium";

export default defineConfig({
  suites: {
    unit: { tests: "tests/**/*.test.ts", run: "vitest run {files}", root: "tests" },
    e2e: {
      tests: "e2e/**/*.test.ts",
      run: "playwright test {files}",
      root: "e2e",
      urls: { "/*": "e2e/fixtures/*" }, // page.goto("/x.html") → e2e/fixtures/x.html
    },
  },
  roots: ["src", "tests", "e2e"], // a changed file outside them runs everything
  ignore: ["**/*.md", "docs/**"],
});

$ bunx bivium plan
unit tests: 3 of 12 files
  tests/Button.test.ts
  tests/Modal.test.ts
  tests/css/unknown.test.ts
e2e tests: none
$ bunx bivium run --suite unit     # vitest run tests/Button.test.ts …

它写的是什么？

一遍词法分析器读取JavaScript和TypeScript (.js， .ts， .jsx， .tsx，以及他们的 m/c 的脚本和标记表达式 .svelte，剧本 .vue， .astro 和 .html，和 script[src]， link[href] 和 iframe[src] 的 .html． 只有代码才算数：在字符串或注释中拼写的import不加边。

一个根 bun.lock， package-lock.json 或者 pnpm-lock.yaml 不是源文件：对其中一个文件的更改会产生它所更改的包的种子(参见 Lockfiles）。

不能清晰地lex的文件由regex提取器读取，这是过度近似的。CSS不会被扫描：生成的样式表通过 edges，和 窄 可以做得更好。

配置

bivium.config.ts (或 .mts， .mjs， .js， .json)，或者 --config <file>． 一个 .ts 配置需要Bun或Node≥22.18。每个glob键取一个glob或一个列表。未知的键是错误的，因为拼写错误的键会悄悄地选择更少的键。

测试无法达到的变化

套房下的一个更改文件 root 套件的测试没有达到其他方式（一个运行器配置，一个设置文件），所以整个套件运行：孤儿规则。使用默认值 root，整个存储库，任何文件bivium都无法追踪到测试运行套件，这是健全和粗糙的。集 root 在每个套件的测试和源代码所在的目录中，说明其余部分是什么：

外面的文件 roots 没有被忽视的运行一切：它是连接图无法看到的支撑，例如CI工作流。

食谱

玩笑还是玩笑。 命名运行程序加载的安装文件，mirror resolve.alias a我很喜欢 "@/" 像编写的那样工作)，为他们的测试提供快照，并且，对于运行代码的套件，跳过仅类型的边缘：

suites: {
  unit: {
    tests: "src/**/*.test.{ts,tsx}",
    run: "vitest run {files}",
    root: "src",
    setup: ["src/setupTests.ts"], // vitest.config.ts `setupFiles`
    wiring: ["vitest.config.ts"],
    types: false,
    nonInputs: ["src/**/types.ts"], // types only: nothing loads them at runtime
  },
},
alias: { "@/": "src/" },
reads: { "src/**/*.test.{ts,tsx}": "src/$1__snapshots__/$2.test.$3.snap" },

tsconfig paths ( vite-tsconfig-paths read)是不带an的 alias． 一个无广延性的 vi.mock("@/x") 像导入一样解析。运行程序按名称加载的测试环境(jsdom， happy-dom)进去了 loadedByName 如果你设置它。

规划工作区。 工作区包通过它们的 package.json exports，和 .js 指定符转换为一个(@acme/ui/Button.js)达到它的 .ts 源。一个 pnpm-lock.yaml Change通过它所更改的包进行选择。集 roots 到套件应该看到其更改的包和应用程序，以及每个测试运行器的套件。

剧作家。 地图 page.goto() 它们打开的页面的url urls，只列出一页 goto() 打开在 pages，及名称 playwright.config.ts 在 wiring：

e2e: {
  tests: "e2e/**/*.spec.ts",
  root: "e2e",
  urls: { "/*": "e2e/fixtures/*.html" },
  wiring: ["playwright.config.ts"],
},

生成的代码。 将内容或类型生成器写入被忽略的目录(.velite， .contentlayer/generated)是一个 edges 从写到读的条目： { ".velite/*": ["content/**", "velite.config.ts"] }． 的进口 #velite 或者 ../.velite 然后到达内容，而不是每一个变化。

Lockfiles

依赖关系会改变一个锁文件，而没有文件会导入它。当一个根 bun.lock， package-lock.json （v2或v3）或 pnpm-lock.yaml （v6或v9）更改后，bivium将其与合并基础进行区分，并使用 pkg: 条目发生变化的包的节点，以及依赖于其中一个包的每个包的节点，所以a svelte Bump选择导入的内容 svelte，或者在此基础上构建的软件包。一个 package.json 其唯一的变化是依赖，lockfile记录的方式与那些包的变化相同。

更改后的包还可以以图中看不到的方式使用：测试生成的CLI、运行器、类型包。所以当一个包发生变化时 package.json 声明，或者一些文件导入，而没有测试导入，一切都运行，原因是(bun.lock: playwright 1.63.0 → 1.64.0, and no test imports it)，除非包裹是 inert． 与 loadedByName 集，只包带一个 bin 在lockfile中，或它所列出的文件中，以这种方式计数：仅到达CMS配置导入库的碰撞不选择任何内容。对于一个bivium无法解析的lockfile，它的设置（除了它的包之外）也可以运行。overrides补丁，pnpm settings， catalogs（或PNPM本身的版本），以及 package.json 更改lockfile不记录。其他锁档(yarn.lock， bun.lockb)是和其他文件一样的文件：在根目录之外，对一个文件的修改会运行所有文件。

$ bunx bivium plan
bun.lock: @biomejs/biome 2.5.14 → 2.6.3, inert
bun.lock: svelte 5.57.1 → 5.57.2
unit tests: 4 of 12 files
…

注释

命令行界面

--config， --cwd 和 --no-cache 使用每个命令，在它之前或之后，和 why 和 check 采取 --base <ref>. --help (或 -h)打印使用情况。一个未知的命令、选项或 --format 是一个错误。退出状态：完成时为0，完成时为1 check 查找问题，2用于查找使用或配置错误； run 带着命令的状态退出。

why 按拼法命名每条边： import， type (一个 import type， export type … from（JSDoc类型，或与声明文件之间的边）， setup （一个套件的安装文件）， goto (一个页面 page.goto() 打开), html (一个HTML页面加载的模块： script[src]， link[href]， iframe[src] 或者内联脚本的import)， name （绑定到桶名的命名导入）和 export （导出它的文件）， glob （import.meta.glob)， depends-on， edges (配置) reads 和 lists.

$ bunx bivium why e2e/accordion.test.ts
e2e/accordion.test.ts
└─ goto    e2e/fixtures/accordion.html             e2e/accordion.test.ts:13
   └─ html    e2e/fixtures/accordion.ts            e2e/fixtures/accordion.html:10
      └─ import  e2e/fixtures/Fixture.svelte       e2e/fixtures/accordion.ts:1
         └─ name    src/index.js#AccordionItem     e2e/fixtures/Fixture.svelte:2
            └─ export  src/AccordionItem.svelte    src/index.js:2
               ● changed
+ 1 more change reaches this test: css/_accordion.scss (--all shows each chain)

$ bunx bivium why e2e/accordion.test.ts --format chain
src/AccordionItem.svelte changed
  exported as AccordionItem  src/index.js:2
  imported by                e2e/fixtures/Fixture.svelte:2
  imported by                e2e/fixtures/accordion.ts:1
  loaded by page             e2e/fixtures/accordion.html:10
  opened by                  e2e/accordion.test.ts:13  ← selected
+ 1 more change reaches this test: css/_accordion.scss (--all shows each chain)

$ bunx bivium why e2e/accordion.test.ts --format source
selected: e2e/accordion.test.ts ← src/AccordionItem.svelte (5 hops)

  --> e2e/accordion.test.ts:13  goto
13 | await page.goto("/accordion.html");
  --> e2e/fixtures/accordion.html:10  html
10 | <script type="module" src="./accordion.ts"></script>
  --> e2e/fixtures/accordion.ts:1  import
 1 | import Fixture from "./Fixture.svelte";
  --> e2e/fixtures/Fixture.svelte:2  name
 2 | import { Accordion, AccordionItem } from "carbon-components-svelte";
  --> src/index.js:2  export
 2 | export { default as AccordionItem } from "./AccordionItem.svelte";
  ● src/AccordionItem.svelte: changed
+ 1 more change reaches this test: css/_accordion.scss (--all shows each chain)

对于一个依赖于每一个变化的测试， chain 说明为什么，在哪里，以及如何修复它，如 check :

$ bunx bivium why tests/e2e.test.ts --format chain
tests/e2e.test.ts runs on every change
  because scripts/launcher.js:10  unresolved "./cli-entry.js"
    fix: no file at that path: fix the import, or add an `edges` entry if a build generates it
  reached via scripts/launcher.js
    depended on by  scripts/build.ts:1
    depended on by  tests/e2e.test.ts:2  ← selected

死着

一个错字就 @depends-on，或者只指向计划器跳过的文件，看起来很好，但从不选择它的文件。 check 评估每一个 @depends-on， @reads， @lists 和 import.meta.glob 模式,每 edges 和 reads 价值，每个套房 setup，针对git列出的每个文件（跟踪的和未跟踪的，是否在根目录中），并报告其中一个：

带有capture的配置值只有在其键匹配的每个文件都不匹配时才会失效，并且在配置文件下也会报告与图读取的文件不匹配的键。图读取的被忽略的文件仍然是遍历的种子，而根之外的更改将运行所有内容，因此两者都不是死的。一个故意死掉的球进去 deadGlobs 有一个原因：

deadGlobs: [
  { file: "tests/css/tokens.test.ts", glob: "docs/src/**", reason: "docs-only changes skip CI" },
],

CI

在任何安装之前，计划自己的作业，并为每个套件的作业提供其选择：

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      unit: ${{ steps.plan.outputs.unit-tests }}
      e2e: ${{ steps.plan.outputs.e2e-tests }}
    steps:
      - uses: actions/checkout@v7
        with:
          # History for the merge base, without old file contents: git
          # fetches the few a plan reads (a changed barrel or lockfile).
          fetch-depth: 0
          filter: blob:none
      - uses: oven-sh/setup-bun@v2
      - id: merge-base
        run: echo "sha=$(git merge-base origin/main HEAD)" >> "$GITHUB_OUTPUT"
      - uses: actions/cache@v6
        with:
          path: .bivium/cache
          key: bivium-${{ steps.merge-base.outputs.sha }}
          restore-keys: bivium-
      - id: plan
        # --bun: run on Bun, which loads a TypeScript config whatever Node
        # the runner has.
        run: bunx --bun bivium plan origin/main --github
  unit:
    needs: plan
    if: needs.plan.outputs.unit != 'none'
    steps:
      # …install, then run all tests or the selected files:
      - run: bunx vitest run ${{ needs.plan.outputs.unit != 'all' && needs.plan.outputs.unit || '' }}

缓存保存从每个文件提取的内容，这些内容由git blob键控，因此warm计划只读取分支更改的文件。在合并基础上键入它：拉取请求可以从默认分支恢复缓存，该分支在提交时运行是要命中的。没有 node_modules，缓存就在 .bivium/cache;它写了一个 .gitignore 所以它不会显示为变化。

在一台苹果m系列笔记本电脑的负载情况下，一个套餐的成本是多少（5个套餐中值，待机时间）：

所以这个大小的缓存是可选的， bunx --bun 这是值得的，并且在测试作业中进行规划（没有额外的作业，没有安装）花费的时间不到一秒钟。生成的存储库的冷计划在Bun上的RSS峰值为88 MB，在Node上为124 MB。

窄

有些更改通过生成的文件到达每个测试：每个页面加载已编译的样式表，因此任何样式编辑都会选择每个测试。更窄的使用来自语义差异的更细的种子替换这种更改的粗种子，例如呈现更改的CSS规则的源。

narrowers: [
  {
    name: "css",
    match: "styles/**", // the changed files it narrows
    opaque: "dist/*.css", // the generated nodes its seeds stand in for
    suites: ["e2e"],
    async narrow({ base, head, changed, graph }) {
      const rules = diffRules(await compile(base.commit), await compile(head.commit));
      if (!rules) return { all: "a rule that requires no class changed" };
      return { seeds: sourcesSpelling(rules), note: `${rules.length} rules changed` };
    },
  },
],

匹配的文件仍然沿着路径走，但是它停在 opaque 结点和种子代表着它们。窄的只能窄：它的套房的选择被削减到没有它选择的步行。一个返回的 { all: reason }抛出或返回的任何东西都将完整地运行其套件。 narrow() 获取存储库 root，合并基和工作树为 base 和 head (每个都有 commit 和 read(path))，匹配的 changed 文件，和只读 graph （nodes()， importers(node)， dependents(nodes)， tests(suite)）。 eval/carbon/css-narrower.ts 它的碳成分是细长的，在玻璃上。

从代码

import { defineConfig, plan } from "bivium";

const config = defineConfig({ suites: { unit: { tests: "tests/**/*.test.ts" } } });
const result = await plan({ config, base: "origin/main" });
result.suites.unit; // { mode: "some", files: [...] }; result.suites.e2e is a type error

plan(options?) 需要 cwd， base， config (默认：配置文件 cwd), cache，并返回每个套件的选择、测试计数、作为句子和数据的原因、lockfile更改种子或发现惰性的包、基文件、合并基文件和更改的文件，以及每个狭窄返回的内容。给定一个配置，套件名称将传递到结果的类型。包只导出 plan， defineConfig 以及它们的类型。

相比之下,