feat(scripts): one command checks what the branch changed

.github/scripts/ci-changes.cjs

@@ -5,6 +5,8 @@
 //   node ci-changes.cjs --paths <file> --full   run every Linux job, gate only the macOS lint
 //   node ci-changes.cjs                         changed paths unknown: run everything
 //
+// scripts/check-changed.ts requires the same decisions so local runs match CI.
+//
 // Every changed path maps to workspace packages, which then pull in their
 // dependents from package.json. A path this file does not recognize runs
 // everything, so a new root file or directory can only cost minutes.
@@ -201,4 +203,6 @@ function main() {
   for (const [key, value] of Object.entries(outputs)) console.log(`${key}=${value}`);
 }
 
-main();
+module.exports = { readWorkspace, decide };
+
+if (require.main === module) main();

.github/scripts/ci-changes.d.cts

@@ -0,0 +1,27 @@
+interface WorkspacePackage {
+  readonly name: string;
+  readonly dir: string;
+  readonly hasTest: boolean;
+  readonly deps: ReadonlyArray<string>;
+}
+
+export function readWorkspace(): Array<WorkspacePackage>;
+
+export function decide(
+  files: ReadonlyArray<string> | null,
+  packages: ReadonlyArray<WorkspacePackage>,
+  full: boolean,
+): {
+  affected: Array<string>;
+  outputs: {
+    typecheck: boolean;
+    build: boolean;
+    test: boolean;
+    test_packages: string;
+    test_web: boolean;
+    test_server: boolean;
+    rust: boolean;
+    release_smoke: boolean;
+    mobile_native: boolean;
+  };
+};

AGENTS.md

@@ -98,8 +98,9 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
 
 ## Verifying
 
-- Smallest proof that the change works. `vp test run <files>` for the tests you touched (`-t "<name>"` in big files), `vp lint <files>`, and `vp run typecheck` in the package you changed. Not `npx tsc`; it is 3x slower than tsc-rs.
-- Run `vp run knip:check` (about 35 s) when you add, remove, or rename exports, files, or dependencies.
+- Before you push, run `vp run check:changed`. It runs CI checks for changed files: format, lint, tests beside changes, typecheck of affected packages and dependents, plus knip when files, exports, or dependencies change.
+- While you iterate, run `vp test run <files>`. For big files, add `-t "<name>"`.
+- Do not use `npx tsc`. Use `vp run typecheck`; it uses tsc-rs, which is 3x faster.
 - Run `node -e` snippets from `apps/server` or the owning package. `effect` does not resolve from the repo root.
 - Test meaningful logic or observable behavior. Do not render components to static markup to assert props or attributes, or add tests that merely assert callback wiring or mirror the implementation.
 - **Do not run repo-wide checks.** No `vp check`, no `vp run -r test`, no `vp run -r typecheck` unless I ask. CI owns the full suite.

docs/operations/development.md

@@ -102,7 +102,14 @@ for the security model.
 
 ## Checks
 
