@avi2dg/checks 0.24.2 → 0.26.0

package/src/core/gates.ts

@@ -0,0 +1,46 @@
+export type Program = {
+  readonly bin: string;
+  readonly script: string;
+};
+
+type TrackedContent = {
+  readonly pathspecs: readonly string[];
+  readonly content: string;
+};
+
+export const EVERY_REPOSITORY = "every repository";
+
+export const VECTORS = ["complexity", "quality", "testing", "docs", "delivery", "dependencies"] as const;
+
+type Vector = (typeof VECTORS)[number];
+
+export type KitGate = {
+  readonly bin: string;
+  readonly vector: Vector;
+  readonly file: string;
+  readonly reads: "tree" | "range";
+  readonly args?: readonly string[];
+  readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
+};
+
+export const ENTRY_POINT: Program = { bin: "checks-lint", script: "core/lint.ts" };
+
+export const TEST_ENTRY_POINT: Program = { bin: "checks-test", script: "testing/test.ts" };
+
+export const DEFAULT_BRANCH = "main";
+
+const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
+
+export const KIT_GATES = [
+  { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { 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-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 },
+  { 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/{scripts → src/core}/lint.ts

@@ -151,8 +151,8 @@ function outcomeOf(exitCode: number): Outcome {
 
 const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-  const script = (yield* Path.Path).join(import.meta.dir, gate.script);
-  const program = gate.script.endsWith(".sh") ? "sh" : process.execPath;
+  const script = (yield* Path.Path).join(import.meta.dir, "..", gate.vector, gate.file);
+  const program = gate.file.endsWith(".sh") ? "sh" : process.execPath;
   const args = gate.reads === "range" ? [script, ...range.refs] : [script, ...(gate.args ?? [])];
   const exitCode = yield* spawner
     .exitCode(ChildProcess.make(program, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit" }))

package/{scripts → 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/{scripts → src/delivery}/changelog-write.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, DateTime, Effect, FileSystem, Path, Schema } from "effect";
 import { cuts, hasEntries, namesPullRequest, releaseDates, renderChangelog, type Bump, type Cut, type Release } from "./changelog.ts";
-import { git } from "./git.ts";
-import { runMain } from "./main.ts";
+import { git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 const NAME = "checks-changelog";
 const CHANGELOG = "CHANGELOG.md";

package/{scripts → src/delivery}/changelog.ts

@@ -1,6 +1,6 @@
-import { firstText, parseOutline, VERSION } from "./doc-outline.ts";
-import { RELEASED } from "./doc-rules.ts";
-import { CHANGE_GROUPS, type ChangeGroup } from "./doc-templates.ts";
+import { firstText, parseOutline, VERSION } from "../docs/doc-outline.ts";
+import { RELEASED } from "../docs/doc-rules.ts";
+import { CHANGE_GROUPS, type ChangeGroup } from "../docs/doc-templates.ts";
 
 export type Bump = {
   readonly sha: string;

package/{scripts → src/delivery}/ci-wiring.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { defaultBranch, git } from "./git.ts";
-import { runMain } from "./main.ts";
-import { ENTRY_POINT, KIT_GATES, type KitGate } from "./gates.ts";
+import { defaultBranch, git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
 import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
 
 export type { Command };

package/{scripts → src/delivery}/commit-identity.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { git, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { git, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 type Identity = { readonly name: string; readonly email: string };
 

package/{scripts → src/delivery}/release-notes.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Effect, FileSystem, Schema } from "effect";
-import { runMain, Usage } from "./main.ts";
+import { runMain, Usage } from "../core/main.ts";
 
 export class ReleaseSectionUnavailable extends Schema.TaggedError<ReleaseSectionUnavailable>()("ReleaseSectionUnavailable", {
   message: Schema.String,

package/{scripts → src/delivery}/release-report.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
 import { groupOf } from "./changelog.ts";
-import { git } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
+import { git } from "../core/git.ts";
+import { runMain, Usage } from "../core/main.ts";
 
 export class ReleaseReportUnreadable extends Schema.TaggedError<ReleaseReportUnreadable>()("ReleaseReportUnreadable", {
   message: Schema.String,

package/{scripts → src/dependencies}/vendor-args.ts

@@ -1,5 +1,5 @@
 import { Effect, Schema } from "effect";
-import { Usage } from "./main.ts";
+import { Usage } from "../core/main.ts";
 
 export const NAME = "checks-vendor";
 export const OPENER = "--library";

package/{scripts → src/dependencies}/vendor.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Option, Path, Schema } from "effect";
-import { git } from "./git.ts";
-import { runMain } from "./main.ts";
+import { git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 import { librariesFrom, NAME, OPENER, type Library } from "./vendor-args.ts";
 
 const CACHE_HOME = ".cache/avi2dg-checks";

package/{scripts → 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/{scripts → src/docs}/doc-snapshot.ts

@@ -1,8 +1,8 @@
 import { Effect, FileSystem, Path, Schema } from "effect";
 import { anchoredTargets, anchorsOf, PACKAGE_MANIFEST, packagesOf, snapshotOf, type Unresolved } from "./doc-references.ts";
-import { git, pathsAt } from "./git.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/{scripts → 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/{scripts → src/docs}/docs.ts

@@ -3,8 +3,8 @@ import { Console, Effect } from "effect";
 import { rootsOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, speaksToConsumers, type Placement } from "./doc-rules.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
-import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 import { isLivingDoc, proseFindings, readerOf } from "./prose-matchers.ts";
 
 type Finding = {

package/{scripts → src/quality}/comment-gate.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
 import { refused, syntaxOf } from "./comments.ts";
-import { changedLines, git, parentOrEmptyTree, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { changedLines, git, parentOrEmptyTree, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 export type GateResult = {
   readonly files: number;

package/{scripts → src/quality}/comment-matchers.ts

@@ -88,7 +88,7 @@ export function syntaxOf(path: string): Syntax | undefined {
 }
 
 export function unreadable(path: string): string {
-  return `${path} is code the comment checks cannot read: add a comment syntax for .${extensionOf(path)} to scripts/comment-matchers.ts`;
+  return `${path} is code the comment checks cannot read: add a comment syntax for .${extensionOf(path)} to src/quality/comment-matchers.ts`;
 }
 
 const WORD = /[\w$]/;

package/{scripts → 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/{scripts → src/testing}/flake.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Option, Path, Random, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { runMain, Usage } from "./main.ts";
+import { runMain, Usage } from "../core/main.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
 
 export type Run = {

package/{scripts → src/testing}/mutation-compare.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Schema } from "effect";
-import { runMain, Usage } from "./main.ts";
+import { runMain, Usage } from "../core/main.ts";
 
 export type Location = {
   readonly start: { readonly line: number; readonly column: number };

package/{scripts → src/testing}/quarantine-clock.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { commitOf, git, isShallowBoundary, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { commitOf, git, isShallowBoundary, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 import { TEST_FILE } from "./test-layout.ts";
 
 export const QUARANTINE = "tests/quarantine/";

package/{scripts → src/testing}/subsumed-tests.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem } from "effect";
-import { runMain, Usage } from "./main.ts";
+import { runMain, Usage } from "../core/main.ts";
 import { type KillRun, parseKillRun, ReportError } from "./mutation-compare.ts";
 
 export type KillSets = ReadonlyMap<string, ReadonlySet<string>>;
@@ -179,7 +179,7 @@ export const bailWarning = (source: string, run: KillRun): Effect.Effect<string
       }),
     );
   if (run.bail === "unrecorded") return Effect.succeed(`${source} records no config, so nothing shows whether bail was off: build it with \`bunx stryker run --disableBail\``);
-  return Effect.succeed(undefined);
+  return Effect.undefined;
 };
 
 export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<Options, Usage> {

package/{scripts → src/testing}/test-layout.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { git } from "./git.ts";
-import { runMain } from "./main.ts";
-import { ENTRY_POINT, TEST_ENTRY_POINT } from "./gates.ts";
-import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "./swc.ts";
+import { git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+import { ENTRY_POINT, TEST_ENTRY_POINT } from "../core/gates.ts";
+import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "../core/swc.ts";
 
 export type Violation = {
   readonly file: string;
@@ -12,12 +12,20 @@ export type Violation = {
 };
 
 const TESTS = "tests/";
+const UNIT = "tests/unit/";
 const E2E = "tests/e2e/";
+const QUARANTINED = "tests/quarantine/";
 const HELPER_DIRS = ["tests/lib/", "tests/fixtures/"] as const;
 const DATA_DIR = "tests/fixtures/";
+const TEST_TIERS = ["live", "pixel"] as const;
+const SPAWNING_LEVELS = ["e2e", ...TEST_TIERS] as const;
+const LEVELS = ["unit", ...SPAWNING_LEVELS] as const;
+const LEVEL_DIR = new RegExp(`^tests/(?:quarantine/)?(?:${LEVELS.join("|")})/`);
+const QUARANTINE_BELOW_LEVEL = new RegExp(`^tests/(${LEVELS.join("|")})/((?:[^/]+/)*?)quarantine/(.+)$`);
+const LEVEL_NAMES = new Intl.ListFormat("en", { type: "disjunction" }).format(LEVELS);
 
 export const TEST_FILE = /(?:[.](?:test|spec)|_test)[.](tsx?)$/;
-const TARGET_FILE = /^tests\/(?:[^/]+\/)*[^/]+[.]test[.]tsx?$/;
+const TARGET_FILE = new RegExp(`${LEVEL_DIR.source}(?:[^/]+/)*[^/]+[.]test[.]tsx?$`);
 const TYPESCRIPT = /[.]tsx?$/;
 
 const BANNED_MODULES: readonly string[] = [
@@ -44,16 +52,15 @@ const QUARANTINE = "**/tests/quarantine/**";
 const LIVE_TESTS = "**/tests/live/**";
 const PIXEL_TESTS = "**/tests/pixel/**";
 const VENDORED = "repos/**";
-const TEST_TIERS = ["live", "pixel"] as const;
-const OUT_OF_PROCESS: readonly string[] = [E2E, ...TEST_TIERS.map((tier) => `${TESTS}${tier}/`)];
+const OUT_OF_PROCESS: readonly string[] = SPAWNING_LEVELS.flatMap((level) => [`${TESTS}${level}/`, `${QUARANTINED}${level}/`]);
 const ACCEPTED_IGNORES: readonly (readonly string[])[] = [
   [QUARANTINE, LIVE_TESTS, PIXEL_TESTS, VENDORED],
   [QUARANTINE, LIVE_TESTS, PIXEL_TESTS],
 ];
-export const LAYOUT_CHECK_MARK = "scripts/test-layout.ts";
+export const LAYOUT_CHECK_MARK = "src/testing/test-layout.ts";
 export const LAYOUT_CHECK_BIN = "checks-test-layout";
-const OWN_ENTRY_POINT = `scripts/${ENTRY_POINT.script}`;
-const TEST_SCRIPTS: readonly string[] = [TEST_ENTRY_POINT.bin, `bun scripts/${TEST_ENTRY_POINT.script}`];
+const OWN_ENTRY_POINT = `src/${ENTRY_POINT.script}`;
+const TEST_SCRIPTS: readonly string[] = [TEST_ENTRY_POINT.bin, `bun src/${TEST_ENTRY_POINT.script}`];
 
 export class LayoutError extends Schema.TaggedError<LayoutError>()("LayoutError", {
   message: Schema.String,
@@ -75,7 +82,24 @@ function targetFor(file: string): string {
     .replace(/(?:^|\/)__tests__\//, "/")
     .replace(/^\/+/, "");
   const renamed = withoutLeadingDirs.replace(TEST_FILE, ".test.$1");
-  return renamed.startsWith(TESTS) ? renamed : `${TESTS}${renamed}`;
+  if (LEVEL_DIR.test(renamed)) return renamed;
+  if (renamed.startsWith(QUARANTINED)) return `${QUARANTINED}unit/${renamed.slice(QUARANTINED.length)}`;
+  return `${UNIT}${renamed.startsWith(TESTS) ? renamed.slice(TESTS.length) : renamed}`;
+}
+
+function quarantineTargetFor(file: string): string | undefined {
+  const below = QUARANTINE_BELOW_LEVEL.exec(file);
+  if (below !== null) return `${QUARANTINED}${below[1]}/${below[2]}${below[3]}`.replace(TEST_FILE, ".test.$1");
+  if (file.startsWith(QUARANTINED) && !LEVEL_DIR.test(file)) return targetFor(file);
+  return undefined;
+}
+
+function outOfProcessTargetFor(file: string): string {
+  if (file.startsWith(QUARANTINED)) {
+    const rest = file.slice(QUARANTINED.length);
+    return `${QUARANTINED}e2e/${rest.startsWith("unit/") ? rest.slice("unit/".length) : rest}`;
+  }
+  return `${E2E}${file.slice(file.startsWith(UNIT) ? UNIT.length : TESTS.length)}`;
 }
 
 export function placementViolations(files: readonly string[]): readonly Violation[] {
@@ -91,11 +115,20 @@ export function placementViolations(files: readonly string[]): readonly Violatio
       });
       continue;
     }
+    const quarantineTarget = quarantineTargetFor(file);
+    if (quarantineTarget !== undefined) {
+      violations.push({
+        file,
+        line: undefined,
+        message: `a quarantined test keeps its level at tests/quarantine/<level>/, which the default run skips; move it to ${quarantineTarget}`,
+      });
+      continue;
+    }
     if (!TARGET_FILE.test(file)) {
       violations.push({
         file,
         line: undefined,
-        message: `a test file must live at tests/**/*.test.ts; move it to ${target}`,
+        message: `a test file must live at tests/<level>/**/*.test.ts, or tests/quarantine/<level>/**/*.test.ts while quarantined, with ${LEVEL_NAMES} as the level; move it to ${target}`,
       });
     }
   }
@@ -185,7 +218,7 @@ export const isolationViolations = Effect.fn("isolationViolations")(function* (f
         violations.push({
           file,
           line: lineOf(source, spanStart(node)),
-          message: `a test outside ${E2E} must stay in-process, and this ${use}; move it to ${E2E}${file.slice(TESTS.length)}`,
+          message: `a test outside ${E2E} must stay in-process, and this ${use}; move it to ${outOfProcessTargetFor(file)}`,
         });
       }
     }
@@ -333,7 +366,7 @@ export function report({ files, violations }: Result): string {
 const layout = Effect.gen(function* () {
   const path = yield* Path.Path;
   const root = process.argv[2] ?? process.cwd();
-  const result = yield* run(root, path.join(import.meta.dir, "..", "bunfig.toml"));
+  const result = yield* run(root, path.join(import.meta.dir, "..", "..", "bunfig.toml"));
   yield* Console.log(report(result));
   return result.violations.length === 0;
 });

package/{scripts → 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;

package/{scripts → src/testing}/test-skips.ts

@@ -1,5 +1,5 @@
 import { Effect, FileSystem, Path, Schema } from "effect";
-import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "./swc.ts";
+import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "../core/swc.ts";
 
 export type Environment = "ci" | "local";
 export type TestTier = "live" | "pixel";

package/{scripts → src/testing}/test.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { TEST_ENTRY_POINT } from "./gates.ts";
-import { runMain, Usage } from "./main.ts";
+import { TEST_ENTRY_POINT } from "../core/gates.ts";
+import { runMain, Usage } from "../core/main.ts";
 import { readSkipDeclarations, type Environment, type SkipDeclaration, type TestTier } from "./test-skips.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
 

package/CONTRIBUTING.md

@@ -1,94 +0,0 @@
-# Contribute to checks
-
-Whoever changes the kit follows these steps in a clone of this repository, before opening a pull request and when cutting a release.
-
-## Before you begin
-
-- Bun at the version `.bun-version` pins, since CI builds `dist/` with it and another version emits different bytes.
-
-## Check a change
-
-To check a change the way CI does:
-
-1. Run `bun install`.
-1. Run `bun run build`, which rewrites the files it generates, as Regenerate what is committed lists.
-1. Run `bun run lint`, which runs oxlint, the kit's own gates through `scripts/lint.ts`, and the dependency cruise.
-1. Run `bun run typecheck`.
-1. Run `bun run test`, which runs the suite through `scripts/test.ts`.
-
-Declare each skip with `skipReason(reason, name)` beside the native Bun test call, as [checks-test](docs/gates/checks-test.md) says.
-
-CI runs the commands in `.github/workflows/ci.yml` and lints the pull request title in `.github/workflows/commitlint.yml`.
-
-## Regenerate what is committed
-
-Each generated file is committed, and lint, the suite or CI's diff after the build fails on one left stale.
-
-To regenerate after an edit:
-
-1. After editing `effect-channel/`, `readability/` or the templates in `scripts/doc-templates.ts`, run `bun run build`.
-   It rewrites `dist/` and `templates/`.
-1. After editing anything a generated block names as its source in its opening marker, run `bun run build`, which rewrites every generated block.
-1. Commit what the command rewrote in the same commit as the edit.
-
-## Release a version
-
-A release is a tag on `main`, which the `release` workflow publishes through npm trusted publishing, so no token is stored anywhere and GitHub mints the publish credential for each run.
-
-To release a version:
-
-1. In a pull request that holds only the release, bump `version` in `package.json` and run `bun run build`.
-   The build writes the version's section into `CHANGELOG.md` from the conventional commits since the last release, so the changelog is never edited by hand.
-1. Commit both as `chore: release <version>` and title the pull request the same.
-   The squash merge lands the title as the commit's subject, and a `feat` or `fix` title would add an entry the committed changelog lacks.
-1. Merge `main` into the release branch and run `bun run build` again right before it merges, committing what it rewrote, since the build lists a commit merged in after the bump under the release.
-   Never rebase the release branch.
-1. Once it merges, tag that commit on `main` with the version and push the tag, since the version bump commit closes the release:
-
-   ```sh
-   tag="v$(bun -p 'require("./package.json").version')"
-   git tag "$tag" && git push origin "$tag"
-   ```
-
-1. Watch the `release` workflow.
-   It refuses a tag off `main` or one that disagrees with `package.json`.
-   It reruns the build, the check that the build changed no committed file, lint, typecheck and the suite before it publishes to npm.
-   After npm publish succeeds, the workflow creates or updates the GitHub release with the matching `CHANGELOG.md` section.
-
-`publishConfig.access` in `package.json` is what makes the scoped package public.
-npm attaches a trusted publisher only to a package that already exists, so a package's first version goes out by hand.
-That is `npm publish` from the tagged commit as `avi2dg`, then adding the trusted publisher in the package's npm settings, with the repository `avi2d/checks` and the workflow `release.yml`.
-That first tag's `release` run fails on the already-published version, and every later tag publishes through the workflow.
-
-## Find where a change goes
-
-To place a change:
-
-1. Find the path it belongs under:
-
-   | Path | What it holds |
-   | --- | --- |
-   | `scripts/` | every bin, and the modules they share |
-   | `effect-channel/` | the oxlint plugin with the Effect error-channel rules |
-   | `readability/` | the oxlint plugin with the readability rules |
-   | `dist/` | the committed oxlint plugin bundles |
-   | `presets/` | the Effect rule blocks consumers copy into native configs |
-   | `templates/` | one template per kind of doc file, which `bun run build` renders |
-   | `CHANGELOG.md` | every release, which `bun run build` writes from the conventional commits |
-   | `tests/` | the suite, with the tests that spawn a process under `tests/e2e/` |
-   | `docs/gates/` | one reference page per bin |
-   | `docs/configs/` | one reference page per shipped config a bin does not own |
-   | `docs/design.md` | why the kit is shaped the way it is |
-   | the root configs | `oxlintrc.json`, `tsconfig.effect.json`, `bunfig.toml`, `commitlint.config.js`, `dependency-cruiser.config.js`, `stryker.preset.js`, which a consuming repository extends or copies |
-
-1. Change the page under `docs/` that describes the behaviour in the same commit as the behaviour.
-   A new bin gets its page under `docs/gates/`, and the suite fails until it has one.
-
-This repository holds itself to the kit, with two exceptions of its own.
-Its `.dependency-cruiser.cjs` redeclares `no-orphans` with each plugin entry added to its `pathNot`.
-Its `.oxlintrc.json` lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`, whose synchronous `refused()` a host loads without `node_modules`.
-
-## Related topics
-
-- [checks](README.md)
-- [Why it is shaped this way](docs/design.md)

package/docs/gates/checks-backtest.md

@@ -1,54 +0,0 @@
----
-kind: reference
-audience: consumers
----
-# checks-backtest
-
-`checks-backtest` is the report of what the comment check would have refused at each recent commit, and a reader looks it up to measure a repository's own history before adopting the check.
-
-## What it checks
-
-It checks nothing and fails nothing.
-It walks recent first-parent commits, prints a row per commit that touches code and then the totals, attributes only the refusals each commit introduced, and counts new comment text as a share of added lines.
-A row holds the commit, its added lines, its added comment lines, its refusals and its subject.
-Each commit that introduced a refusal is then listed with its refusals.
-
-## What it reads
-
-It reads each commit and its first parent, and the files each commit changes that have a comment syntax in `scripts/comment-matchers.ts`.
-`generated/`, `vendor/`, `repos/`, `node_modules/` and `dist/` are out of reach, so the figures are authored code.
-
-## Arguments
-
-```sh
-checks-backtest [commit-count]
-```
-
-`commit-count` is the number of first-parent commits it walks, 60 when absent.
-
-## Exit codes
-
-| Code | When |
-| --- | --- |
-| 0 | the report printed |
-| 2 | it is given more than one argument, or git cannot read the history, as with a count git refuses |
-
-## Sample output
-
-```
-fe12189	9	0	0	feat(scripts): hold CONTRIBUTING.md to the how-to template
-086bdd0	1205	1	0	feat(scripts): add checks-docs gate holding doc files to s
-dc23b30	21	1	0	fix: release 0.12.0 and read local exports in checks-featu
-bcb4e3b	1252	4	0	feat(scripts): add size budget, feature-owner rules and ch
-4 commits touching code, 2487 added lines
-comment lines added: 6 (0.2% of added lines)
-refusals introduced: 0
-```
-
-## Opting out
-
-Nothing runs it but a person who wants the figures.
-
-## Related topics
-
-- [checks-comment-gate](checks-comment-gate.md)