@avi2dg/checks 0.24.2 → 0.26.0

package/docs/gates/checks-unused.md

@@ -0,0 +1,65 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-unused
+
+`checks-unused` is the gate that refuses a TypeScript file no entry point reaches, and a reader looks it up when a file seems dead but every other check passes.
+
+## What it checks
+
+It runs Knip with the repository's own configuration and names each `.ts` or `.tsx` 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 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 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.
+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
+
+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 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 file(s)
+```
+
+## 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-repetition](checks-repetition.md)

package/knip-base.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/knip@6.38.0/schema.json",
+  "include": ["files"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.24.2",
+  "version": "0.26.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -13,53 +13,54 @@
   "type": "module",
   "files": [
     "CHANGELOG.md",
-    "CONTRIBUTING.md",
     "docs/configs/",
     "docs/design.md",
     "docs/gates/",
     "bunfig.toml",
     "commitlint.config.js",
     "dependency-cruiser.config.js",
-    "scripts/lint-coverage.sh",
-    "scripts/main.ts",
-    "scripts/git.ts",
-    "scripts/gates.ts",
-    "scripts/lint.ts",
-    "scripts/changelog.ts",
-    "scripts/changelog-write.ts",
-    "scripts/release-notes.ts",
-    "scripts/release-report.ts",
-    "scripts/test-layout.ts",
-    "scripts/test.ts",
-    "scripts/test-skips.ts",
-    "scripts/swc.ts",
-    "scripts/test-report.ts",
-    "scripts/flake.ts",
-    "scripts/commit-identity.ts",
-    "scripts/mutation-compare.ts",
-    "scripts/subsumed-tests.ts",
-    "scripts/ci-wiring.ts",
-    "scripts/shell-command.ts",
-    "scripts/comment-matchers.ts",
-    "scripts/prose-matchers.ts",
-    "scripts/comments.ts",
-    "scripts/comment-gate.ts",
-    "scripts/suppressions-ratchet.ts",
-    "scripts/backtest.ts",
-    "scripts/range-gate.ts",
-    "scripts/repetition.ts",
-    "scripts/quarantine-clock.ts",
-    "scripts/docs.ts",
-    "scripts/vendor.ts",
-    "scripts/vendor-args.ts",
-    "scripts/doc-outline.ts",
-    "scripts/doc-rules.ts",
-    "scripts/doc-references.ts",
-    "scripts/doc-snapshot.ts",
-    "scripts/doc-templates.ts",
-    "templates/",
-    "presets/effect.oxlint.json",
-    "presets/effect.language-service.json",
+    "knip-base.json",
+    "src/quality/lint-coverage.sh",
+    "src/core/main.ts",
+    "src/core/git.ts",
+    "src/core/gates.ts",
+    "src/core/lint.ts",
+    "src/delivery/changelog.ts",
+    "src/delivery/changelog-write.ts",
+    "src/delivery/release-notes.ts",
+    "src/delivery/release-report.ts",
+    "src/testing/test-layout.ts",
+    "src/testing/test.ts",
+    "src/testing/test-skips.ts",
+    "src/core/swc.ts",
+    "src/testing/test-report.ts",
+    "src/testing/flake.ts",
+    "src/delivery/commit-identity.ts",
+    "src/testing/mutation-compare.ts",
+    "src/testing/subsumed-tests.ts",
+    "src/delivery/ci-wiring.ts",
+    "src/delivery/shell-command.ts",
+    "src/quality/comment-matchers.ts",
+    "src/docs/prose-matchers.ts",
+    "src/quality/comments.ts",
+    "src/quality/comment-gate.ts",
+    "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",
+    "src/dependencies/vendor-args.ts",
+    "src/docs/doc-outline.ts",
+    "src/docs/doc-rules.ts",
+    "src/docs/doc-references.ts",
+    "src/docs/doc-snapshot.ts",
+    "src/docs/doc-templates.ts",
+    "dist/templates/",
+    "src/quality/presets/effect.oxlint.json",
+    "src/quality/presets/effect.language-service.json",
     "oxlintrc.json",
     "stryker.preset.js",
     "tsconfig.effect.json",
@@ -67,77 +68,43 @@
     "dist/readability/index.js"
   ],
   "exports": {
-    "./bunfig.toml": "./bunfig.toml",
-    "./commitlint.config.js": "./commitlint.config.js",
     "./dependency-cruiser.config.js": "./dependency-cruiser.config.js",
-    "./scripts/lint-coverage.sh": "./scripts/lint-coverage.sh",
-    "./scripts/lint.ts": "./scripts/lint.ts",
-    "./scripts/changelog.ts": "./scripts/changelog.ts",
-    "./scripts/changelog-write.ts": "./scripts/changelog-write.ts",
-    "./scripts/release-notes.ts": "./scripts/release-notes.ts",
-    "./scripts/release-report.ts": "./scripts/release-report.ts",
-    "./scripts/test-layout.ts": "./scripts/test-layout.ts",
-    "./scripts/test.ts": "./scripts/test.ts",
-    "./scripts/test-skips.ts": "./scripts/test-skips.ts",
-    "./scripts/flake.ts": "./scripts/flake.ts",
-    "./scripts/commit-identity.ts": "./scripts/commit-identity.ts",
-    "./scripts/mutation-compare.ts": "./scripts/mutation-compare.ts",
-    "./scripts/subsumed-tests.ts": "./scripts/subsumed-tests.ts",
-    "./scripts/ci-wiring.ts": "./scripts/ci-wiring.ts",
-    "./scripts/comment-matchers.ts": "./scripts/comment-matchers.ts",
-    "./scripts/prose-matchers.ts": "./scripts/prose-matchers.ts",
-    "./scripts/comments.ts": "./scripts/comments.ts",
-    "./scripts/comment-gate.ts": "./scripts/comment-gate.ts",
-    "./scripts/suppressions-ratchet.ts": "./scripts/suppressions-ratchet.ts",
-    "./scripts/backtest.ts": "./scripts/backtest.ts",
-    "./scripts/repetition.ts": "./scripts/repetition.ts",
-    "./scripts/quarantine-clock.ts": "./scripts/quarantine-clock.ts",
-    "./scripts/docs.ts": "./scripts/docs.ts",
-    "./scripts/vendor.ts": "./scripts/vendor.ts",
-    "./templates/readme.md": "./templates/readme.md",
-    "./templates/changelog.md": "./templates/changelog.md",
-    "./templates/adr.md": "./templates/adr.md",
-    "./templates/agents.md": "./templates/agents.md",
-    "./templates/claude.md": "./templates/claude.md",
-    "./templates/tutorial.md": "./templates/tutorial.md",
-    "./templates/how-to.md": "./templates/how-to.md",
-    "./templates/reference.md": "./templates/reference.md",
-    "./templates/explanation.md": "./templates/explanation.md",
-    "./presets/effect.oxlint.json": "./presets/effect.oxlint.json",
-    "./presets/effect.language-service.json": "./presets/effect.language-service.json",
-    "./oxlintrc.json": "./oxlintrc.json",
+    "./knip-base.json": "./knip-base.json",
+    "./scripts/test-skips.ts": "./src/testing/test-skips.ts",
+    "./scripts/comment-matchers.ts": "./src/quality/comment-matchers.ts",
+    "./scripts/prose-matchers.ts": "./src/docs/prose-matchers.ts",
     "./stryker.preset.js": "./stryker.preset.js",
-    "./tsconfig.effect.json": "./tsconfig.effect.json",
-    "./dist/effect-channel/index.js": "./dist/effect-channel/index.js",
-    "./dist/readability/index.js": "./dist/readability/index.js"
+    "./templates/*": "./dist/templates/*",
+    "./tsconfig.effect.json": "./tsconfig.effect.json"
   },
   "bin": {
-    "checks-lint": "scripts/lint.ts",
-    "checks-changelog": "scripts/changelog-write.ts",
-    "checks-release-notes": "scripts/release-notes.ts",
-    "checks-release-report": "scripts/release-report.ts",
-    "checks-lint-coverage": "scripts/lint-coverage.sh",
-    "checks-test-layout": "scripts/test-layout.ts",
-    "checks-test": "scripts/test.ts",
-    "checks-flake": "scripts/flake.ts",
-    "checks-commit-identity": "scripts/commit-identity.ts",
-    "checks-mutation-compare": "scripts/mutation-compare.ts",
-    "checks-subsumed-tests": "scripts/subsumed-tests.ts",
-    "checks-ci-wiring": "scripts/ci-wiring.ts",
-    "checks-comment-gate": "scripts/comment-gate.ts",
-    "checks-suppressions-ratchet": "scripts/suppressions-ratchet.ts",
-    "checks-backtest": "scripts/backtest.ts",
-    "checks-repetition": "scripts/repetition.ts",
-    "checks-quarantine-clock": "scripts/quarantine-clock.ts",
-    "checks-docs": "scripts/docs.ts",
-    "checks-vendor": "scripts/vendor.ts"
+    "checks-lint": "src/core/lint.ts",
+    "checks-changelog": "src/delivery/changelog-write.ts",
+    "checks-release-notes": "src/delivery/release-notes.ts",
+    "checks-release-report": "src/delivery/release-report.ts",
+    "checks-lint-coverage": "src/quality/lint-coverage.sh",
+    "checks-test-layout": "src/testing/test-layout.ts",
+    "checks-test": "src/testing/test.ts",
+    "checks-flake": "src/testing/flake.ts",
+    "checks-commit-identity": "src/delivery/commit-identity.ts",
+    "checks-mutation-compare": "src/testing/mutation-compare.ts",
+    "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
+    "checks-ci-wiring": "src/delivery/ci-wiring.ts",
+    "checks-comment-gate": "src/quality/comment-gate.ts",
+    "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"
   },
   "scripts": {
-    "prepare": "bun scripts/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
-    "build": "bun build effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build readability/index.ts --outdir dist/readability --target node --format esm && bun scripts/doc-templates-write.ts && bun scripts/changelog-write.ts && bun scripts/doc-blocks-write.ts",
-    "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs .",
+    "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
+    "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "lint": "oxlint --type-aware && bun src/core/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
-    "test": "bun scripts/test.ts"
+    "test": "bun src/testing/test.ts"
   },
   "peerDependencies": {
     "@swc/core": "1.16.2",
@@ -153,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",
@@ -165,6 +131,7 @@
     "@commitlint/cli": "21.2.3",
     "@commitlint/config-conventional": "21.2.3",
     "@effect/platform-bun": "4.0.0-rc.115",
-    "@effect/platform-node-shared": "4.0.0-rc.115"
+    "@effect/platform-node-shared": "4.0.0-rc.115",
+    "knip": "6.38.0"
   }
 }

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/{scripts → src/complexity}/repetition.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { changedPaths, checkoutFiles, collect, git, pathsAt, rangeFromArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { changedPaths, checkoutFiles, collect, git, pathsAt, rangeFromArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 export type Fragment = {
   readonly file: string;

package/{scripts → src/complexity}/suppressions-ratchet.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { git, commitOf, parentOrEmptyTree, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { git, commitOf, parentOrEmptyTree, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 export const SUPPRESSIONS = "oxlint-suppressions.json";
 

package/src/complexity/unused.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env bun
+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 JUDGED = /\.tsx?$/;
+
+class UnusedError extends Schema.TaggedError<UnusedError>()("UnusedError", {
+  message: Schema.String,
+}) {}
+
+const decodeKnipReport = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      issues: Schema.Array(Schema.Struct({ files: Schema.optional(Schema.Array(Schema.Struct({ name: Schema.String }))) })),
+    }),
+  ),
+);
+
+export const filesOf = Effect.fn("filesOf")(function* (stdout: string) {
+  const { issues } = yield* decodeKnipReport(stdout).pipe(
+    Effect.mapError((cause) => new UnusedError({ 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 report({ tracked, files }: Scan): string {
+  if (files.length === 0) return `${NAME}: no unreferenced files among ${tracked} tracked .ts/.tsx file(s)`;
+  return [`${NAME}: ${files.length} unreferenced file(s):`, ...files.map((file) => `  ${file}`)].join("\n");
+}
+
+const unused = Effect.gen(function* () {
+  const { tracked, reported } = yield* scanTree(NAME, ["--files"]).pipe(
+    Effect.mapError((cause) => new UnusedError({ message: cause.message })),
+  );
+  if (reported.kind === "unconfigured") return false;
+  const files = yield* filesOf(reported.stdout);
+  yield* Console.log(report({ tracked, files }));
+  return files.length === 0;
+});
+
+if (import.meta.main) runMain(NAME, unused);