@avi2dg/checks 0.55.0 → 0.56.1

package/src/complexity/graphwalk.ts

@@ -0,0 +1,374 @@
+#!/usr/bin/env bun
+import { BunServices } from "@effect/platform-bun";
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { LINTED_SOURCE, TYPESCRIPT_SOURCE, type TrackedContent } from "../core/gates.ts";
+import { checkoutFiles, collect, commitOf, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
+import { PASSED, runExitMain, UNDECIDED, Usage, VIOLATED } from "../core/main.ts";
+import { knipReport } from "./knip.ts";
+
+const NAME = "graphwalk";
+const UNUSED = "unused";
+const EXPORTS = "exports";
+const IMPORTS = "imports";
+const WRITE = "--write";
+const USAGE = `usage: graphwalk.ts [<ref> | <base-ref> <head-ref> | ${WRITE}]`;
+
+const INCLUDED = ["--include", "files,exports,types"];
+const JUDGED = /[.]tsx?$|[.]astro$/;
+
+export const BASELINE_FILE = "exports-baseline.json";
+
+export const PROJECT_CONFIG = "dependency-cruiser.config.ts";
+
+export const OWN_CONFIGS = [
+  ".dependency-cruiser.json",
+  ".dependency-cruiser.js",
+  ".dependency-cruiser.cjs",
+  ".dependency-cruiser.mjs",
+  ".dependency-cruiser.ts",
+  ".dependency-cruiser.cts",
+  ".dependency-cruiser.mts",
+] as const;
+
+export const CRUISED = ["*.ts", "*.tsx", "*.mts", "*.cts"] as const;
+
+const KIT_DEFAULTS = "kit-defaults.ts";
+
+export type Status = "passed" | "violated" | "undecided";
+
+class GraphwalkError extends Schema.TaggedError<GraphwalkError>()("GraphwalkError", {
+  message: Schema.String,
+}) {}
+
+const UnusedSymbolSchema = Schema.Struct({ file: Schema.String, kind: Schema.Literals(["export", "type"]), name: Schema.String });
+
+export type UnusedSymbol = typeof UnusedSymbolSchema.Type;
+
+export type Baseline = readonly UnusedSymbol[];
+
+export type Drift = { readonly unlisted: readonly UnusedSymbol[]; readonly added: readonly UnusedSymbol[]; readonly stale: readonly UnusedSymbol[] };
+
+const Violation = Schema.Struct({ from: Schema.String, to: Schema.String, rule: Schema.Struct({ name: Schema.String, severity: Schema.String }) });
+
+export type Violation = typeof Violation.Type;
+
+const decodeKnipFiles = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ issues: Schema.Array(Schema.Struct({ files: Schema.optional(Schema.Array(Schema.Struct({ name: Schema.String }))) })) })),
+);
+
+const decodeKnipSymbols = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ issues: Schema.Array(Schema.Struct({ file: Schema.String, exports: Schema.optional(Schema.Array(Schema.Struct({ name: Schema.String }))), types: Schema.optional(Schema.Array(Schema.Struct({ name: Schema.String }))) })) })),
+);
+
+const decodeBaseline = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(UnusedSymbolSchema)));
+
+const decodeCruise = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ summary: Schema.Struct({ violations: Schema.Array(Violation), error: Schema.Int, totalCruised: Schema.Int }) })),
+);
+
+const byPosition = (a: UnusedSymbol, b: UnusedSymbol): number => a.file.localeCompare(b.file) || a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name);
+
+const keyOf = ({ file, kind, name }: UnusedSymbol): string => `${kind}\0${file}\0${name}`;
+
+function outside(symbols: readonly UnusedSymbol[], others: readonly UnusedSymbol[]): readonly UnusedSymbol[] {
+  const known = new Set(others.map(keyOf));
+  return symbols.filter((symbol) => !known.has(keyOf(symbol))).toSorted(byPosition);
+}
+
+const describe = (symbol: UnusedSymbol): string => `  ${symbol.file}: ${symbol.name} (${symbol.kind})`;
+
+export const filesOf = Effect.fn("filesOf")(function* (stdout: string) {
+  const { issues } = yield* decodeKnipFiles(stdout).pipe(
+    Effect.mapError((cause) => new GraphwalkError({ message: `knip's JSON report does not decode: ${cause.message}` })),
+  );
+  return issues
+    .flatMap(({ files = [] }) => files.map(({ name }) => name))
+    .filter((file) => JUDGED.test(file))
+    .toSorted();
+});
+
+export function unusedReport({ tracked, files }: { readonly tracked: number; readonly files: readonly string[] }): string {
+  if (files.length === 0) return `${UNUSED}: no unreferenced files among ${tracked} tracked .ts/.tsx/.astro file(s)`;
+  return [`${UNUSED}: ${files.length} unreferenced file(s):`, ...files.map((file) => `  ${file}`)].join("\n");
+}
+
+export const symbolsOf = Effect.fn("symbolsOf")(function* (stdout: string) {
+  const { issues } = yield* decodeKnipSymbols(stdout).pipe(
+    Effect.mapError((cause) => new GraphwalkError({ message: `knip's JSON report does not decode: ${cause.message}` })),
+  );
+  return issues
+    .flatMap(({ file, exports = [], types = [] }): readonly UnusedSymbol[] => [
+      ...exports.map(({ name }): UnusedSymbol => ({ file, kind: "export", name })),
+      ...types.map(({ name }): UnusedSymbol => ({ file, kind: "type", name })),
+    ])
+    .toSorted(byPosition);
+});
+
+export const baselineOf = Effect.fn("baselineOf")(function* (text: string, where: string) {
+  return yield* decodeBaseline(text).pipe(
+    Effect.mapError((cause) => new GraphwalkError({ message: `${where} does not decode: ${cause.message}` })),
+  );
+});
+
+export function driftOf({
+  reported,
+  base,
+  head,
+  unusedAtBase,
+}: {
+  readonly reported: Baseline;
+  readonly base: Baseline;
+  readonly head: Baseline;
+  readonly unusedAtBase: Baseline;
+}): Drift {
+  return {
+    unlisted: outside(reported, head),
+    added: outside(head, [...base, ...unusedAtBase]),
+    stale: outside(head, reported),
+  };
+}
+
+export function exportsReport(head: Baseline, { unlisted, added, stale }: Drift): string {
+  const sections = [
+    { symbols: unlisted, what: `unused export(s) not in ${BASELINE_FILE}:` },
+    { symbols: added, what: `${BASELINE_FILE} export(s) the range adds that its base did not leave unused, remove the export instead:` },
+    { symbols: stale, what: `${BASELINE_FILE} export(s) no longer reported, remove them:` },
+  ].filter(({ symbols }) => symbols.length > 0);
+  if (sections.length > 0) {
+    return sections.flatMap(({ symbols, what }) => [`${EXPORTS}: ${symbols.length} ${what}`, ...symbols.map(describe)]).join("\n");
+  }
+  return head.length === 0
+    ? `${EXPORTS}: no unused exports or types`
+    : `${EXPORTS}: ${head.length} unused export(s) in ${BASELINE_FILE}, and no new ones`;
+}
+
+export function describeViolation({ from, to, rule }: Violation): string {
+  return from === to ? `  ${rule.severity} ${rule.name}: ${from}` : `  ${rule.severity} ${rule.name}: ${from} → ${to}`;
+}
+
+const unconfiguredLine = (section: string): string =>
+  `${section}: no knip configuration names entry files, so add a knip.config.ts calling defineConfig from @avi2dg/checks/knip`;
+
+const trackedIn = Effect.fn("trackedIn")(function* (root: string, source: TrackedContent) {
+  return (yield* git(["ls-files", "--", ...source.pathspecs], root))
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+});
+
+const baselinePath = Effect.fn("baselinePath")(function* (root: string) {
+  return (yield* Path.Path).join(root, BASELINE_FILE);
+});
+
+const baselineInTree = Effect.fn("baselineInTree")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const at = yield* baselinePath(root);
+  if (!(yield* fs.exists(at))) return [] satisfies Baseline;
+  return yield* fs.readFileString(at).pipe(Effect.flatMap((text) => baselineOf(text, BASELINE_FILE)));
+});
+
+const baselineAt = Effect.fn("baselineAt")(function* (treeish: string, root: string) {
+  const blob = (yield* git(["ls-tree", "--object-only", treeish, "--", BASELINE_FILE], root)).trim();
+  if (blob === "") return [] satisfies Baseline;
+  return yield* baselineOf(yield* git(["cat-file", "blob", blob], root), `${BASELINE_FILE} at ${treeish}`);
+});
+
+// Knip loads the configuration's imports, such as the kit's knip builder, from a node_modules the checkout lacks.
+const unusedAt = Effect.fn("unusedAt")(
+  function* (rev: string, root: string) {
+    const files = yield* pathsAt(rev, [], root);
+    if (files.length === 0) return [] satisfies Baseline;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const tree = yield* checkoutFiles(rev, files, yield* fs.makeTempDirectoryScoped({ prefix: "checks-graphwalk-" }), root);
+    const modules = path.join(root, "node_modules");
+    if (yield* fs.exists(modules)) yield* fs.symlink(modules, path.join(tree, "node_modules"));
+    const reported = yield* knipReport(tree, INCLUDED).pipe(
+      Effect.mapError((cause) => new GraphwalkError({ message: `at ${rev}: ${cause.message}` })),
+    );
+    return reported.kind === "unconfigured" ? [] : yield* symbolsOf(reported.stdout);
+  },
+  Effect.scoped,
+);
+
+// Knip scans the checked-out tree, and a pull request's merge checkout holds the base branch tip beside the range head.
+const judgedBase = Effect.fn("judgedBase")(function* (first: string, second: string | undefined, root: string) {
+  const { base } = yield* rangeEnds(first, second, root);
+  if (second === undefined) return base;
+  const head = yield* commitOf(second, root);
+  const parents = (yield* git(["rev-parse", "HEAD^@"], root)).split("\n").filter((line) => line !== "");
+  const [other, ...rest] = parents.filter((parent) => parent !== head);
+  return parents.includes(head) && other !== undefined && rest.length === 0 ? other : base;
+});
+
+const configOf = Effect.fn("configOf")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  for (const name of [PROJECT_CONFIG, ...OWN_CONFIGS]) {
+    if (yield* fs.exists(path.join(root, name))) return { file: name, shown: name };
+  }
+  return { file: path.join(import.meta.dir, "..", "dependencies", KIT_DEFAULTS), shown: "the kit's defaults" };
+});
+
+const depcruise = Effect.fn("depcruise")(function* () {
+  const path = yield* Path.Path;
+  const main = yield* Effect.try({
+    try: () => new URL("../../bin/dependency-cruiser.mjs", import.meta.resolve("dependency-cruiser")),
+    catch: () => new GraphwalkError({ message: "cannot resolve dependency-cruiser, a peer dependency of the kit" }),
+  });
+  return yield* path.fromFileUrl(main);
+});
+
+const trackedInTree = Effect.fn("trackedInTree")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const listed = yield* git(["ls-files", "-z", "--", ...CRUISED], root);
+  return yield* Effect.filter(listed.split("\0").filter(Boolean), (file) => fs.exists(path.join(root, file)), { concurrency: "unbounded" });
+});
+
+const runSection = Effect.fn("runSection")(function* (
+  section: string,
+  body: Effect.Effect<Status, { readonly message: string }, BunServices.BunServices>,
+) {
+  return yield* body.pipe(
+    Effect.catch((cause) => Console.error(`${section}: ${cause.message}`).pipe(Effect.as<Status>("undecided"))),
+  );
+});
+
+const unusedSection = (tracked: number, stdout: string) =>
+  runSection(
+    UNUSED,
+    Effect.gen(function* () {
+      const files = yield* filesOf(stdout);
+      yield* Console.log(unusedReport({ tracked, files }));
+      return files.length === 0 ? "passed" : "violated";
+    }),
+  );
+
+const exportsSection = (root: string, stdout: string, first: string, second: string | undefined) =>
+  runSection(
+    EXPORTS,
+    Effect.gen(function* () {
+      const head = yield* baselineInTree(root);
+      const reported = yield* symbolsOf(stdout);
+      const baseRev = yield* judgedBase(first, second, root);
+      const base = yield* baselineAt(baseRev, root);
+      const unusedAtBase = outside(head, base).length === 0 ? [] : yield* unusedAt(baseRev, root);
+      const drift = driftOf({ reported, base, head, unusedAtBase });
+      yield* Console.log(exportsReport(head, drift));
+      return drift.unlisted.length === 0 && drift.added.length === 0 && drift.stale.length === 0 ? "passed" : "violated";
+    }),
+  );
+
+const importsSection = (root: string) =>
+  runSection(
+    IMPORTS,
+    Effect.gen(function* () {
+      const files = yield* trackedInTree(root);
+      if (files.length === 0) return yield* new GraphwalkError({ message: "no tracked TypeScript to cruise" });
+      const config = yield* configOf(root);
+      const run = yield* collect(process.execPath, [yield* depcruise(), "--config", config.file, "--output-type", "json", ...files], root).pipe(
+        Effect.mapError((cause) => new GraphwalkError({ message: `cannot run dependency-cruiser: ${cause.message}` })),
+      );
+      const { summary } = yield* decodeCruise(run.stdout).pipe(
+        Effect.mapError(
+          () => new GraphwalkError({ message: `dependency-cruiser exits ${run.exitCode} with no report: ${(run.stdout + run.stderr).trim()}` }),
+        ),
+      );
+      const cruised = `${summary.totalCruised} module(s) cruised against ${config.shown}`;
+      if (summary.violations.length === 0) {
+        yield* Console.log(`${IMPORTS}: ${cruised}, no violation`);
+        return "passed";
+      }
+      yield* Console.error(
+        [`${IMPORTS}: ${summary.violations.length} violation(s) in ${cruised}`, ...summary.violations.map(describeViolation)].join("\n"),
+      );
+      return summary.error === 0 ? "passed" : "violated";
+    }),
+  );
+
+function exitOf(statuses: readonly Status[]): number {
+  if (statuses.includes("violated")) return VIOLATED;
+  if (statuses.includes("undecided")) return UNDECIDED;
+  return PASSED;
+}
+
+const seed = Effect.fn("seed")(function* (root: string, tracked: number) {
+  if (tracked === 0) return yield* new GraphwalkError({ message: "no tracked TypeScript source to scan" });
+  const reported = yield* knipReport(root, INCLUDED).pipe(Effect.mapError((cause) => new GraphwalkError({ message: cause.message })));
+  if (reported.kind === "unconfigured") {
+    yield* Console.log(unconfiguredLine(EXPORTS));
+    return VIOLATED;
+  }
+  const symbols = yield* symbolsOf(reported.stdout);
+  yield* (yield* FileSystem.FileSystem).writeFileString(yield* baselinePath(root), `${JSON.stringify(symbols, null, 2)}\n`);
+  yield* Console.log(`${EXPORTS}: wrote ${symbols.length} unused export(s) to ${BASELINE_FILE}`);
+  return PASSED;
+});
+
+const lintOnlyGate = Effect.fn("lintOnlyGate")(function* (root: string, args: readonly string[]) {
+  if ((yield* trackedInTree(root)).length === 0) return yield* new GraphwalkError({ message: "no tracked TypeScript or Astro source to scan" });
+  if (args.length > 0) yield* refArgs(args, USAGE);
+  return exitOf([yield* importsSection(root)]);
+});
+
+const knipFailedGate = Effect.fn("knipFailedGate")(function* (root: string, message: string, hasTypescript: boolean) {
+  yield* Console.error(`${UNUSED}: ${message}`);
+  if (!hasTypescript) {
+    if ((yield* trackedInTree(root)).length === 0) return UNDECIDED;
+    return exitOf(["undecided", yield* importsSection(root)]);
+  }
+  yield* Console.error(`${EXPORTS}: ${message}`);
+  return exitOf(["undecided", "undecided", yield* importsSection(root)]);
+});
+
+const unconfiguredGate = Effect.fn("unconfiguredGate")(function* (root: string, hasTypescript: boolean) {
+  yield* Console.log(unconfiguredLine(UNUSED));
+  yield* Console.log(unconfiguredLine(EXPORTS));
+  const cruised = hasTypescript || (yield* trackedInTree(root)).length > 0 ? yield* importsSection(root) : "passed";
+  return exitOf(["violated", "violated", cruised]);
+});
+
+const judgedGate = Effect.fn("judgedGate")(function* (root: string, linted: number, typescript: number, stdout: string, first: string, second: string | undefined) {
+  const unlisted = yield* unusedSection(linted, stdout);
+  if (typescript === 0) {
+    if ((yield* trackedInTree(root)).length === 0) return exitOf([unlisted]);
+    return exitOf([unlisted, yield* importsSection(root)]);
+  }
+  const drifted = yield* exportsSection(root, stdout, first, second);
+  return exitOf([unlisted, drifted, yield* importsSection(root)]);
+});
+
+const gate = Effect.gen(function* () {
+  const args = process.argv.slice(2);
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  if (args.length === 1 && args[0] === WRITE) {
+    const tracked = yield* trackedIn(root, TYPESCRIPT_SOURCE);
+    return yield* seed(root, tracked.length).pipe(
+      Effect.catch((cause: { readonly message: string }) => Console.error(`${EXPORTS}: ${cause.message}`).pipe(Effect.as(UNDECIDED))),
+    );
+  }
+  const linted = yield* trackedIn(root, LINTED_SOURCE);
+  if (linted.length === 0) return yield* lintOnlyGate(root, args);
+  const { first, second } = args.length === 0 ? { first: "HEAD", second: undefined } : yield* refArgs(args, USAGE);
+  const typescript = yield* trackedIn(root, TYPESCRIPT_SOURCE);
+  const knipOutcome = yield* knipReport(root, INCLUDED).pipe(
+    Effect.mapError((cause) => new GraphwalkError({ message: cause.message })),
+    Effect.map((reported) => ({ failed: false as const, reported })),
+    Effect.catch((cause: { readonly message: string }) => Effect.succeed({ failed: true as const, message: cause.message })),
+  );
+  if (knipOutcome.failed) return yield* knipFailedGate(root, knipOutcome.message, typescript.length > 0);
+  const reported = knipOutcome.reported;
+  if (reported.kind === "unconfigured") return yield* unconfiguredGate(root, typescript.length > 0);
+  return yield* judgedGate(root, linted.length, typescript.length, reported.stdout, first, second);
+}).pipe(
+  Effect.catch((cause: { readonly message: string }) =>
+    (cause instanceof Usage ? Console.error(`${NAME}: ${cause.message}`) : Console.error(`${UNUSED}: ${cause.message}`)).pipe(
+      Effect.as(UNDECIDED),
+    ),
+  ),
+);
+
+if (import.meta.main) {
+  runExitMain(gate);
+}

