@avi2dg/checks 0.55.0 → 0.56.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.56.0
+
+Released 2026-10-27.
+
+### Features
+
+- **core:** scope lint gates by changed paths and add desk run [#11](https://github.com/avi2d/checks/pull/11)
+
 ## 0.55.0
 
 Released 2026-10-27.

package/docs/bins.md

@@ -10,6 +10,7 @@ The kit ships one bin per check, each named `checks-` and called from a package
 
 `checks-lint` runs each of these gates that applies to the repository, and names every one that fails.
 A gate reads either the working tree or the range `checks-lint` resolves.
+It scopes tree gates to the change unless `--full` forces the full run, and `--desk` runs the fast tree gates.
 The table groups the gates by vector, the part of a repository each one judges.
 
 <!-- generated gates: bun run build writes it from KIT_GATES in src/core/gates.ts and scripts/doc-blocks.ts -->

package/docs/configs/dependency-rules.md

@@ -61,7 +61,7 @@ A rule under `forbidden` that takes a kit rule's name replaces that rule whole,
 
 ## Running it
 
-`checks-lint` runs [checks-imports](../gates/checks-imports.md), which cruises every tracked TypeScript file against `dependency-cruiser.config.ts`, or against the kit's defaults when the repository holds no config.
+`checks-lint` runs [checks-imports](../gates/checks-imports.md) in the full run, which cruises every tracked TypeScript file against `dependency-cruiser.config.ts`, or against the kit's defaults when the repository holds no config.
 
 ## Related topics
 

package/docs/design.md

@@ -123,10 +123,11 @@ So the three packages move together at one exact version.
 `checks-lint` runs each gate in a child process rather than importing it.
 A gate then behaves the same alone or through `checks-lint`, and `lint-coverage.sh` can stay a shell script.
 The gates run one at a time and pass their output straight through, so each report reads whole and in the order of the gate table.
-`checks-lint` picks the gates that apply from the tracked files, and a repository cannot select gates.
-A TypeScript gate runs as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also run on tracked Astro source.
+`checks-lint` picks the gates that apply from the tracked files for the full run, and a repository cannot select gates.
+A scoped run selects a subset by changed paths, and the desk run selects the fast tree gates.
+A TypeScript gate applies as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also apply on tracked Astro source.
 
-dependency-cruiser runs as the `checks-imports` gate rather than as a script each repository adds to `lint`, so no repository can leave it out.
+dependency-cruiser runs as the `checks-imports` gate rather than as a script each repository adds to `lint`, so the full run keeps it.
 A repository with no config of its own is cruised against the kit's defaults, since every rule has one.
 The gate cruises the tracked TypeScript, so a build output or a linked library outside git never reaches the cruise.
 It runs dependency-cruiser under Bun, which loads a TypeScript config wherever it sits, the kit's defaults under `node_modules` among them.

package/docs/gates/checks-ci-wiring.md

@@ -131,7 +131,7 @@ ci-wiring: 1 reference(s) name a missing workflow or job:
 
 ## When it runs
 
-`checks-lint` runs it in every repository.
+`checks-lint` runs it in the full run in every repository.
 
 ## Related topics
 

package/docs/gates/checks-copy.md

@@ -107,7 +107,7 @@ copy: no violation in 2 file(s) from 2 declared input(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks `copy.json` at its root.
+`checks-lint` runs it in the full run when the repository tracks `copy.json` at its root.
 A repository without that file never runs it and needs no html-validate.
 
 ## Related topics

package/docs/gates/checks-css-size.md

@@ -44,7 +44,7 @@ css-size: 1 violation(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `*.css` file.
+`checks-lint` runs it in the full run when the repository tracks a `*.css` file.
 
 ## Related topics
 

package/docs/gates/checks-effect-scope.md

@@ -55,7 +55,7 @@ effect-scope: the @effect/language-service entry in tsconfig.json differs from t
 ## When it runs
 
 A repository runs `checks-effect-scope` from its `build` script, so CI's `git diff --exit-code` after the build fails on a stale `tsconfig.json` too.
-`checks-lint` runs it with `--check` when the repository tracks `oxlint.config.ts`.
+`checks-lint` runs it with `--check` in the full run when the repository tracks `oxlint.config.ts`.
 
 ## Related topics
 

package/docs/gates/checks-frontend-syntax.md

@@ -177,7 +177,7 @@ frontend-syntax: no violation in 2 file(s) from 2 declared input(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks `frontend-syntax.json` at its root.
+`checks-lint` runs it in the full run when the repository tracks `frontend-syntax.json` at its root.
 A repository without that file never runs it and needs neither `stylelint.config.ts` nor the peers.
 
 ## Related topics

package/docs/gates/checks-imports.md

@@ -56,7 +56,7 @@ imports: 225 module(s) cruised against dependency-cruiser.config.ts, no violatio
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts` or `.tsx` file, so a repository with no config of its own still has its imports judged.
+`checks-lint` runs it in the full run when the repository tracks a `.ts` or `.tsx` file, so a repository with no config of its own still has its imports judged, and never in the desk run.
 
 ## Related topics
 

package/docs/gates/checks-lint-coverage.md

@@ -53,7 +53,7 @@ lint-coverage: the program tsconfig.json builds holds the ts-reset rules is-arra
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts`, `.tsx` or `.astro` file.
+`checks-lint` runs it in the full run when the repository tracks a `.ts`, `.tsx` or `.astro` file.
 
 ## Related topics
 

package/docs/gates/checks-lint.md

@@ -4,11 +4,16 @@ audience: consumers
 ---
 # checks-lint
 
-`checks-lint` runs every applicable kit lint gate over one range and reports each failure.
+`checks-lint` runs every applicable kit lint gate in the selected set over one range and reports each failure.
 
 ## What it checks
 
 It runs the gates under [What runs](../bins.md#what-runs), each in its own process.
+It scopes the run to the gates the change reaches, and the full run stays the fallback.
+Applicability below selects the full run, and a scoped or desk run selects a subset.
+A Markdown change runs the range gates plus `checks-copy`.
+A TypeScript source change runs every applicable gate.
+A test file classifies as TypeScript, so its change runs every applicable gate too.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
 `checks-lint-coverage` and `checks-unused` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
@@ -31,16 +36,19 @@ Tree gates read the working tree rather than the range.
 
 ```sh
 checks-lint
-checks-lint <base-ref> <head-ref>
+checks-lint [--full | --desk]
+checks-lint [--full | --desk] <base-ref> <head-ref>
 ```
 
 With two arguments, the base and head override range discovery.
+`--full` forces the unscoped run.
+`--desk` runs the fast tree gates.
 
 ## Exit codes
 
 | Code | Result |
 | --- | --- |
-| 0 | Every applicable gate passed. |
+| 0 | Every gate that ran passed. |
 | 1 | At least one gate found a violation. |
 | 2 | The range could not resolve or no failed gate could decide. |
 
@@ -60,6 +68,7 @@ checks-lint: 1 of 19 gate(s) failed: checks-comment-gate
 A repository runs it from `bun run lint` in a pull request workflow that fetches the whole git history.
 It leaves out the TypeScript gates while the repository tracks no TypeScript file, except that `checks-lint-coverage` and `checks-unused` run when it tracks an `.astro` file.
 It never runs `checks-browser`, which a product runs after it builds its site.
+A pull request run scopes the gates to the change.
 
 ## Related topics
 

package/docs/gates/checks-no-plain-js.md

@@ -51,7 +51,7 @@ no-plain-js: 2 violation(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks TypeScript.
+`checks-lint` runs it in the full run when the repository tracks TypeScript.
 
 ## Related topics
 

package/docs/gates/checks-test-layout.md

@@ -87,7 +87,7 @@ test-layout: 4 violation(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks TypeScript.
+`checks-lint` runs it in the full run when the repository tracks TypeScript.
 A repository without TypeScript needs neither the `checks-test` script nor `bunfig.toml`.
 
 ## Related topics

package/docs/gates/checks-unused.md

@@ -57,7 +57,7 @@ unused: no unreferenced files among 110 tracked .ts/.tsx/.astro file(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts`, `.tsx` or `.astro` file.
+`checks-lint` runs it in the full run when the repository tracks a `.ts`, `.tsx` or `.astro` file, and never in the desk run.
 Such a repository names its entries in a Knip configuration.
 
 ## Related topics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -34,6 +34,7 @@
     "src/core/gates.ts",
     "src/core/declared-inputs.ts",
     "src/core/lint.ts",
+    "src/core/scope.ts",
     "src/delivery/changelog.ts",
     "src/delivery/changelog-write.ts",
     "src/delivery/release-notes.ts",
@@ -205,6 +206,7 @@
   },
   "scripts": {
     "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
+    "desk": "bun run test:fast && bun src/core/lint.ts --desk",
     "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun build src/testing/mutation-guard-plugin.ts src/testing/mutation-refusal.ts src/testing/unit-test-order.ts --outdir dist/mutation --target node --format esm --packages external && bun build src/quality/presets/oxlint.ts src/quality/presets/knip.ts src/quality/presets/dependency-cruiser.ts src/quality/presets/stylelint.ts --outdir dist/presets --target node --format esm --packages external && tsc -p tsconfig.presets.json && bun scripts/configs-write.ts && bun src/quality/effect-scope.ts && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint && bun src/core/lint.ts",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",

package/src/core/lint.ts

@@ -2,8 +2,9 @@
 import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { EVERY_REPOSITORY, KIT_GATES, type KitGate } from "./gates.ts";
-import { defaultBranch, git } from "./git.ts";
+import { changedPaths, defaultBranch, git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
+import { FAST_TREE_GATES, selectScope } from "./scope.ts";
 
 type Range = {
   readonly refs: readonly [tip: string] | readonly [base: string, head: string];
@@ -21,7 +22,7 @@ class GatesUndecided extends Schema.TaggedError<GatesUndecided>()("GatesUndecide
 }) {}
 
 const NAME = "checks-lint";
-const USAGE = "usage: lint.ts [<base-ref> <head-ref>]";
+const USAGE = "usage: lint.ts [--full | --desk] [<base-ref> <head-ref>]";
 const PULL_REQUEST_EVENT = "pull_request";
 const SHALLOW_HINT = "a CI checkout needs actions/checkout fetch-depth: 0";
 
@@ -140,6 +141,15 @@ const resolveRange = Effect.fn("resolveRange")(function* (args: readonly string[
   return { refs: rangeOf(base, head), source: ends.source } satisfies Range;
 });
 
+export type LintMode = "full" | "desk" | "scoped";
+
+export function splitMode(args: readonly string[]): { readonly mode: LintMode; readonly rest: readonly string[] } | undefined {
+  const flags = args.filter((arg) => arg.startsWith("--"));
+  const rest = args.filter((arg) => !arg.startsWith("--"));
+  if (flags.length > 1 || (flags.length === 1 && flags[0] !== "--full" && flags[0] !== "--desk")) return undefined;
+  return { mode: flags.length === 0 ? "scoped" : flags[0] === "--full" ? "full" : "desk", rest };
+}
+
 export function describe({ refs }: Range): string {
   return refs.length === 1 ? `tip ${refs[0]}` : `range ${refs[0]}..${refs[1]}`;
 }
@@ -165,15 +175,41 @@ const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
   return { gate, outcome: outcomeOf(exitCode) };
 });
 
+const scopedGates = Effect.fn("scopedGates")(function* (range: Range, root: string) {
+  if (range.refs.length === 1) return { bins: undefined, detail: "the full run, since a lone tip scopes nothing" };
+  const [base, head] = range.refs;
+  const changes = yield* changedPaths(base, head, [], root);
+  const committed = changes.flatMap((change) => (change.kind === "renamed" ? [change.from, change.path] : [change.path]));
+  const working = (yield* git(["diff", "--no-renames", "--name-only", "-z", "HEAD", "--"], root)).split("\0").filter(Boolean);
+  const untracked = (yield* git(["ls-files", "--others", "--exclude-standard", "-z"], root)).split("\0").filter(Boolean);
+  const scope = selectScope([...committed, ...working, ...untracked]);
+  if (scope.full) return { bins: undefined, detail: "the full run, since the change reaches past a scoped shape" };
+  return { bins: scope.gates, detail: "" };
+});
+
 const lint = Effect.gen(function* () {
+  const split = splitMode(process.argv.slice(2));
+  if (split === undefined) return yield* new Usage({ message: USAGE });
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const range = yield* resolveRange(process.argv.slice(2));
+  const range = yield* resolveRange(split.rest);
   yield* Console.log(`${NAME}: ${describe(range)} from ${range.source}`);
-  const gates = yield* Effect.filter(KIT_GATES, (gate) =>
+  const applicable = yield* Effect.filter(KIT_GATES, (gate) =>
     gate.appliesTo === EVERY_REPOSITORY
       ? Effect.succeed(true)
       : git(["ls-files", "--", ...gate.appliesTo.pathspecs], root).pipe(Effect.map((files) => files.trim() !== "")),
   );
+  const scoped = split.mode === "desk"
+    ? {
+      bins: applicable.filter((gate) => FAST_TREE_GATES.includes(gate.bin)).map((gate) => gate.bin),
+      detail: "the desk run",
+    }
+    : split.mode === "full"
+      ? { bins: applicable.map((gate) => gate.bin), detail: "the full run (--full)" }
+      : yield* scopedGates(range, root);
+  const bins = scoped.bins;
+  const gates = bins === undefined ? applicable : applicable.filter((gate) => bins.includes(gate.bin));
+  const detail = split.mode === "scoped" && bins !== undefined ? `${gates.length} gate(s) for this change` : scoped.detail;
+  yield* Console.log(`${NAME}: ${detail}`);
   const verdicts = yield* Effect.forEach(gates, (gate) => runGate(gate, range));
   const failed = verdicts.filter((verdict) => verdict.outcome !== "passed");
   if (failed.length === 0) {

package/src/core/scope.ts

@@ -0,0 +1,54 @@
+import { KIT_GATES } from "./gates.ts";
+
+export type Scope = {
+  readonly full: boolean;
+  readonly gates: readonly string[];
+};
+
+export type ChangeShape = "docs" | "copy" | "typescript" | "workflow" | "lockfile" | "unknown";
+
+const TREE_GATES = KIT_GATES.filter((gate) => gate.reads === "tree").map((gate) => gate.bin);
+
+// checks-unused and checks-imports each take over a second, so the desk run skips them.
+const SLOW_TREE_GATES: readonly string[] = ["checks-unused", "checks-imports"];
+
+export const FAST_TREE_GATES: readonly string[] = TREE_GATES.filter((bin) => !SLOW_TREE_GATES.includes(bin));
+
+const CI_CONFIGS = new Set([
+  "package.json",
+  "bunfig.toml",
+  "commitlint.config.ts",
+  "oxlint.config.ts",
+  "knip.config.ts",
+  "knip-base.json",
+  "dependency-cruiser.config.js",
+  "dependency-cruiser.config.ts",
+]);
+const basenameOf = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+
+export function classifyPath(path: string): ChangeShape {
+  const basename = basenameOf(path);
+  if (basename === "bun.lock") return "lockfile";
+  if (path.startsWith(".github/") || CI_CONFIGS.has(basename) || /^tsconfig(\..*)?\.json$/.test(basename)) {
+    return "workflow";
+  }
+  if (path === "copy.json") return "copy";
+  if (/\.(?:ts|tsx|mts|cts|astro)$/.test(path)) return "typescript";
+  if (path.endsWith(".md")) return "docs";
+  return "unknown";
+}
+
+const fullScope = (): Scope => ({ full: true, gates: KIT_GATES.map((gate) => gate.bin) });
+
+export function selectScope(paths: readonly string[]): Scope {
+  if (paths.length === 0) return fullScope();
+  const shapes = new Set(paths.map(classifyPath));
+  if (shapes.has("unknown") || shapes.has("workflow") || shapes.has("lockfile")) return fullScope();
+  const copyContent = shapes.has("copy") || shapes.has("docs");
+  const tree = shapes.has("typescript") ? TREE_GATES : copyContent ? ["checks-copy"] : [];
+  return {
+    full: false,
+    gates: KIT_GATES.filter((gate) => gate.reads === "range" || tree.includes(gate.bin)).map((gate) => gate.bin),
+  };
+}
+