@avi2dg/checks 0.36.0 → 0.37.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-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.37.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -80,15 +80,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 +105,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",
@@ -128,12 +146,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();

package/src/quality/effect-scope.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { git } from "../core/git.ts";
+import { runMain, Usage } from "../core/main.ts";
+import { hasMember, type Step, withMember, withoutMember } from "./jsonc-patch.ts";
+import { effectRules } from "./presets/oxlint.ts";
+import severities from "./presets/effect.language-service.json" with { type: "json" };
+import kitTsconfig from "../../tsconfig.effect.json" with { type: "json" };
+
+export const OXLINT_CONFIG = "oxlint.config.ts";
+export const TSCONFIG = "tsconfig.json";
+export const LANGUAGE_SERVICE = "@effect/language-service";
+
+const NAME = "effect-scope";
+const CHECK = "--check";
+const USAGE = `usage: effect-scope.ts [${CHECK}]`;
+
+class EffectScopeError extends Schema.TaggedError<EffectScopeError>()("EffectScopeError", {
+  message: Schema.String,
+}) {}
+
+const JsonObject = Schema.Record(Schema.String, Schema.Unknown);
+
+type JsonObject = typeof JsonObject.Type;
+
+const Override = Schema.Struct({
+  files: Schema.Array(Schema.String),
+  excludeFiles: Schema.optionalKey(Schema.Array(Schema.String)),
+  rules: Schema.optionalKey(JsonObject),
+});
+
+const OxlintModule = Schema.Struct({ default: Schema.Struct({ overrides: Schema.optionalKey(Schema.Array(Override)) }) });
+
+const decodeOxlintModule = Schema.decodeUnknownEffect(OxlintModule);
+const decodeObject = Schema.decodeUnknownEffect(JsonObject);
+const decodePlugins = Schema.decodeUnknownEffect(Schema.Array(JsonObject));
+
+export type ServiceOverride = {
+  readonly include: readonly string[];
+  readonly exclude?: readonly string[];
+  readonly options: typeof severities;
+};
+
+const EFFECT_RULES = JSON.stringify(effectRules([]).rules);
+
+const SERVICE: readonly [Step, ...Step[]] = ["compilerOptions", "plugins", { name: LANGUAGE_SERVICE }];
+
+const SERVICE_OVERRIDES: readonly [Step, ...Step[]] = [...SERVICE, "overrides"];
+
+const SERVICE_SEVERITY: readonly [Step, ...Step[]] = [...SERVICE, "diagnosticSeverity"];
+
+const KIT_SEVERITY = kitTsconfig.compilerOptions.plugins.find(({ name }) => name === LANGUAGE_SERVICE)?.diagnosticSeverity ?? {};
+
+export function serviceOverrides(overrides: readonly (typeof Override.Type)[]): readonly ServiceOverride[] {
+  return overrides
+    .filter(({ rules }) => JSON.stringify(rules) === EFFECT_RULES)
+    .map(({ files, excludeFiles = [] }) => (excludeFiles.length === 0 ? { include: files, options: severities } : { include: files, exclude: excludeFiles, options: severities }));
+}
+
+export function withServiceOverrides(tsconfig: string, overrides: readonly ServiceOverride[]): string {
+  if (!hasMember(tsconfig, SERVICE)) return overrides.length === 0 ? tsconfig : withMember(tsconfig, SERVICE, { diagnosticSeverity: KIT_SEVERITY, overrides });
+  const paths = overrides.length === 0 ? withoutMember(tsconfig, SERVICE_OVERRIDES) : withMember(tsconfig, SERVICE_OVERRIDES, overrides);
+  return Object.entries(KIT_SEVERITY).reduce((text, [key, severity]) => withMember(text, [...SERVICE_SEVERITY, key], severity), paths);
+}
+
+const refuse = (message: string) => () => new EffectScopeError({ message });
+
+const readScope = Effect.fn("readScope")(function* (file: string) {
+  const path = yield* Path.Path;
+  const url = yield* path.toFileUrl(file).pipe(Effect.mapError(refuse(`cannot address ${file}`)));
+  const loaded = yield* Effect.tryPromise({
+    try: (): Promise<unknown> => import(url.href),
+    catch: (cause) => new EffectScopeError({ message: `cannot load ${OXLINT_CONFIG}: ${String(cause)}` }),
+  });
+  const { default: config } = yield* decodeOxlintModule(loaded).pipe(Effect.mapError(refuse(`${OXLINT_CONFIG} exports no oxlint config as its default`)));
+  return serviceOverrides(config.overrides ?? []);
+});
+
+const placeOfService = Effect.fn("placeOfService")(function* (tsconfig: JsonObject) {
+  const compilerOptions = yield* decodeObject("compilerOptions" in tsconfig ? tsconfig["compilerOptions"] : {}).pipe(Effect.mapError(refuse(`${TSCONFIG} holds compilerOptions that is not an object`)));
+  const plugins = yield* decodePlugins("plugins" in compilerOptions ? compilerOptions["plugins"] : []).pipe(Effect.mapError(refuse(`${TSCONFIG} holds compilerOptions.plugins that is not a list of objects`)));
+  const service = plugins.find(({ name }) => name === LANGUAGE_SERVICE) ?? {};
+  yield* decodeObject("diagnosticSeverity" in service ? service["diagnosticSeverity"] : {}).pipe(Effect.mapError(refuse(`${TSCONFIG} holds a ${LANGUAGE_SERVICE} diagnosticSeverity that is not an object`)));
+});
+
+const effectScope = Effect.gen(function* () {
+  const args = process.argv.slice(2);
+  if (args.length > 1 || (args.length === 1 && args[0] !== CHECK)) return yield* new Usage({ message: USAGE });
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const tsconfigFile = path.join(root, TSCONFIG);
+  if (!(yield* fs.exists(tsconfigFile))) {
+    yield* Console.log(`${NAME}: no ${TSCONFIG}, so no language service holds the Effect paths`);
+    return true;
+  }
+  const overrides = yield* readScope(path.join(root, OXLINT_CONFIG));
+  const text = yield* fs.readFileString(tsconfigFile);
+  const unparsed = refuse(`${TSCONFIG} does not parse as a JSONC object`);
+  const tsconfig = yield* Effect.try({ try: () => Bun.JSONC.parse(text), catch: unparsed }).pipe(Effect.flatMap(decodeObject), Effect.mapError(unparsed));
+  yield* placeOfService(tsconfig);
+  const written = withServiceOverrides(text, overrides);
+  if (written === text) {
+    yield* Console.log(`${NAME}: ${TSCONFIG} holds the Effect paths of ${OXLINT_CONFIG} and the kit's severities`);
+    return true;
+  }
+  if (args[0] === CHECK) {
+    yield* Console.error(`${NAME}: the ${LANGUAGE_SERVICE} entry in ${TSCONFIG} differs from the Effect paths of ${OXLINT_CONFIG} or the kit's severities; run checks-effect-scope to rewrite them`);
+    return false;
+  }
+  yield* fs.writeFileString(tsconfigFile, written);
+  yield* Console.log(`${NAME}: wrote the Effect paths of ${OXLINT_CONFIG} and the kit's severities to ${TSCONFIG}`);
+  return true;
+});
+
+if (import.meta.main) runMain(NAME, effectScope);