package/src/complexity/knip.ts

@@ -1,6 +1,5 @@
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import type { TrackedContent } from "../core/gates.ts";
-import { collect, git } from "../core/git.ts";
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { collect } from "../core/git.ts";
 
 class KnipError extends Schema.TaggedError<KnipError>()("KnipError", {
   message: Schema.String,
@@ -53,17 +52,3 @@ export const knipReport = Effect.fn("knipReport")(function* (root: string, args:
   }
   return { kind: "reported", stdout: run.stdout } as const;
 });
-
-export const scanTree = Effect.fn("scanTree")(function* (name: string, args: readonly string[], source: TrackedContent) {
-  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const tracked = (yield* git(["ls-files", "--", ...source.pathspecs], root))
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line !== "");
-  if (tracked.length === 0) return yield* new KnipError({ message: `no tracked ${source.content} to scan` });
-  const reported = yield* knipReport(root, args);
-  if (reported.kind === "unconfigured") {
-    yield* Console.log(`${name}: no knip configuration names entry files, so add a knip.config.ts calling defineConfig from @avi2dg/checks/knip`);
-  }
-  return { root, tracked: tracked.length, reported };
-});

package/src/core/gates.ts

@@ -63,10 +63,8 @@ export const KIT_GATES = [
   { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", alsoReads: "every agent file at the head commit", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-copy", vector: "docs", file: "copy.ts", reads: "tree", appliesTo: COPY_DECLARATION },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: LINTED_SOURCE },
