@avi2dg/checks 0.36.0 → 0.38.0

package/docs/gates/checks-exports.md

@@ -25,16 +25,16 @@ 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:
+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 base from "@avi2dg/checks/knip-base.json";
+import { defineConfig } from "@avi2dg/checks/knip";
 
-export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
+export default defineConfig({ entry: ["src/index.ts"] });
 ```
 
-The base in `knip-base.json` reports only unreferenced files.
+The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts` and `dependency-cruiser.config.ts` to the entries.
 The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
 
 ## Arguments

package/docs/gates/checks-imports.md

@@ -0,0 +1,64 @@
+---
+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 when the repository tracks a `.ts` or `.tsx` file, so a repository with no config of its own still has its imports judged.
+
+## Related topics
+
+- [The dependency rules](../configs/dependency-rules.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-lint.md

@@ -47,7 +47,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 14 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 16 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

package/docs/gates/checks-mutation-baseline.md

@@ -0,0 +1,99 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-mutation-baseline
+
+`checks-mutation-baseline` restores the newest mutation baseline that `main` published, and on a self-hosted runner it keeps each baseline it downloads so the next job copies it instead.
+
+## What it checks
+
+It reads the successful runs of `mutation.yml` on `main`.
+Without `--full` it takes the newest of the 20 newest of those runs that a pull request did not start.
+It restores that run's `mutation-baseline` artifact, and takes the run whether or not it holds one.
+It tries no older run, so a newest run without the artifact restores nothing.
+An artifact without `stryker-incremental.json` counts as no baseline.
+It copies `stryker-incremental.json` to the first destination, and `mutation/mutation.json` to the second destination when the artifact holds it.
+
+With `--full` it lists up to 50 `schedule` runs and up to 50 `workflow_dispatch` runs apart, so pushes cannot crowd the full runs out of one list.
+It tries those runs newest first, and restores the first `mutation-baseline-full` artifact that has not expired, downloads and holds the report.
+It tries no run after that one.
+It takes the report from `mutation.json` at the artifact's root, or else from `mutation/mutation.json`, and copies it to the destination.
+
+It creates the directories each destination needs.
+
+## What it reads
+
+It reads the runs and their artifacts through `gh`, which needs a token that reads the repository's Actions, such as `GH_TOKEN: ${{ github.token }}` with `actions: read`.
+The `mutation-baseline` artifact holds `stryker-incremental.json` and `mutation/mutation.json`, which an upload of `reports/stryker-incremental.json` and `reports/mutation/mutation.json` writes.
+The `mutation-baseline-full` artifact holds `mutation.json` at its root, which an upload of `reports/mutation/mutation.json` alone writes.
+It reads `RUNNER_ENVIRONMENT` and `HOME` to place the runner cache.
+
+## The runner cache
+
+The cache sits under `$HOME/.cache/avi2dg-checks/mutation-baseline/`.
+It lies outside the job's workspace and `RUNNER_TEMP`, so it outlives the job on a self-hosted runner.
+Each entry sits at `<repository id>/<artifact name>/<artifact id>/`.
+GitHub gives every upload a new artifact id, so an entry under a listed id is never stale.
+On a hit the bin copies the files from the entry and downloads nothing.
+On a miss it downloads into a staging directory beside the entry and renames it into place.
+A job sharing the runner sees an entry whole or not at all.
+If the entry already exists, because another job placed it or it lost a file, the bin keeps it and restores from its own download.
+After each download it keeps the 2 highest artifact ids for that repository and artifact name, plus the entry it restores from.
+It removes the rest.
+A 100 MB baseline zip can unpack to about 500 MB, so a repository restoring both artifacts holds about 2 GB.
+
+When `RUNNER_ENVIRONMENT` is `github-hosted`, it downloads into a temporary directory and writes no cache, since a hosted runner starts every job on a fresh machine.
+When `HOME` is unset it works the same way, and prints to stderr that the runner cache is disabled.
+
+## Arguments
+
+```sh
+checks-mutation-baseline <incremental-dest> [mutation-json-dest]
+checks-mutation-baseline --full <mutation-json-dest>
+```
+
+`--full` restores only the report of a run that started with no state.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | it restored a baseline, or found none to restore |
+| 2 | the arguments do not parse, `gh` cannot list the runs, the cache cannot be written, or another job removed the entry before it was copied |
+
+A failed artifact lookup or download prints the `gh` error and moves on, as a missing artifact does.
+
+## Sample output
+
+```
+mutation-baseline: restored it from the runner's cache, mutation-baseline artifact 11666313211 from run 38042411822
+```
+
+A miss prints `downloaded it into the runner's cache` instead, and a hosted runner prints `downloaded it`.
+
+## When it runs
+
+Only a CI step the repository writes runs it.
+A baseline job restores the state the previous `main` run left before an incremental Stryker run:
+
+```yaml
+- name: Restore previous baseline state
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: bunx checks-mutation-baseline reports/stryker-incremental.json
+```
+
+A pull request's scope step restores the full report with `--full`:
+
+```yaml
+- name: Select mutation scope
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+```
+
+## Related topics
+
+- [checks-mutation](checks-mutation.md)
+- [checks-mutation-compare](checks-mutation-compare.md)

package/docs/gates/checks-mutation-compare.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-mutation-compare
 
-`checks-mutation-compare` is the gate that fails a pull request when any mutant regresses, rather than judging an absolute score.
+`checks-mutation-compare` compares the mutants of two reports and lists each one that regresses, rather than judging an absolute score.
 
 ## What it checks
 
@@ -68,7 +68,10 @@ mutation-compare: REGRESSION (1 mutant(s))
 ## When it runs
 
 Only a CI step the repository writes runs it.
-A repository runs it with `--advisory` for its first month, then drops the flag so it blocks.
+A repository runs it with `--advisory`, so the comparison stays advisory and never blocks a pull request.
+Its lines land only in the CI log.
+A repository that wants a reviewer to answer each regression line puts the lines in front of that reviewer with its own CI step.
+That step can post them as a pull request comment.
 A full sweep runs in CI and never on a laptop.
 Start a baseline with `gh workflow run mutation` and keep its report as an artifact.
 The shared preset refuses a full `stryker run` outside CI and names that workflow command instead, as [checks-mutation](checks-mutation.md) says.

package/docs/gates/checks-mutation.md

@@ -75,9 +75,9 @@ An `--incremental` run with no report stops before instrumenting with the missin
 ## When it runs
 
 A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
-A repository that picks a pull request scope from a baseline also runs that workflow on a nightly schedule.
+A repository that picks a pull request scope from a baseline starts that workflow weekly with `gh workflow run mutation`, because a GitHub schedule can start hours late.
 Run scoped checks locally during development.
-A scheduled run costs a full Stryker run.
+Each baseline costs a full Stryker run.
 
 ## Running it in CI
 

package/docs/gates/checks-unused.md

@@ -18,15 +18,15 @@ It fails when the repository holds no Knip configuration, since Knip's default e
 
 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:
+The repository writes `knip.config.ts` with the kit's builder, which requires `entry`, the files nothing imports:
 
 ```ts
-import base from "@avi2dg/checks/knip-base.json";
+import { defineConfig } from "@avi2dg/checks/knip";
 
-export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
+export default defineConfig({ entry: ["src/index.ts"] });
 ```
 
-The base in `knip-base.json` reports only unreferenced files.
+The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts` and `dependency-cruiser.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.
 

package/oxlintrc.json

@@ -1,19 +1,48 @@
 {
-  "plugins": ["typescript", "oxc", "eslint", "import"],
-  "jsPlugins": ["./dist/effect-channel/index.js", "./dist/readability/index.js", "./dist/data-shape/index.js"],
-  "categories": { "correctness": "error", "suspicious": "error" },
+  "plugins": [
+    "typescript",
+    "oxc",
+    "eslint",
+    "import"
+  ],
+  "jsPlugins": [
+    "./dist/effect-channel/index.js",
+    "./dist/readability/index.js",
+    "./dist/data-shape/index.js"
+  ],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "error"
+  },
   "rules": {
     "effect-channel/no-error-channel-escape": "error",
     "typescript/no-explicit-any": "error",
-    "typescript/ban-ts-comment": ["error", { "ts-expect-error": true }],
+    "typescript/ban-ts-comment": [
+      "error",
+      {
+        "ts-expect-error": true
+      }
+    ],
     "typescript/no-inferrable-types": "error",
     "typescript/explicit-module-boundary-types": "error",
     "typescript/switch-exhaustiveness-check": "error",
     "typescript/prefer-readonly": "error",
-    "typescript/no-unnecessary-condition": ["error", { "allowConstantLoopConditions": true }],
+    "typescript/no-unnecessary-condition": [
+      "error",
+      {
+        "allowConstantLoopConditions": true
+      }
+    ],
     "typescript/no-unnecessary-type-parameters": "error",
     "typescript/use-unknown-in-catch-callback-variable": "error",
-    "eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "ignoreRestSiblings": true }],
+    "eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_",
+        "ignoreRestSiblings": true
+      }
+    ],
     "typescript/no-unsafe-type-assertion": "error",
     "typescript/no-non-null-assertion": "error",
     "typescript/no-deprecated": "error",
