@avi2dg/checks 0.56.0 → 0.57.0

package/src/core/lint.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 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 { EVERY_REPOSITORY, NIGHT_GATES, PR_GATES, WHOLE_TREE, type KitGate } from "./gates.ts";
 import { changedPaths, defaultBranch, git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 import { FAST_TREE_GATES, selectScope } from "./scope.ts";
@@ -22,7 +22,8 @@ class GatesUndecided extends Schema.TaggedError<GatesUndecided>()("GatesUndecide
 }) {}
 
 const NAME = "checks-lint";
-const USAGE = "usage: lint.ts [--full | --desk] [<base-ref> <head-ref>]";
+const USAGE = "usage: lint.ts [--full | --desk] [<base-ref> <head-ref>] | --night";
+const NIGHT = "--night";
 const PULL_REQUEST_EVENT = "pull_request";
 const SHALLOW_HINT = "a CI checkout needs actions/checkout fetch-depth: 0";
 
@@ -159,11 +160,16 @@ function outcomeOf(exitCode: number): Outcome {
   return exitCode === 1 ? "violated" : "undecided";
 }
 
-const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
+const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range, wholeTree: boolean) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const script = (yield* Path.Path).join(import.meta.dir, "..", gate.vector, gate.file);
   const program = gate.file.endsWith(".sh") ? "sh" : process.execPath;
-  const args = gate.reads === "range" ? [script, ...range.refs] : [script, ...(gate.args ?? [])];
+  const args =
+    gate.reads === "range"
+      ? wholeTree
+        ? [script, WHOLE_TREE, ...range.refs]
+        : [script, ...range.refs]
+      : [script, ...(gate.args ?? [])];
   const extra = gate.env === undefined ? {} : { env: gate.env, extendEnv: true };
   const exitCode = yield* spawner
     .exitCode(ChildProcess.make(program, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit", ...extra }))
@@ -175,6 +181,11 @@ const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
   return { gate, outcome: outcomeOf(exitCode) };
 });
 
+const wholeTreeRange = Effect.fn("wholeTreeRange")(function* () {
+  const head = yield* commitOf("HEAD");
+  return { refs: [head], source: "the whole tree at HEAD" } satisfies Range;
+});
+
 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;
@@ -187,39 +198,62 @@ const scopedGates = Effect.fn("scopedGates")(function* (range: Range, root: stri
   return { bins: scope.gates, detail: "" };
 });
 