-Run checks for the files and packages you changed:
+`vp run check:changed` runs what CI runs for your branch's changes: format and lint of the
+changed files, `knip:check` when files, exports, or dependencies change, typecheck of the affected
+packages and their dependents, and the test files beside the changed files. It maps files to
+packages with [ci-changes.cjs](../../.github/scripts/ci-changes.cjs), as CI does. It compares
+against the merge base with `origin/main`, or a ref you pass. Tests that reach a changed file only
+through imports run in CI.
+
+While you iterate, run single checks:
 
 ```sh
 vp test run <files>

package.json

@@ -26,6 +26,7 @@
     "build:resource-monitor": "cargo build --locked --release --manifest-path native/resource-monitor/Cargo.toml",
     "typecheck": "vp run -r --cache --concurrency-limit 4 typecheck",
     "tc": "vp run -r --cache --concurrency-limit 4 typecheck",
+    "check:changed": "node scripts/check-changed.ts",
     "lint": "vp lint --report-unused-disable-directives",
     "knip": "knip --preprocessor ./scripts/knip-schemas.ts",
     "knip:check": "knip --include files,dependencies --no-config-hints && knip --workspace apps/server --workspace apps/desktop --workspace apps/web --workspace packages/client-runtime --workspace packages/contracts --workspace packages/effect-acp --workspace packages/effect-codex-app-server --workspace packages/shared --workspace packages/ssh --workspace packages/tailscale --workspace packages/provider-core --workspace packages/provider-acp --workspace packages/provider-acp-registry --workspace packages/provider-testing --workspace packages/provider-pi --workspace packages/provider-muse --workspace packages/provider-opencode --workspace packages/provider-cursor --workspace packages/provider-grok --workspace packages/source-control-core --workspace packages/source-control-azure-devops --workspace packages/source-control-bitbucket --workspace packages/source-control-forgejo --workspace packages/source-control-gitcafe --workspace packages/source-control-github --workspace packages/source-control-gitlab --workspace packages/source-control-testing --exports --preprocessor ./scripts/knip-schemas.ts --no-config-hints",

scripts/check-changed.ts

@@ -0,0 +1,112 @@
+// @effect-diagnostics nodeBuiltinImport:off globalConsole:off
+// Runs locally what CI runs for this branch's changes: format and lint of the
+// changed files, knip, typecheck of the affected packages and their dependents,
+// and the test files beside the changed files.
+//
+//   vp run check:changed          compare against the merge base with origin/main
+//   vp run check:changed <ref>    compare against <ref>
+//
+// Uncommitted and untracked files count. The package mapping comes from
+// .github/scripts/ci-changes.cjs, so this typechecks what CI would typecheck.
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+import { decide, readWorkspace } from "../.github/scripts/ci-changes.cjs";
+
+const root = NodePath.resolve(import.meta.dirname, "..");
+const CODE = /\.[cm]?[jt]sx?$/;
+
+const git = (...args: Array<string>) =>
+  NodeChildProcess.execFileSync("git", args, { cwd: root, encoding: "utf8" })
+    .split("\n")
+    .filter(Boolean);
+
+const base = process.argv[2] ?? git("merge-base", "HEAD", "origin/main")[0] ?? "origin/main";
+// --no-renames lists a rename as its old and new path, as CI does.
+const untracked = git("ls-files", "--others", "--exclude-standard");
+const files = [
+  ...new Set([...git("diff", "--name-only", "--no-renames", base, "--"), ...untracked]),
+].sort();
+
+if (files.length === 0) {
+  console.log(`check:changed: no changes since ${base.slice(0, 12)}.`);
+  process.exit(0);
+}
+
+const present = files.filter((file) => NodeFS.existsSync(NodePath.join(root, file)));
+const code = present.filter((file) => CODE.test(file));
+const packages = readWorkspace();
+const { affected, outputs } = decide(files, packages, false);
+
+// Changed test files, and the test files beside a changed source file
+// (foo.ts -> foo.test.ts, foo.browser.test.tsx). Vitest's import-graph
+// `related` reaches most of a package: one leaf server file pulled in 252 of
+// 406 server test files and took 7 minutes. CI runs the rest.
+const TEST = /\.test\.[cm]?[jt]sx?$/;
+const tests = new Set(code.filter((file) => TEST.test(file)));
+for (const file of code) {
+  const dir = NodePath.dirname(file);
+  const prefix = `${NodePath.basename(file).replace(CODE, "")}.`;
+  for (const entry of NodeFS.readdirSync(NodePath.join(root, dir))) {
+    if (entry.startsWith(prefix) && TEST.test(entry)) tests.add(NodePath.join(dir, entry));
+  }
+}
+
+// knip:check takes about 35 s and cannot be scoped to a package, so it runs
+// only when the change can leave a file, export, or dependency unused.
+const addedOrDeleted = new Set([
+  ...git("diff", "--name-only", "--no-renames", "--diff-filter=AD", base, "--"),
+  ...untracked,
+]);
+const changedExport =
+  code.length > 0 &&
+  git("diff", "--unified=0", base, "--", ...code).some((line) =>
+    /^[+-](?!\+\+ |-- ).*\bexport\b/.test(line),
+  );
+const runKnip =
+  changedExport ||
+  files.some(
+    (file) =>
+      (CODE.test(file) && addedOrDeleted.has(file)) ||
+      NodePath.basename(file) === "package.json" ||
+      file === "knip.jsonc",
+  );
+
+const filters = (names: ReadonlyArray<string>) => names.flatMap((name) => ["--filter", name]);
+const steps = [
+  present.length > 0 && {
+    name: "format",
+    args: ["fmt", "--check", "--no-error-on-unmatched-pattern", ...present],
+  },
+  code.length > 0 && { name: "lint", args: ["lint", ...code] },
+  runKnip && { name: "knip", args: ["run", "knip:check"] },
+  affected.length > 0 && {
+    name: `typecheck (${affected.length} packages)`,
+    args: ["run", "--cache", "--concurrency-limit", "4", ...filters(affected), "typecheck"],
+  },
+  // From the repo root, the root vite.config.ts hands each file to its package's config.
+  tests.size > 0 && {
+    name: `test (${tests.size} files)`,
+    args: ["test", "run", "--passWithNoTests", ...tests],
+  },
+].filter((step) => step !== false);
+
+console.log(`check:changed: ${files.length} files since ${base.slice(0, 12)}`);
+const results = steps.map((step) => {
+  console.log(`\n> vp ${step.name}`);
+  const started = performance.now();
+  const { status } = NodeChildProcess.spawnSync("vp", step.args, { cwd: root, stdio: "inherit" });
+  const seconds = ((performance.now() - started) / 1000).toFixed(1);
+  return { name: step.name, ok: status === 0, seconds };
+});
+
+console.log("\ncheck:changed summary");
+for (const result of results) {
+  console.log(`  ${result.ok ? "pass" : "FAIL"}  ${result.name}  ${result.seconds}s`);
+}
+const ciOnly = (["build", "rust", "mobile_native", "release_smoke"] as const).filter(
+  (job) => outputs[job],
+);
+if (ciOnly.length > 0) console.log(`  CI also runs: ${ciOnly.join(", ")}`);
+if (!runKnip) console.log("  knip skipped: no files, exports, or dependencies changed");
+if (results.some((result) => !result.ok)) process.exit(1);