@@ -21,14 +50,22 @@
   },
   "overrides": [
     {
-      "files": ["**/*.ts", "**/*.tsx"],
+      "files": [
+        "**/*.ts",
+        "**/*.tsx"
+      ],
       "rules": {
         "data-shape/readonly-collection-param": "error"
       }
     },
     {
-      "files": ["**/*.ts", "**/*.tsx"],
-      "excludeFiles": ["tests/**"],
+      "files": [
+        "**/*.ts",
+        "**/*.tsx"
+      ],
+      "excludeFiles": [
+        "tests/**"
+      ],
       "rules": {
         "data-shape/schema-twin": "error",
         "typescript/no-unsafe-assignment": "error",
@@ -39,7 +76,9 @@
       }
     },
     {
-      "files": ["**/*.astro"],
+      "files": [
+        "**/*.astro"
+      ],
       "rules": {
         "readability/thin-astro": "error",
         "import/no-unassigned-import": "off"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -44,6 +44,7 @@
     "src/testing/mutation-scope.js",
     "src/testing/mutation-guard-plugin.js",
     "src/testing/mutation-compare.ts",
+    "src/testing/mutation-baseline.ts",
     "src/testing/subsumed-tests.ts",
     "src/delivery/ci-wiring.ts",
     "src/delivery/shell-command.ts",
@@ -80,15 +81,21 @@
     "src/docs/doc-templates.ts",
     "src/docs/doc-names.ts",
     "dist/templates/",
-    "src/quality/presets/effect.oxlint.json",
     "src/quality/presets/effect.language-service.json",
+    "src/quality/presets/oxlint.ts",
+    "src/quality/presets/dependency-cruiser.ts",
+    "src/quality/effect-scope.ts",
+    "src/quality/jsonc-patch.ts",
+    "src/dependencies/imports.ts",
+    "src/dependencies/kit-defaults.ts",
     "oxlintrc.json",
     "stryker.preset.js",
     "tsconfig.effect.json",
     "ts-reset.d.ts",
     "dist/effect-channel/index.js",
     "dist/readability/index.js",
-    "dist/data-shape/index.js"
+    "dist/data-shape/index.js",
+    "dist/presets/"
   ],
   "exports": {
     "./dependency-cruiser.config.js": "./dependency-cruiser.config.js",
@@ -99,7 +106,19 @@
     "./stryker.preset.js": "./stryker.preset.js",
     "./templates/*": "./dist/templates/*",
     "./tsconfig.effect.json": "./tsconfig.effect.json",
-    "./browser-hooks.ts": "./src/quality/browser/hooks.ts"
+    "./browser-hooks.ts": "./src/quality/browser/hooks.ts",
+    "./oxlint": {
+      "types": "./dist/presets/oxlint.d.ts",
+      "default": "./dist/presets/oxlint.js"
+    },
+    "./knip": {
+      "types": "./dist/presets/knip.d.ts",
+      "default": "./dist/presets/knip.js"
+    },
+    "./dependency-cruiser": {
+      "types": "./dist/presets/dependency-cruiser.d.ts",
+      "default": "./dist/presets/dependency-cruiser.js"
+    }
   },
   "bin": {
     "checks-lint": "src/core/lint.ts",
@@ -115,6 +134,7 @@
     "checks-commit-identity": "src/delivery/commit-identity.ts",
     "checks-mutation": "src/testing/mutation.ts",
     "checks-mutation-compare": "src/testing/mutation-compare.ts",
+    "checks-mutation-baseline": "src/testing/mutation-baseline.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",
@@ -128,12 +148,14 @@
     "checks-advisories": "src/dependencies/advisories.ts",
     "checks-secrets": "src/delivery/secrets.ts",
     "checks-frontend-syntax": "src/quality/frontend-syntax.ts",
-    "checks-browser": "src/quality/browser/browser.ts"
+    "checks-browser": "src/quality/browser/browser.ts",
+    "checks-imports": "src/dependencies/imports.ts",
+    "checks-effect-scope": "src/quality/effect-scope.ts"
   },
   "scripts": {
     "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 build src/quality/data-shape/index.ts --outdir dist/data-shape --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 .",
+    "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 build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun build src/quality/presets/oxlint.ts src/quality/presets/knip.ts src/quality/presets/dependency-cruiser.ts --outdir dist/presets --target node --format esm && tsc -p tsconfig.presets.json && bun scripts/configs-write.ts && bun src/quality/effect-scope.ts && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "lint": "oxlint && bun src/core/lint.ts",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun src/testing/test.ts",
     "mutate": "bunx stryker run",

package/src/complexity/exports.ts

@@ -130,7 +130,7 @@ export function report(head: Baseline, { unlisted, added, stale }: Drift): strin
 
 const scan = scanTree(NAME, INCLUDED, TYPESCRIPT_SOURCE).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.
+// 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);

package/src/complexity/knip.ts

@@ -63,7 +63,7 @@ export const scanTree = Effect.fn("scanTree")(function* (name: string, args: rea
   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 one extending the kit's knip-base.json`);
+    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

@@ -36,6 +36,8 @@ export const LINTED_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx", "*.a
 
 const BUN_LOCKFILE: TrackedContent = { pathspecs: ["bun.lock"], content: "a bun lockfile" };
 
+const OXLINT_CONFIG: TrackedContent = { pathspecs: ["oxlint.config.ts"], content: "an oxlint.config.ts" };
+
 const FRONTEND_SYNTAX_DECLARATION: TrackedContent = { pathspecs: ["frontend-syntax.json"], content: "a frontend syntax declaration" };
 
 export const KIT_GATES = [
@@ -43,6 +45,7 @@ export const KIT_GATES = [
   { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-commit-identity", vector: "delivery", file: "commit-identity.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-effect-scope", vector: "quality", file: "effect-scope.ts", reads: "tree", args: ["--check"], appliesTo: OXLINT_CONFIG },
   { bin: "checks-frontend-syntax", vector: "quality", file: "frontend-syntax.ts", reads: "tree", appliesTo: FRONTEND_SYNTAX_DECLARATION },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
@@ -52,5 +55,6 @@ export const KIT_GATES = [
   { 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-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", file: "advisories.ts", reads: "range", appliesTo: BUN_LOCKFILE },
 ] as const satisfies readonly KitGate[];

package/src/dependencies/imports.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { collect, git } from "../core/git.ts";
+import { runMain, Usage } from "../core/main.ts";
+
+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 NAME = "imports";
+const USAGE = "usage: imports.ts";
+const KIT_DEFAULTS = "kit-defaults.ts";
+
+class ImportsError extends Schema.TaggedError<ImportsError>()("ImportsError", {
+  message: Schema.String,
+}) {}
+
+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 decodeCruise = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      summary: Schema.Struct({ violations: Schema.Array(Violation), error: Schema.Int, totalCruised: Schema.Int }),
+    }),
+  ),
+);
+
+export function describeViolation({ from, to, rule }: Violation): string {
+  return from === to ? `  ${rule.severity} ${rule.name}: ${from}` : `  ${rule.severity} ${rule.name}: ${from} → ${to}`;
+}
+
+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, 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 ImportsError({ 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 imports = Effect.gen(function* () {
+  if (process.argv.length > 2) return yield* new Usage({ message: USAGE });
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const files = yield* trackedInTree(root);
+  if (files.length === 0) return yield* new ImportsError({ 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 ImportsError({ message: `cannot run dependency-cruiser: ${cause.message}` })),
+  );
+  const { summary } = yield* decodeCruise(run.stdout).pipe(
+    Effect.mapError(() => new ImportsError({ 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(`${NAME}: ${cruised}, no violation`);
+    return true;
+  }
+  yield* Console.error([`${NAME}: ${summary.violations.length} violation(s) in ${cruised}`, ...summary.violations.map(describeViolation)].join("\n"));
+  return summary.error === 0;
+});
+
+if (import.meta.main) runMain(NAME, imports);

package/src/dependencies/kit-defaults.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from "../quality/presets/dependency-cruiser.ts";
+
+export default defineConfig();