@avi2dg/checks 0.56.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/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/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)