@avi2dg/checks 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.26.0
+
+Released 2026-09-27.
+
+### Breaking changes
+
+- **complexity:** add checks-exports gate holding unused exports to a shrinking baseline [#89](https://github.com/avi2d/checks/pull/89)
+- move doc templates into dist/templates and presets into src/quality [#88](https://github.com/avi2d/checks/pull/88)
+
 ## 0.25.0
 
 Released 2026-09-27.

package/README.md

@@ -119,6 +119,7 @@ Each gate belongs to the vector it judges a repository on, and the table groups
 | complexity | [`checks-suppressions-ratchet`](docs/gates/checks-suppressions-ratchet.md) | the range | every repository |
 | complexity | [`checks-repetition`](docs/gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
 | complexity | [`checks-unused`](docs/gates/checks-unused.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| complexity | [`checks-exports`](docs/gates/checks-exports.md) | the range | a repository tracking `*.ts` or `*.tsx` |
 | quality | [`checks-lint-coverage`](docs/gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
@@ -170,13 +171,11 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `commitlint.config.js` | the shared commitlint config |
 | `dependency-cruiser.config.js` | the shared dependency-cruiser base |
 | `knip-base.json` | the Knip base a repository's configuration imports |
-| `src/` | every bin, which a package script calls by its `checks-` name, and the modules the bins import |
-| `templates/` | one template per kind of doc file, which a new doc file starts from |
-| `presets/` | the Effect rule blocks a repository copies into its native config |
+| `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect rule blocks under `src/quality/presets/` |
+| `dist/` | the compiled oxlint plugins and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
 | `stryker.preset.js` | the Stryker mutation-testing preset |
 | `tsconfig.effect.json` | the tsconfig fragment with the Effect language-service block |
-| `dist/` | the compiled oxlint plugins, one per purpose |
 
 <!-- end generated shipped -->
 

package/docs/configs/effect-rules.md

@@ -31,7 +31,7 @@ The repo's `.oxlintrc.json` owns its Effect paths and exemptions in an override:
 }
 ```
 
-The kit ships the rule block in `presets/effect.oxlint.json` for copying into the override.
+The kit ships the rule block in `src/quality/presets/effect.oxlint.json` for copying into the override.
 Each config in an oxlint `extends` chain sets `plugins` explicitly, because an omitted list enables defaults across the chain.
 `unicorn/no-process-exit` does not check a shebang script, so a bin can use `eslint/no-restricted-properties` for `process.exit`.
 
@@ -39,7 +39,7 @@ Each config in an oxlint `extends` chain sets `plugins` explicitly, because an o
 
 The repository's `tsconfig.json` holds its Effect override under `compilerOptions.plugins`.
 The override includes the same source paths and excludes the same exempt paths as oxlint.
-The kit ships severity values in `presets/effect.language-service.json` for the override's `options`.
+The kit ships severity values in `src/quality/presets/effect.language-service.json` for the override's `options`.
 The kit's `tsconfig.effect.json` keeps the shared language service diagnostics.
 
 ## Related topics

package/docs/configs/native-settings.md

@@ -13,8 +13,9 @@ A consuming repository puts each setting in the file its tool reads.
 | `.github/workflows/*.yml` | Pull request commands, scheduled commands, runner labels | GitHub Actions and `checks-ci-wiring` |
 | `.oxlintrc.json` | Effect paths, exemptions, file size, function size, statements, cognitive complexity and depth | oxlint |
 | `oxlint-suppressions.json` | The existing violations oxlint suppresses, per file and rule | oxlint and `checks-suppressions-ratchet` |
+| `exports-baseline.json` | The existing unused exports and types, per file, kind and name | `checks-exports` |
 | `.jscpd.json` | The `path` and `ignore` globs of the files repetition is measured in | jscpd and `checks-repetition` |
-| `knip.config.ts` | The `entry` globs Knip traces unreferenced files from, spread over the kit's `knip-base.json` | Knip and `checks-unused` |
+| `knip.config.ts` | The `entry` globs Knip traces unreferenced files from, spread over the kit's `knip-base.json` | Knip, `checks-unused` and `checks-exports` |
 | `tsconfig.json` | Effect language service scope and severity | TypeScript and Effect language service |
 | `package.json` | `scripts` with the `checks-vendor` arguments in `prepare`, `author` and `contributors` | Bun, `checks-commit-identity` and `checks-vendor` |
 | `bunfig.toml` | Test discovery and quarantine exclusion | Bun and `checks-test-layout` |

package/docs/design.md

@@ -30,7 +30,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
 - `dist/` is committed.
   No `prepack` or `prepublishOnly` builds it, so a publish ships whatever bundle the publishing worktree holds.
   Rebuild it after pulling with `bun run build`.
-  `bun run build` also emits `templates/` and `CHANGELOG.md`, which are committed the same way.
+  `bun run build` also emits `dist/templates/` and `CHANGELOG.md`, which are committed the same way.
   CI runs `git diff --exit-code` over the whole tree after the build, because a test that compares a generated file with its source passes on the copy the build just rewrote.
 - `CHANGELOG.md` is generated, so a release commit carries it and the tarball ships it.
   The commit that bumps package.json `version` closes its release, and the `v*` tag goes on that commit, so commits merged after it wait for the next release.
@@ -78,7 +78,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   Setting your own `options.enhancedResolveOptions` replaces the base's, so restate `exportsFields` and `conditionNames` if you do.
 - dependency-cruiser `extends` merges same-name `forbidden` rules with the child's fields winning.
   That is the entry-point and layer recipe under Boundaries in [The dependency rules](configs/dependency-rules.md).
-- The templates in `templates/` are rendered from `src/docs/doc-templates.ts`, the spec `checks-docs` reads.
+- The templates in `dist/templates/` are rendered from `src/docs/doc-templates.ts`, the spec `checks-docs` reads.
   A template written by hand beside the check agrees with it only until someone edits one of them.
 - A page's Diátaxis mode comes from `kind` front matter on the page, whatever directory holds it.
   The repository makes the judgment beside the page, and the check holds it to that template.

package/docs/gates/checks-docs.md

@@ -11,23 +11,25 @@ audience: consumers
 It holds each doc file a change touches to the template for its kind, and lists every other doc file that does not conform yet without failing.
 It holds each line a change adds or edits in a living doc or an agent file to the prose rules, as [The prose rules](#the-prose-rules) says.
 It fails when a living doc names a path, link or command that does not resolve, and the range added it or broke it, as [Paths, links and commands](#paths-links-and-commands) says.
-The package ships one template per kind under `templates/`, and a repository starts a new doc file by copying one:
+The package ships one template per kind under `dist/templates/`, and a repository starts a new doc file by copying one:
 
 ```sh
-cp node_modules/@avi2dg/checks/templates/how-to.md docs/add-a-supplier.md
+cp node_modules/@avi2dg/checks/dist/templates/how-to.md docs/add-a-supplier.md
 ```
 
+A host resolves a template as `@avi2dg/checks/templates/how-to.md`, which keeps pointing at it wherever the package holds the templates.
+
 <!-- generated doc-kinds: bun run build writes it from src/docs/doc-rules.ts, src/docs/doc-templates.ts and scripts/doc-blocks.ts -->
 
 | File | Kind | Template |
 | --- | --- | --- |
-| `README.md` | readme | `templates/readme.md` |
-| `CHANGELOG.md` | changelog | `templates/changelog.md` |
-| `AGENTS.md` | agents | `templates/agents.md` |
-| `CLAUDE.md` | claude | `templates/claude.md` |
-| `CONTRIBUTING.md` | how-to | `templates/how-to.md` |
-| each file in `docs/adr/` but its generated index, `README.md` | adr | `templates/adr.md` |
-| a page with `kind` in front matter | tutorial, how-to, reference or explanation | `templates/<mode>.md` |
+| `README.md` | readme | `dist/templates/readme.md` |
+| `CHANGELOG.md` | changelog | `dist/templates/changelog.md` |
+| `AGENTS.md` | agents | `dist/templates/agents.md` |
+| `CLAUDE.md` | claude | `dist/templates/claude.md` |
+| `CONTRIBUTING.md` | how-to | `dist/templates/how-to.md` |
+| each file in `docs/adr/` but its generated index, `README.md` | adr | `dist/templates/adr.md` |
+| a page with `kind` in front matter | tutorial, how-to, reference or explanation | `dist/templates/<mode>.md` |
 
 <!-- end generated doc-kinds -->
 

package/docs/gates/checks-exports.md

@@ -0,0 +1,104 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-exports
+
+`checks-exports` is the gate that refuses an exported value or type nothing imports, and a reader looks it up when Knip names a symbol no file reaches.
+
+## 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 base loads there too.
+Knip configurations do not extend a package file, so the consumer configuration imports the kit's base and spreads it:
+
+```ts
+import base from "@avi2dg/checks/knip-base.json";
+
+export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
+```
+
+The base in `knip-base.json` reports only unreferenced files.
+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
+```
+
+## Opting out
+
+`checks-lint` runs this gate only when the repository tracks `.ts` or `.tsx` files.
+A repository that tracks one 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,8 @@
     "src/complexity/suppressions-ratchet.ts",
     "src/complexity/repetition.ts",
     "src/complexity/unused.ts",
+    "src/complexity/exports.ts",
+    "src/complexity/knip.ts",
     "src/testing/quarantine-clock.ts",
     "src/docs/docs.ts",
     "src/dependencies/vendor.ts",
@@ -56,9 +58,9 @@
     "src/docs/doc-references.ts",
     "src/docs/doc-snapshot.ts",
     "src/docs/doc-templates.ts",
-    "templates/",
-    "presets/effect.oxlint.json",
-    "presets/effect.language-service.json",
+    "dist/templates/",
+    "src/quality/presets/effect.oxlint.json",
+    "src/quality/presets/effect.language-service.json",
     "oxlintrc.json",
     "stryker.preset.js",
     "tsconfig.effect.json",
@@ -72,6 +74,7 @@
     "./scripts/comment-matchers.ts": "./src/quality/comment-matchers.ts",
     "./scripts/prose-matchers.ts": "./src/docs/prose-matchers.ts",
     "./stryker.preset.js": "./stryker.preset.js",
+    "./templates/*": "./dist/templates/*",
     "./tsconfig.effect.json": "./tsconfig.effect.json"
   },
   "bin": {
@@ -91,6 +94,7 @@
     "checks-suppressions-ratchet": "src/complexity/suppressions-ratchet.ts",
     "checks-repetition": "src/complexity/repetition.ts",
     "checks-unused": "src/complexity/unused.ts",
+    "checks-exports": "src/complexity/exports.ts",
     "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
     "checks-docs": "src/docs/docs.ts",
     "checks-vendor": "src/dependencies/vendor.ts"
@@ -116,7 +120,6 @@
     "@oxlint/plugins": "1.83.0",
     "@swc/core": "1.16.2",
     "@types/bun": "^1.3.0",
-    "ajv": "8.20.0",
     "dependency-cruiser": "18.4.0",
     "effect": "4.0.0-rc.115",
     "jscpd": "5.3.2",

package/src/complexity/exports.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { checkoutFiles, commitOf, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+import { knipReport, scanTree } from "./knip.ts";
+
+export type UnusedSymbol = {
+  readonly file: string;
+  readonly kind: "export" | "type";
+  readonly name: string;
+};
+
+export type Baseline = readonly UnusedSymbol[];
+
+export type Held = {
+  readonly reported: readonly UnusedSymbol[];
+  readonly base: Baseline;
+  readonly head: Baseline;
+  readonly unusedAtBase: readonly UnusedSymbol[];
+};
+
+export type Drift = {
+  readonly unlisted: readonly UnusedSymbol[];
+  readonly added: readonly UnusedSymbol[];
+  readonly stale: readonly UnusedSymbol[];
+};
+
+const NAME = "exports";
+export const BASELINE_FILE = "exports-baseline.json";
+const INCLUDED = ["--include", "exports,types"];
+const WRITE = "--write";
+const USAGE = `usage: exports.ts <ref> | <base-ref> <head-ref> | ${WRITE}`;
+
+class ExportsError extends Schema.TaggedError<ExportsError>()("ExportsError", {
+  message: Schema.String,
+}) {}
+
+const KnipSymbol = Schema.Struct({ name: Schema.String });
+
+const decodeKnipReport = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      issues: Schema.Array(
+        Schema.Struct({
+          file: Schema.String,
+          exports: Schema.optional(Schema.Array(KnipSymbol)),
+          types: Schema.optional(Schema.Array(KnipSymbol)),
+        }),
+      ),
+    }),
+  ),
+);
+
+const decodeBaseline = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Array(
+      Schema.Struct({
+        file: Schema.String,
+        kind: Schema.Literals(["export", "type"]),
+        name: Schema.String,
+      }),
+    ),
+  ),
+);
+
+function byPosition(a: UnusedSymbol, b: UnusedSymbol): number {
+  return a.file.localeCompare(b.file) || a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name);
+}
+
+export const symbolsOf = Effect.fn("symbolsOf")(function* (stdout: string) {
+  const { issues } = yield* decodeKnipReport(stdout).pipe(
+    Effect.mapError((cause) => new ExportsError({ 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 ExportsError({ message: `${where} does not decode: ${cause.message}` })),
+  );
+});
+
+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}`);
+});
+
+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);
+}
+
+export function driftOf({ reported, base, head, unusedAtBase }: Held): Drift {
+  return {
+    unlisted: outside(reported, head),
+    added: outside(head, [...base, ...unusedAtBase]),
+    stale: outside(head, reported),
+  };
+}
+
+function describe(symbol: UnusedSymbol): string {
+  return `  ${symbol.file}: ${symbol.name} (${symbol.kind})`;
+}
+
+export function report(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 }) => [`${NAME}: ${symbols.length} ${what}`, ...symbols.map(describe)]).join("\n");
+  }
+  return head.length === 0
+    ? `${NAME}: no unused exports or types`
+    : `${NAME}: ${head.length} unused export(s) in ${BASELINE_FILE}, and no new ones`;
+}
+
+const scan = scanTree(NAME, INCLUDED).pipe(Effect.mapError((cause) => new ExportsError({ message: cause.message })));
+
+// Knip loads the configuration's imports, such as the kit's knip-base.json, 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 readonly UnusedSymbol[];
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const tree = yield* checkoutFiles(rev, files, yield* fs.makeTempDirectoryScoped({ prefix: "checks-exports-" }), 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 ExportsError({ 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 check = Effect.fn("check")(function* (first: string, second: string | undefined) {
+  const { root, reported } = yield* scan;
+  if (reported.kind === "unconfigured") return false;
+  const baseRev = yield* judgedBase(first, second, root);
+  const base = yield* baselineAt(baseRev, root);
+  const head = yield* baselineInTree(root);
+  const unusedAtBase = outside(head, base).length === 0 ? [] : yield* unusedAt(baseRev, root);
+  const drift = driftOf({ reported: yield* symbolsOf(reported.stdout), base, head, unusedAtBase });
+  yield* Console.log(report(head, drift));
+  return drift.unlisted.length === 0 && drift.added.length === 0 && drift.stale.length === 0;
+});
+
+const seed = Effect.gen(function* () {
+  const { root, reported } = yield* scan;
+  if (reported.kind === "unconfigured") return false;
+  const symbols = yield* symbolsOf(reported.stdout);
+  yield* (yield* FileSystem.FileSystem).writeFileString(yield* baselinePath(root), `${JSON.stringify(symbols, null, 2)}\n`);
+  yield* Console.log(`${NAME}: wrote ${symbols.length} unused export(s) to ${BASELINE_FILE}`);
+  return true;
+});
+
+const gate = Effect.gen(function* () {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === WRITE) return yield* seed;
+  const { first, second } = yield* refArgs(args, USAGE);
+  return yield* check(first, second);
+});
+
+if (import.meta.main) runMain(NAME, gate);

package/src/complexity/knip.ts

@@ -0,0 +1,70 @@
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { collect, git } from "../core/git.ts";
+
+class KnipError extends Schema.TaggedError<KnipError>()("KnipError", {
+  message: Schema.String,
+}) {}
+
+const CONFIGS = [
+  ".knip.json",
+  ".knip.jsonc",
+  "knip.json",
+  "knip.jsonc",
+  "knip.js",
+  "knip.ts",
+  "knip.config.js",
+  "knip.config.ts",
+] as const;
+
+const TYPESCRIPT = ["*.ts", "*.tsx"];
+
+const hasKnipConfig = Effect.fn("hasKnipConfig")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  for (const name of CONFIGS) {
+    if (yield* fs.exists(path.join(root, name))) return true;
+  }
+  const manifest: unknown = yield* fs.readFileString(path.join(root, "package.json")).pipe(
+    Effect.flatMap((text) =>
+      Effect.try({
+        try: () => JSON.parse(text) as unknown,
+        catch: () => new KnipError({ message: "package.json does not parse as JSON" }),
+      })
+    ),
+  );
+  return typeof manifest === "object" && manifest !== null && "knip" in manifest;
+});
+
+const knipBinary = Effect.fn("knipBinary")(function* () {
+  const path = yield* Path.Path;
+  const main = yield* Effect.try({
+    try: () => new URL("../bin/knip.js", import.meta.resolve("knip")),
+    catch: () => new KnipError({ message: "cannot resolve knip from the installed kit" }),
+  });
+  return yield* path.fromFileUrl(main);
+});
+
+export const knipReport = Effect.fn("knipReport")(function* (root: string, args: readonly string[]) {
+  if (!(yield* hasKnipConfig(root))) return { kind: "unconfigured" } as const;
+  const run = yield* collect(process.execPath, [yield* knipBinary(), ...args, "--reporter", "json"], root).pipe(
+    Effect.mapError((cause) => new KnipError({ message: `cannot run knip: ${cause.message}` })),
+  );
+  if (run.exitCode !== 0 && run.exitCode !== 1) {
+    return yield* new KnipError({ message: `knip exits ${run.exitCode}: ${(run.stdout + run.stderr).trim()}` });
+  }
+  return { kind: "reported", stdout: run.stdout } as const;
+});
+
+export const scanTree = Effect.fn("scanTree")(function* (name: string, args: readonly string[]) {
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const tracked = (yield* git(["ls-files", "--", ...TYPESCRIPT], root))
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+  if (tracked.length === 0) return yield* new KnipError({ message: "no tracked .ts or .tsx files to scan" });
+  const reported = yield* knipReport(root, args);
+  if (reported.kind === "unconfigured") {
+    yield* Console.log(`${name}: no knip configuration names entry files, so add one extending the kit's knip-base.json`);
+  }
+  return { root, tracked: tracked.length, reported };
+});