+const pullRequestSelection = Effect.fn("pullRequestSelection")(function* (
+  split: { readonly mode: LintMode; readonly rest: readonly string[] },
+  range: Range,
+  root: string,
+  applicable: readonly KitGate[],
+) {
+  if (split.mode === "desk") {
+    return {
+      bins: applicable.filter((gate) => FAST_TREE_GATES.includes(gate.bin)).map((gate) => gate.bin),
+      detail: "the desk run",
+    };
+  }
+  if (split.mode === "full") {
+    return { bins: applicable.map((gate) => gate.bin), detail: "the full run (--full)" };
+  }
+  return yield* scopedGates(range, root);
+});
+
+function selectionDetail(night: boolean, mode: LintMode, scopeDetail: string, count: number): string | undefined {
+  if (night) return undefined;
+  if (mode === "scoped" && scopeDetail === "") return `${count} gate(s) for this change`;
+  return scopeDetail === "" ? undefined : scopeDetail;
+}
+
 const lint = Effect.gen(function* () {
-  const split = splitMode(process.argv.slice(2));
+  const raw = process.argv.slice(2);
+  const night = raw.includes(NIGHT);
+  if (night && raw.length > 1) return yield* new Usage({ message: USAGE });
+  const split = night ? { mode: "full" as const, rest: [] as readonly string[] } : splitMode(raw);
   if (split === undefined) return yield* new Usage({ message: USAGE });
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const range = yield* resolveRange(split.rest);
+  const range = night ? yield* wholeTreeRange() : yield* resolveRange(split.rest);
   yield* Console.log(`${NAME}: ${describe(range)} from ${range.source}`);
-  const applicable = yield* Effect.filter(KIT_GATES, (gate) =>
+  const applicable = yield* Effect.filter(night ? NIGHT_GATES : PR_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 scoped = night
+    ? { bins: applicable.map((gate) => gate.bin) as readonly string[] | undefined, detail: "" }
+    : yield* pullRequestSelection(split, range, root, applicable);
   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 detail = selectionDetail(night, split.mode, scoped.detail, gates.length);
+  if (detail !== undefined) yield* Console.log(`${NAME}: ${detail}`);
+  const verdicts = yield* Effect.forEach(gates, (gate) => runGate(gate, range, night));
   const failed = verdicts.filter((verdict) => verdict.outcome !== "passed");
   if (failed.length === 0) {
     yield* Console.log(`${NAME}: ${gates.length} gate(s) pass`);
     return true;
   }
-  const summary = `${failed.length} of ${gates.length} gate(s) failed: ${failed.map((verdict) => verdict.gate.bin).join(", ")}`;
+  const names = failed.map((verdict) => verdict.gate.bin).join(", ");
   if (failed.every((verdict) => verdict.outcome === "undecided")) {
-    return yield* new GatesUndecided({ message: summary });
+    return yield* new GatesUndecided({ message: `${failed.length} of ${gates.length} gate(s) undecided: ${names}` });
   }
+  const summary = `${failed.length} of ${gates.length} gate(s) failed: ${names}`;
   yield* Console.error(`${NAME}: ${summary}`);
   return false;
 });

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/testing/night-run-findings.ts

@@ -19,7 +19,8 @@ export type PreviousNight = { readonly url: string; readonly record: NightRecord
 export type Finding =
   | { readonly kind: "mutation"; readonly file: string; readonly before: Score; readonly after: Score; readonly since: string }
   | { readonly kind: "test"; readonly file: string; readonly name: string }
-  | { readonly kind: "crash"; readonly file: string };
+  | { readonly kind: "crash"; readonly file: string }
+  | { readonly kind: "gates"; readonly file: string };
 
 function scoreOf(file: ReportFile): Score {
   let detected = 0;
@@ -45,6 +46,7 @@ function fell(before: Score, after: Score): boolean {
 export function keyOf(finding: Finding): string {
   if (finding.kind === "mutation") return `mutation:${finding.file}`;
   if (finding.kind === "test") return `test:${finding.file}${NAME_SEPARATOR}${finding.name}`;
+  if (finding.kind === "gates") return `gates:${finding.file}`;
   return `test:${finding.file}`;
 }
 
@@ -65,8 +67,23 @@ function testFindings(reports: readonly TestReport[]): readonly Finding[] {
   return [...new Map(failing.map((finding) => [keyOf(finding), finding])).values()];
 }
 
-export function findingsOf(previous: Option.Option<PreviousNight>, tonight: Tonight): readonly Finding[] {
-  return [...scoreFindings(previous, tonight.scores), ...testFindings(tonight.tests)].sort((one, other) => keyOf(one).localeCompare(keyOf(other)));
+export function findingsOf(previous: Option.Option<PreviousNight>, tonight: Tonight, gates: readonly Finding[] = []): readonly Finding[] {
+  return [...scoreFindings(previous, tonight.scores), ...testFindings(tonight.tests), ...gates].sort((one, other) =>
+    keyOf(one).localeCompare(keyOf(other)),
+  );
+}
+
+const FAILED_GATES = /of \d+ gate\(s\) failed: (.+)/;
+const PASSED_GATES = /gate\(s\) pass/;
+
+export function gatesOf(log: string): readonly Finding[] {
+  const names = log
+    .split("\n")
+    .flatMap((line) => FAILED_GATES.exec(line)?.[1]?.split(",") ?? [])
+    .map((name) => name.trim())
+    .filter((name) => name !== "");
+  if (names.length > 0) return [...new Map(names.map((file): [string, Finding] => [file, { kind: "gates", file }])).values()];
+  return PASSED_GATES.test(log) ? [] : [{ kind: "gates", file: "checks-lint" }];
 }
 
 export function percent(score: Score): string {

package/src/testing/night-run.ts

@@ -5,11 +5,11 @@ import { DEFAULT_BRANCH } from "../core/gates.ts";
 import { runMain, Usage } from "../core/main.ts";
 import { gh, type GitHubFailure, gitHubJson, REPOSITORY } from "../delivery/github.ts";
 import { parseReport as parseMutationReport } from "./mutation-compare.ts";
-import { type Finding, findingsOf, keyOf, NightRecordSchema, type NightRecord, percent, type PreviousNight, scoresOf, type TestReport } from "./night-run-findings.ts";
+import { type Finding, findingsOf, gatesOf, keyOf, NightRecordSchema, type NightRecord, percent, type PreviousNight, scoresOf, type TestReport } from "./night-run-findings.ts";
 import { parseReport as parseTestReport } from "./test-report.ts";
 
 const NAME = "checks-night-run";
-const USAGE = `usage: ${NAME} [--mutation <mutation-report>] [--tests <junit-report>]...`;
+const USAGE = `usage: ${NAME} [--mutation <mutation-report>] [--tests <junit-report>]... [--gates <lint-log>]`;
 export const LABEL = "night-run";
 const LABEL_COLOR = "5319e7";
 const LABEL_DESCRIPTION = "A regression a night run on main found";
@@ -23,19 +23,22 @@ class NightRunFailure extends Schema.TaggedError<NightRunFailure>()("NightRunFai
   message: Schema.String,
 }) {}
 
-export type Options = { readonly mutation: Option.Option<string>; readonly tests: readonly string[] };
+export type Options = { readonly mutation: Option.Option<string>; readonly tests: readonly string[]; readonly gates: Option.Option<string> };
 
 export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<Options, Usage> {
   const mutation: string[] = [];
   const tests: string[] = [];
+  const gates: string[] = [];
   for (let at = 0; at < argv.length; at += 2) {
     const [flag, value] = [argv[at], argv[at + 1]];
-    const into = flag === "--mutation" ? mutation : flag === "--tests" ? tests : undefined;
+    const into = flag === "--mutation" ? mutation : flag === "--tests" ? tests : flag === "--gates" ? gates : undefined;
     if (into === undefined || value === undefined || value.startsWith("--")) return yield* new Usage({ message: USAGE });
     into.push(value);
   }
-  if (mutation.length > 1 || mutation.length + tests.length === 0) return yield* new Usage({ message: USAGE });
-  return { mutation: Option.fromNullishOr(mutation[0]), tests };
+  if (mutation.length > 1 || gates.length > 1 || mutation.length + tests.length + gates.length === 0) {
+    return yield* new Usage({ message: USAGE });
+  }
+  return { mutation: Option.fromNullishOr(mutation[0]), tests, gates: Option.fromNullishOr(gates[0]) };
 });
 
 export type OpenIssue = { readonly number: number; readonly key: string };
@@ -102,6 +105,7 @@ const openIssues = Effect.gen(function* () {
 function fullTitleOf(finding: Finding): string {
   if (finding.kind === "mutation") return `Night run: mutation score fell in ${finding.file}`;
   if (finding.kind === "test") return `Night run: ${finding.file} > ${finding.name} fails`;
+  if (finding.kind === "gates") return `Night run: nightly gate ${finding.file} failed`;
   return `Night run: ${finding.file} crashed its test worker`;
 }
 
@@ -125,6 +129,7 @@ export function findingText(finding: Finding, run: string): string {
     ].join("\n");
   }
   if (finding.kind === "test") return `The night run ${run} failed \`${finding.name}\` in \`${finding.file}\`.`;
+  if (finding.kind === "gates") return `The night run ${run} failed nightly gate \`${finding.file}\`.`;
   return `The night run ${run} lost every result of \`${finding.file}\`, because the worker running it crashed.`;
 }
 
@@ -240,8 +245,9 @@ const nightRun = Effect.gen(function* () {
   const actions = yield* actionsRun;
   const scores = Option.isSome(options.mutation) ? Option.some(yield* tonightScores(options.mutation.value)) : Option.none<NightRecord["scores"]>();
   const tests: TestReport[] = yield* Effect.forEach(options.tests, testReport);
+  const gates: readonly Finding[] = Option.isSome(options.gates) ? gatesOf(yield* readText(options.gates.value)) : [];
   const previous = Option.isSome(scores) ? yield* previousNight(actions) : Option.none<PreviousNight>();
-  const findings = findingsOf(previous, { scores: Option.getOrElse(scores, () => ({})), tests });
+  const findings = findingsOf(previous, { scores: Option.getOrElse(scores, () => ({})), tests }, gates);
   const filing: Filing = actions.ref === `refs/heads/${DEFAULT_BRANCH}` ? { onMain: true, filed: yield* fileFindings(findings, actions.run) } : { onMain: false, ref: actions.ref };
   if (filing.onMain && Option.isSome(scores)) yield* writeRecord({ scores: scores.value });
   yield* Console.log(report(actions.run, Option.map(scores, (tonight) => Object.keys(tonight).length), previous, findings, filing));

package/src/testing/quarantine-clock.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
 import { commitOf, git, isShallowBoundary, refArgs, writtenAt } from "../core/git.ts";
-import { runMain } from "../core/main.ts";
+import { WHOLE_TREE } from "../core/gates.ts";
+import { Usage, runMain } from "../core/main.ts";
 import { TEST_FILE } from "./test-layout.ts";
 
 export const QUARANTINE = "tests/quarantine/";
@@ -12,7 +13,7 @@ export class QuarantineError extends Schema.TaggedError<QuarantineError>()("Quar
   message: Schema.String,
 }) {}
 
-const USAGE = "usage: quarantine-clock.ts <ref> | <base-ref> <head-ref>";
+const USAGE = "usage: quarantine-clock.ts <ref> | <base-ref> <head-ref> | --whole-tree <head-ref>";
 
 export type Entry =
   | { readonly kind: "entered"; readonly sha: string; readonly at: number; readonly day: string }
@@ -133,6 +134,13 @@ export const runHead = Effect.fn("runHead")(function* (root: string, head: strin
 
 const clock = Effect.gen(function* () {
   const { first, second } = yield* refArgs(process.argv.slice(2), USAGE);
+  if (first === WHOLE_TREE) {
+    if (second === undefined) return yield* new Usage({ message: USAGE });
+    const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+    const result = yield* runHead(root, yield* commitOf(second));
+    yield* Console.log(report(result));
+    return result.overdue.length === 0;
+  }
   if (second !== undefined) yield* commitOf(first);
   const head = yield* commitOf(second ?? first);
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();

package/docs/gates/checks-exports.md

@@ -1,104 +0,0 @@
----
-kind: reference
-audience: consumers
----
-# checks-exports
-
-`checks-exports` is the gate that refuses an exported value or type nothing imports.
-
-## What it checks
-
-It runs Knip with the repository's own configuration and names each exported value and type no file imports.
-It reads only the exports and types issue types, so an unreferenced file or an unused dependency never fails it.
-It asks Knip for those issue types itself, so a configuration that narrows `include` or excludes them still has its exports judged.
-A configuration that turns the exports or types rules off silences those symbols, so keep both rules on.
-It holds each reported symbol against `exports-baseline.json`, and fails on any symbol the baseline does not hold.
-It fails on any baseline entry the range adds unless Knip reports that same symbol unused at the base, so the baseline records debt that already existed and never debt the range creates.
-It fails on any baseline entry Knip no longer reports, so the baseline only shrinks.
-It fails when the repository tracks no TypeScript source, since an empty scan would pass without judging anything.
-It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead export from a public one.
-
-## What it reads
-
-It runs Knip over the working tree, so an uncommitted file is judged like a committed one.
-It reads the repository's Knip configuration, which names the entries.
-It reads `exports-baseline.json` in the repository root, which holds each accepted unused export as a file, kind and name triple.
-It reads `exports-baseline.json` again at the base of the range, where a commit without the file counts as empty.
-When the range adds baseline entries, it runs Knip again on a temporary checkout of the base and removes the checkout when it ends.
-That checkout links the repository's `node_modules`, so a configuration importing the kit's builder loads there too.
-The repository writes `knip.config.ts` with the kit's builder, which requires `entry`, the files nothing imports:
-
-```ts
-import { defineConfig } from "@avi2dg/checks/knip";
-
-export default defineConfig({ entry: ["src/index.ts"] });
-```
-
-The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts`, `dependency-cruiser.config.ts` and `oxlint.config.ts` to the entries.
-The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
-
-## Arguments
-
-```sh
-checks-exports <base-ref> <head-ref>
-checks-exports <ref>
-checks-exports --write
-```
-
-With two arguments the base is where the head branched off, at their merge-base.
-When the checked-out commit is a merge of the head ref and one other commit, as a pull request's default checkout is, the base is that other commit instead.
-So under `checks-lint` a pull request's merge checkout is judged against the base branch tip it merges, and a symbol that branch already baselined does not count as added.
-With one the base is that commit's parent, or the empty tree for a repository's first commit, where nothing counts as already unused.
-With `--write` it records every unused export and type Knip reports into `exports-baseline.json`, the way `oxlint --suppress-all` seeds `oxlint-suppressions.json`.
-
-## Seeding a baseline
-
-A repository adopting the gate runs `checks-exports --write` on a branch that changes no source and commits the file it writes.
-The gate passes that range, since Knip reports every seeded symbol unused at the base too.
-A seed written after the range adds a dead export, or after it removes the last import of one, fails on that symbol.
-
-## Exit codes
-
-| Code | When |
-| --- | --- |
-| 0 | no reported symbol is unlisted, no baseline entry is added or stale, or `--write` recorded the baseline |
-| 1 | a reported symbol is unlisted, a baseline entry is added or stale or the repository holds no Knip configuration |
-| 2 | a ref does not resolve, the repository tracks no TypeScript source, Knip cannot run, or a report or baseline does not parse |
-
-## Sample output
-
-```
-exports: 2 unused export(s) not in exports-baseline.json:
-  src/used.ts: unusedExport (export)
-  src/used.ts: UnusedOptions (type)
-```
-
-A baseline entry the range adds fails when Knip does not report its symbol unused at the base:
-
-```
-exports: 1 exports-baseline.json export(s) the range adds that its base did not leave unused, remove the export instead:
-  src/used.ts: unusedExport (export)
-```
-
-A passing run with a held baseline counts what it holds:
-
-```
-exports: 2 unused export(s) in exports-baseline.json, and no new ones
-```
-
-A passing run with an empty baseline says so:
-
-```
-exports: no unused exports or types
-```
-
-## When it runs
-
-`checks-lint` runs it over each pull request's range when the repository tracks a `.ts` or `.tsx` file.
-Such a repository names its entries in a Knip configuration.
-
-## Related topics
-
-- [checks-lint](checks-lint.md)
-- [checks-suppressions-ratchet](checks-suppressions-ratchet.md)
-- [checks-unused](checks-unused.md)

package/docs/gates/checks-imports.md

@@ -1,64 +0,0 @@
----
-kind: reference
-audience: consumers
----
-# checks-imports
-
-`checks-imports` is the gate that holds a repository's imports to the dependency rules, with the kit's defaults when the repository writes no config.
-
-## What it checks
-
-It runs dependency-cruiser over every tracked `.ts`, `.tsx`, `.mts` and `.cts` file and names each violation with its rule, the importing module and the module it reaches.
-It fails on a violation whose rule has `error` severity, and lists a `warn` or `info` violation without failing.
-The rules are those [The dependency rules](../configs/dependency-rules.md) lists, plus each rule the repository's config adds.
-
-In a repository whose `package.json` lists `astro` under `dependencies` or `devDependencies`, the kit's defaults leave `no-orphans` out.
-The cruise never reads an `.astro` file, so a `.ts` module only a page imports would read as an orphan.
-[checks-unused](checks-unused.md) already names each file no entry reaches there, and it reads `.astro` imports.
-A repository that wants the rule back lists its own `no-orphans` under `forbidden` in `dependency-cruiser.config.ts`.
-
-## What it reads
-
-It reads the working tree from the repository root, and leaves out a tracked file the working tree no longer holds.
-It cruises against the first config it finds there:
-
-1. `dependency-cruiser.config.ts`, which calls `defineConfig` from `@avi2dg/checks/dependency-cruiser`.
-1. A config under one of dependency-cruiser's own names, such as `.dependency-cruiser.cjs`.
-1. The kit's defaults, which `defineConfig()` returns with no argument.
-
-It runs dependency-cruiser from the installed kit under Bun, which loads a TypeScript config wherever it sits.
-
-## Arguments
-
-It takes none.
-
-## Exit codes
-
-| Code | When |
-| --- | --- |
-| 0 | no import breaks an `error` rule |
-| 1 | an import breaks an `error` rule |
-| 2 | the repository tracks no TypeScript, or dependency-cruiser cannot load the config or run |
-
-## Sample output
-
-```
-imports: 2 violation(s) in 36 module(s) cruised against dependency-cruiser.config.ts
-  error not-to-dev-dep: src/index.ts → node_modules/effect/dist/index.js
-  error no-orphans: src/lonely.ts
-```
-
-A passing run counts the modules it cruised:
-
-```
-imports: 225 module(s) cruised against dependency-cruiser.config.ts, no violation
-```
-
-## When it runs
-
-`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
-
-- [The dependency rules](../configs/dependency-rules.md)
-- [checks-lint](checks-lint.md)

package/docs/gates/checks-unused.md

@@ -1,66 +0,0 @@
----
-kind: reference
-audience: consumers
----
-# checks-unused
-
-`checks-unused` is the gate that refuses a TypeScript or Astro file no entry point reaches.
-
-## What it checks
-
-It runs Knip with the repository's own configuration and names each `.ts`, `.tsx` or `.astro` file no entry reaches.
-It reads only the files issue type, so an unused export or dependency never fails it.
-It asks Knip for that issue type itself, so a configuration that narrows `include`, excludes files or turns the files rule off still has its files judged.
-It fails when the repository tracks no `.ts`, `.tsx` or `.astro` file, since an empty scan would pass without judging anything.
-It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead file from an entry point.
-
-## What it reads
-
-It reads the working tree, so an uncommitted file is judged like a committed one.
-It reads the repository's Knip configuration, which names the entries.
-The repository writes `knip.config.ts` with the kit's builder, which requires `entry`, the files nothing imports:
-
-```ts
-import { defineConfig } from "@avi2dg/checks/knip";
-
-export default defineConfig({ entry: ["src/index.ts"] });
-```
-
-The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts`, `dependency-cruiser.config.ts` and `oxlint.config.ts` to the entries.
-In a repository that depends on `astro`, Knip reads `.astro` imports, so a file only an `.astro` entry imports counts as used and an `.astro` file no entry reaches is named.
-The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
-
-## Arguments
-
-It takes none.
-
-## Exit codes
-
-| Code | When |
-| --- | --- |
-| 0 | no tracked file is unreferenced |
-| 1 | a tracked file is unreferenced or the repository holds no Knip configuration |
-| 2 | the repository tracks no TypeScript or Astro source, Knip cannot run, or its configuration does not parse |
-
-## Sample output
-
-```
-unused: 1 unreferenced file(s):
-  src/planted-dead.ts
-```
-
-A passing run counts the files it judged:
-
-```
-unused: no unreferenced files among 110 tracked .ts/.tsx/.astro file(s)
-```
-
-## When it runs
-
-`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
-
-- [checks-lint](checks-lint.md)
-- [checks-repetition](checks-repetition.md)