-  { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-graphwalk", vector: "complexity", file: "graphwalk.ts", reads: "range", appliesTo: LINTED_SOURCE },
   { bin: "checks-quarantine-clock", vector: "testing", file: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-imports", vector: "dependencies", file: "imports.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   {
     bin: "checks-advisories",
     vector: "dependencies",
@@ -74,5 +72,5 @@ export const KIT_GATES = [
     reads: "range",
     env: { [ADVISORIES_DEFER_SCAN]: "1" },
     appliesTo: BUN_LOCKFILE,
-  },
+  }
 ] as const satisfies readonly KitGate[];

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/main.ts

@@ -1,9 +1,9 @@
 import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Cause, Console, Effect, Exit, Schema } from "effect";
 
-const PASSED = 0;
-const VIOLATED = 1;
-const UNDECIDED = 2;
+export const PASSED = 0;
+export const VIOLATED = 1;
+export const UNDECIDED = 2;
 const INTERRUPTED = 130;
 
 export class Usage extends Schema.TaggedError<Usage>()("Usage", {
@@ -19,12 +19,16 @@ export function runMain<E extends { readonly message: string }>(
   name: string,
   passes: Effect.Effect<boolean, E, BunServices.BunServices>,
 ): void {
-  const program = passes.pipe(
-    Effect.map((passed) => (passed ? PASSED : VIOLATED)),
-    Effect.catch((failure) => Console.error(`${name}: ${failure.message}`).pipe(Effect.as(UNDECIDED))),
-    Effect.provide(BunServices.layer),
+  runExitMain(
+    passes.pipe(
+      Effect.map((passed) => (passed ? PASSED : VIOLATED)),
+      Effect.catch((failure) => Console.error(`${name}: ${failure.message}`).pipe(Effect.as(UNDECIDED))),
+    ),
   );
-  BunRuntime.runMain(program, { teardown: (exit, onExit) => onExit(statusOf(exit)) });
+}
+
+export function runExitMain(exits: Effect.Effect<number, never, BunServices.BunServices>): void {
+  BunRuntime.runMain(exits.pipe(Effect.provide(BunServices.layer)), { teardown: (exit, onExit) => onExit(statusOf(exit)) });
 }
 
 export function runTreeGate<Outcome extends { readonly violations: readonly unknown[] }>(

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),
+  };
+}
+