package/src/complexity/unused.ts

@@ -1,22 +1,11 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { collect, git } from "../core/git.ts";
+import { Console, Effect, Schema } from "effect";
 import { runMain } from "../core/main.ts";
+import { scanTree } from "./knip.ts";
 
 export type Scan = { readonly tracked: number; readonly files: readonly string[] };
 
 const NAME = "unused";
-const CONFIGS = [
-  ".knip.json",
-  ".knip.jsonc",
-  "knip.json",
-  "knip.jsonc",
-  "knip.js",
-  "knip.ts",
-  "knip.config.js",
-  "knip.config.ts",
-] as const;
-const TYPESCRIPT = ["*.ts", "*.tsx"];
 const JUDGED = /\.tsx?$/;
 
 class UnusedError extends Schema.TaggedError<UnusedError>()("UnusedError", {
@@ -46,51 +35,13 @@ export function report({ tracked, files }: Scan): string {
   return [`${NAME}: ${files.length} unreferenced file(s):`, ...files.map((file) => `  ${file}`)].join("\n");
 }
 
-const hasConfig = Effect.fn("hasConfig")(function* (root: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  for (const name of CONFIGS) {
-    if (yield* fs.exists(path.join(root, name))) return true;
-  }
-  const manifest: unknown = yield* fs.readFileString(path.join(root, "package.json")).pipe(
-    Effect.flatMap((text) =>
-      Effect.try({
-        try: () => JSON.parse(text) as unknown,
-        catch: () => new UnusedError({ message: "package.json does not parse as JSON" }),
-      })
-    ),
-  );
-  return typeof manifest === "object" && manifest !== null && "knip" in manifest;
-});
-
-const knip = Effect.fn("knip")(function* () {
-  const path = yield* Path.Path;
-  const main = yield* Effect.try({
-    try: () => new URL("../bin/knip.js", import.meta.resolve("knip")),
-    catch: () => new UnusedError({ message: "cannot resolve knip from the installed kit" }),
-  });
-  return yield* path.fromFileUrl(main);
-});
-
 const unused = Effect.gen(function* () {
-  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const tracked = (yield* git(["ls-files", "--", ...TYPESCRIPT], root))
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line !== "");
-  if (tracked.length === 0) return yield* new UnusedError({ message: "no tracked .ts or .tsx files to scan" });
-  if (!(yield* hasConfig(root))) {
-    yield* Console.log(`${NAME}: no knip configuration names entry files, so add one extending the kit's knip-base.json`);
-    return false;
-  }
-  const run = yield* collect(process.execPath, [yield* knip(), "--files", "--reporter", "json"], root).pipe(
-    Effect.mapError((cause) => new UnusedError({ message: `cannot run knip: ${cause.message}` })),
+  const { tracked, reported } = yield* scanTree(NAME, ["--files"]).pipe(
+    Effect.mapError((cause) => new UnusedError({ message: cause.message })),
   );
-  if (run.exitCode !== 0 && run.exitCode !== 1) {
-    return yield* new UnusedError({ message: `knip exits ${run.exitCode}: ${(run.stdout + run.stderr).trim()}` });
-  }
-  const files = yield* filesOf(run.stdout);
-  yield* Console.log(report({ tracked: tracked.length, files }));
+  if (reported.kind === "unconfigured") return false;
+  const files = yield* filesOf(reported.stdout);
+  yield* Console.log(report({ tracked, files }));
   return files.length === 0;
 });
 

package/src/core/gates.ts

@@ -12,7 +12,7 @@ export const EVERY_REPOSITORY = "every repository";
 
 export const VECTORS = ["complexity", "quality", "testing", "docs", "delivery", "dependencies"] as const;
 
-export type Vector = (typeof VECTORS)[number];
+type Vector = (typeof VECTORS)[number];
 
 export type KitGate = {
   readonly bin: string;
@@ -41,5 +41,6 @@ export const KIT_GATES = [
   { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-quarantine-clock", vector: "testing", file: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
 ] as const satisfies readonly KitGate[];

package/src/core/swc.ts

@@ -1,7 +1,7 @@
 import { parse } from "@swc/core";
 import { Effect, Schema } from "effect";
 
-export class TypeScriptParseError extends Schema.TaggedError<TypeScriptParseError>()("TypeScriptParseError", {
+class TypeScriptParseError extends Schema.TaggedError<TypeScriptParseError>()("TypeScriptParseError", {
   message: Schema.String,
 }) {}
 

package/src/docs/doc-references.ts

@@ -1,6 +1,6 @@
 import { scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
 
-export type ReferenceKind = "path" | "link" | "command";
+type ReferenceKind = "path" | "link" | "command";
 
 export type Unresolved = {
   readonly kind: ReferenceKind;

package/src/docs/doc-snapshot.ts

@@ -2,7 +2,7 @@ import { Effect, FileSystem, Path, Schema } from "effect";
 import { anchoredTargets, anchorsOf, PACKAGE_MANIFEST, packagesOf, snapshotOf, type Unresolved } from "./doc-references.ts";
 import { git, pathsAt } from "../core/git.ts";
 
-export class ManifestUnreadable extends Schema.TaggedError<ManifestUnreadable>()("ManifestUnreadable", {
+class ManifestUnreadable extends Schema.TaggedError<ManifestUnreadable>()("ManifestUnreadable", {
   message: Schema.String,
 }) {}
 

package/src/docs/doc-templates.ts

@@ -9,21 +9,21 @@ export type Title =
   | { readonly type: "fixed"; readonly text: string }
   | { readonly type: "open"; readonly placeholder: string; readonly rule: HeadingRule; readonly prefix?: string };
 
-export type Outlined = {
+type Outlined = {
   readonly shape: "outline";
   readonly title: Title;
   readonly lead: readonly string[];
   readonly sections: readonly Slot[];
 };
 
-export type Exact = {
+type Exact = {
   readonly shape: "exact";
   readonly text: string;
 };
 
 export type Template = Outlined | Exact;
 
-export const TEMPLATE_DIRECTORY = "templates";
+export const TEMPLATE_DIRECTORY = "dist/templates";
 
 export const ADR_STATUSES = ["Proposed", "Accepted", "Rejected", "Deprecated", "Superseded", "Retired"] as const;
 

package/src/quality/comments.ts

@@ -1,13 +1,13 @@
 import { Effect, Schema } from "effect";
 import { commentsIn, refusalsIn, syntaxOf, unreadable, type Syntax } from "./comment-matchers.ts";
 
-export { SYNTAXES, syntaxOf, type Comment } from "./comment-matchers.ts";
+export { syntaxOf } from "./comment-matchers.ts";
 
 export class UnreadableCode extends Schema.TaggedError<UnreadableCode>()("UnreadableCode", {
   message: Schema.String,
 }) {}
 
-export function syntaxFor(path: string): Effect.Effect<Syntax, UnreadableCode> {
+function syntaxFor(path: string): Effect.Effect<Syntax, UnreadableCode> {
   const syntax = syntaxOf(path);
   return syntax ? Effect.succeed(syntax) : Effect.fail(new UnreadableCode({ message: unreadable(path) }));
 }

package/src/testing/test-report.ts

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 
-export type Outcome = "passed" | "failed" | "skipped" | "todo";
+type Outcome = "passed" | "failed" | "skipped" | "todo";
 
 export type TestResult = {
   readonly file: string;