@avi2dg/checks 0.21.0 → 0.22.0

package/dist/feature-rules.js

@@ -1,354 +0,0 @@
-// scripts/feature-rules.ts
-import { Schema as Schema4 } from "effect";
-
-// scripts/quality-file.ts
-import { Console, Effect, FileSystem, JsonSchema, Path, Schema as Schema3 } from "effect";
-
-// scripts/gates.ts
-import { Schema } from "effect";
-var EVERY_REPOSITORY = "every repository";
-var QUALITY_FILE = "quality.json";
-var TYPESCRIPT_SOURCE = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
-var QUALITY_DECLARATION = { pathspecs: [QUALITY_FILE], content: `a ${QUALITY_FILE}` };
-var KIT_GATES = [
-  { bin: "checks-lint-coverage", script: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-test-layout", script: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-commit-identity", script: "commit-identity.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-comment-gate", script: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-suppressions-ratchet", script: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-ci-wiring", script: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-docs", script: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-quality", script: "quality.ts", reads: "tree", args: ["--check"], appliesTo: QUALITY_DECLARATION },
-  { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-repetition", script: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-quarantine-clock", script: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY }
-];
-var UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);
-var LintGates = Schema.Array(Schema.Literals(KIT_GATES.map((gate) => gate.bin))).check(Schema.makeFilter((selected) => {
-  const missing = UNCONDITIONAL.filter((bin) => !selected.includes(bin));
-  if (missing.length === 0)
-    return true;
-  const verb = missing.length === 1 ? "applies" : "apply";
-  return `checks-lint must run ${missing.join(", ")}, which ${verb} to ${EVERY_REPOSITORY}`;
-}, { toJsonSchema: () => ({ allOf: UNCONDITIONAL.map((bin) => ({ contains: { const: bin } })) }) }));
-
-// scripts/size-rules.ts
-import { Schema as Schema2 } from "effect";
-var TESTS_DIRECTORY = "tests";
-var COUNTED = { skipBlankLines: false, skipComments: false };
-var FILE_LINES = {
-  key: "fileLines",
-  rule: "max-lines",
-  options: COUNTED,
-  measured: /has too many lines \((\d+)\)/,
-  limits: "The most lines a file may hold, blank and comment lines counted"
-};
-var FUNCTION_LINES = {
-  key: "functionLines",
-  rule: "max-lines-per-function",
-  options: COUNTED,
-  measured: /has too many lines \((\d+)\)/,
-  limits: "The most lines a function may span, blank and comment lines counted"
-};
-var STATEMENTS = {
-  key: "statements",
-  rule: "max-statements",
-  options: {},
-  measured: /has too many statements \((\d+)\)/,
-  limits: "The most statements a function may hold"
-};
-var COMPLEXITY = {
-  key: "complexity",
-  rule: "cognitive-complexity",
-  plugin: "effect-channel",
-  options: {},
-  measured: /has a cognitive complexity of (\d+)/,
-  limits: "The highest cognitive complexity a function may reach, a switch counted once"
-};
-var DEPTH = {
-  key: "depth",
-  rule: "max-depth",
-  options: {},
-  measured: /nested too deeply \((\d+)\)/,
-  limits: "The deepest a block may nest inside a function"
-};
-var APPLIES = ["ratchet", "all"];
-var SIZE_DEFAULTS = {
-  applies: "ratchet",
-  production: { fileLines: 400, functionLines: 100, statements: 30, complexity: 15, depth: 4 },
-  tests: { fileLines: 600, statements: 50, complexity: 15, depth: 4 }
-};
-var Limit = Schema2.Int.check(Schema2.isGreaterThan(0));
-function limit({ limits }, fallback) {
-  return Schema2.optionalKey(Limit.annotate({ description: `${limits}; ${fallback} when absent` }));
-}
-var ProductionBudget = Schema2.Struct({
-  fileLines: limit(FILE_LINES, SIZE_DEFAULTS.production.fileLines),
-  functionLines: limit(FUNCTION_LINES, SIZE_DEFAULTS.production.functionLines),
-  statements: limit(STATEMENTS, SIZE_DEFAULTS.production.statements),
-  complexity: limit(COMPLEXITY, SIZE_DEFAULTS.production.complexity),
-  depth: limit(DEPTH, SIZE_DEFAULTS.production.depth)
-});
-var TestBudget = Schema2.Struct({
-  fileLines: limit(FILE_LINES, SIZE_DEFAULTS.tests.fileLines),
-  statements: limit(STATEMENTS, SIZE_DEFAULTS.tests.statements),
-  complexity: limit(COMPLEXITY, SIZE_DEFAULTS.tests.complexity),
-  depth: limit(DEPTH, SIZE_DEFAULTS.tests.depth)
-});
-var Size = Schema2.Struct({
-  applies: Schema2.optionalKey(Schema2.Literals(APPLIES).annotate({
-    description: `Which production and test files the budget holds: ratchet, the ones a range adds or changes, to no more overrun per rule than at the range's base; all, every one. ${SIZE_DEFAULTS.applies} when absent. The rest are listed as advisory`,
-    message: "Expected ratchet or all, and ratchet replaces changed"
-  })),
-  production: Schema2.optionalKey(ProductionBudget.annotate({
-    description: `The budget of the files under sources.production, and of the files listed as advisory outside ${TESTS_DIRECTORY}/`
-  })),
-  tests: Schema2.optionalKey(TestBudget.annotate({ description: `The budget of the files under ${TESTS_DIRECTORY}/, which sets no limit on a function's lines` }))
-}).annotate({
-  description: "The size budget oxlint holds production and test files to, read by checks-size-budget",
-  messageUnexpectedKey: "Expected only applies, production and tests, since each limit is set inside production or tests"
-});
-
-// scripts/quality-file.ts
-var SEGMENT = String.raw`(?!\.\.?(?:/|$))(?:\*\*|(?:[\w.@+-]|\*(?!\*))+)`;
-var FILE = String.raw`(?:[\w.@+-]|\*(?!\*))*\.\w+`;
-var PathGlob = Schema3.String.check(Schema3.isPattern(new RegExp(`^${SEGMENT}(?:/${SEGMENT})*/${FILE}$`), {
-  expected: "a glob from the repository root such as src/**/*.ts: a directory first, * within a segment, ** as a whole one, a file name with an extension last"
-})).annotate({
-  identifier: "PathGlob",
-  description: "A glob from the repository root that oxlint, the Effect language service and git read alike: a directory first, * within a segment, ** as a whole one, a file name with an extension last, and no braces, ?, [ or leading ./"
-});
-var DocGlob = Schema3.String.check(Schema3.isPattern(new RegExp(`^(?:${SEGMENT}/)*${FILE}$`), {
-  expected: "a glob from the repository root such as README.md or docs/**/*.md: * within a segment, ** as a whole one, a file name with an extension last"
-})).annotate({
-  identifier: "DocGlob",
-  description: "A glob from the repository root that checks-docs reads: * within a segment, ** as a whole one, a file name with an extension last"
-});
-var LITERAL_SEGMENT = String.raw`(?!\.\.?(?:/|$))[\w.@+-]+`;
-var DirectoryPath = Schema3.String.check(Schema3.isPattern(new RegExp(`^${LITERAL_SEGMENT}(?:/${LITERAL_SEGMENT})*$`), {
-  expected: "a directory from the repository root such as src/billing, with no glob and no trailing slash"
-})).annotate({ identifier: "DirectoryPath" });
-var FilePath = Schema3.String.check(Schema3.isPattern(new RegExp(`^(?:${LITERAL_SEGMENT}/)*[\\w.@+-]*\\.\\w+$`), {
-  expected: "a file from the repository root such as src/billing/index.ts, with no glob"
-})).annotate({ identifier: "FilePath" });
-var PROOF_DIRECTORY = "tests/e2e/";
-var ProofPath = Schema3.String.check(Schema3.isPattern(new RegExp(`^${PROOF_DIRECTORY}(?:${LITERAL_SEGMENT}/)*[\\w.@+-]+\\.test\\.tsx?$`), {
-  expected: `a test file under ${PROOF_DIRECTORY} such as ${PROOF_DIRECTORY}billing.test.ts`
-})).annotate({ identifier: "ProofPath" });
-var Command = Schema3.NonEmptyString.annotate({ identifier: "Command" });
-var RuleName = Schema3.String.check(Schema3.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a Rule name in kebab case" })).annotate({ identifier: "RuleName" });
-var Identity = Schema3.Struct({ name: Schema3.NonEmptyString, email: Schema3.NonEmptyString }).annotate({
-  identifier: "Identity"
-});
-var CommitIdentity = Schema3.Struct({
-  authors: Schema3.NonEmptyArray(Identity).annotate({
-    description: "The identities allowed to author and commit, in place of the kit's default owner"
-  })
-});
-var Gates = Schema3.Struct({
-  ci: Schema3.optionalKey(Schema3.NonEmptyArray(Command).annotate({
-    description: "The commands CI runs on every pull request to the default branch, each one plain command"
-  })),
-  scheduled: Schema3.optionalKey(Schema3.Array(Command).annotate({ description: "The commands a cron-scheduled workflow runs" })),
-  lint: Schema3.optionalKey(LintGates)
-});
-var RunsOn = Schema3.NonEmptyArray(Schema3.NonEmptyString).annotate({
-  identifier: "RunsOn",
-  description: "The runner labels every job the kit generates runs on; ubuntu-latest when absent"
-});
-var EffectSources = Schema3.Struct({
-  paths: Schema3.NonEmptyArray(PathGlob).annotate({
-    description: "Where source is written in Effect, held to the Effect rules of oxlint and the language service"
-  }),
-  exempt: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: "Files under paths the Effect rules pass over" }))
-});
-var Library = Schema3.Struct({
-  name: Schema3.String.check(Schema3.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a library name in kebab case" })).annotate({ description: "The link checks-vendor manages under repos/" }),
-  package: Schema3.NonEmptyString.annotate({ description: "The npm package whose installed version picks the tag" }),
-  repository: Schema3.NonEmptyString.annotate({ description: "The git remote checks-vendor clones the tag from" }),
-  tag: Schema3.String.check(Schema3.isPattern(/\{version\}/, { expected: "a tag template holding {version}" })).annotate({
-    description: "The tag template, with {version} for the installed version"
-  }),
-  path: Schema3.optionalKey(FilePath.annotate({ description: "The manifest inside the clone holding the version; package.json when absent" }))
-}).annotate({ identifier: "Library" });
-var Sources = Schema3.Struct({
-  production: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: "The source the repository ships, as against tests and tooling" })),
-  libraries: Schema3.optionalKey(Schema3.Array(Library).check(Schema3.makeFilter((libraries) => {
-    const repeated = duplicates(libraries.map((library) => library.name));
-    return repeated === undefined || `names ${repeated} more than once`;
-  })).annotate({ description: "The libraries checks-vendor pins to a shared read-only clone" })),
-  effect: Schema3.optionalKey(EffectSources)
-});
-var Feature = Schema3.Struct({
-  name: Schema3.String.check(Schema3.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a feature name in kebab case" })).annotate({ description: "The owner the dependency rule and the change signal name" }),
-  root: DirectoryPath.annotate({ description: "The directory the feature owns" }),
-  entries: Schema3.NonEmptyArray(FilePath).annotate({
-    description: "The files under root that code outside it imports the feature through"
-  }),
-  allowFrom: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({
-    description: "Files outside root that may import past its entries, such as a CLI or a harness; tests/ always may"
-  })),
-  proof: ProofPath.annotate({ description: "The end-to-end test that imports one of entries" })
-}).check(Schema3.makeFilter(({ root, entries }) => {
-  const outside = entries.filter((entry) => !entry.startsWith(`${root}/`));
-  return outside.length === 0 || `lists ${outside.join(", ")} among its entries, outside its root ${root}`;
-}));
-function nests(outer, inner) {
-  return outer === inner || inner.startsWith(`${outer}/`);
-}
-function duplicates(names) {
-  const repeated = names.filter((name, index) => names.indexOf(name) !== index);
-  return repeated.length === 0 ? undefined : [...new Set(repeated)].join(", ");
-}
-var Features = Schema3.Array(Feature).check(Schema3.makeFilter((features) => {
-  const repeated = duplicates(features.map((feature) => feature.name));
-  if (repeated !== undefined)
-    return `names ${repeated} more than once`;
-  for (const outer of features) {
-    const inner = features.find((other) => other !== outer && nests(outer.root, other.root));
-    if (inner !== undefined)
-      return `gives ${inner.root} to both ${outer.name} and ${inner.name}`;
-  }
-  return true;
-}));
-var AgentRules = Schema3.Struct({
-  on: Schema3.optionalKey(Schema3.Array(RuleName).annotate({ description: "Catalogued Rules switched on here" })),
-  off: Schema3.optionalKey(Schema3.Array(RuleName).annotate({ description: "Catalogued Rules switched off here" }))
-}).check(Schema3.makeFilter(({ on = [], off = [] }) => {
-  const both = on.filter((rule) => off.includes(rule));
-  return both.length === 0 || `switches ${both.join(", ")} both on and off`;
-}));
-var pagesIn = (mode) => Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: `The pages written as ${mode}` }));
-var Docs = Schema3.Struct({
-  pages: Schema3.optionalKey(Schema3.Struct({
-    tutorial: pagesIn("a tutorial, which teaches by building one thing"),
-    "how-to": pagesIn("a how-to, which walks one task"),
-    reference: pagesIn("reference, which describes a thing to be looked up"),
-    explanation: pagesIn("an explanation, which says why")
-  }).annotate({
-    description: "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
-  })),
-  forConsumers: Schema3.optionalKey(Schema3.Array(DocGlob).annotate({
-    description: "The living docs that speak to a repository installing this one, whose bun run commands checks-docs does not hold to this package.json"
-  }))
-});
-var Quality = Schema3.Struct({
-  $schema: Schema3.optionalKey(Schema3.String),
-  defaultBranch: Schema3.optionalKey(Schema3.NonEmptyString.annotate({ description: "The branch pull requests merge into; main when absent" })),
-  gates: Schema3.optionalKey(Gates),
-  runsOn: Schema3.optionalKey(RunsOn),
-  commitIdentity: Schema3.optionalKey(CommitIdentity),
-  sources: Schema3.optionalKey(Sources),
-  size: Schema3.optionalKey(Size),
-  features: Schema3.optionalKey(Features.annotate({
-    description: "The feature owners dependency-cruiser holds to their entries and checks-feature-owners maps a change to"
-  })),
-  changeSignal: Schema3.optionalKey(Schema3.Literal("advisory").annotate({
-    description: "Report which feature owners a change touches, without failing on it"
-  })),
-  agentRules: Schema3.optionalKey(AgentRules),
-  docs: Schema3.optionalKey(Docs.annotate({ description: "What checks-docs reads to map a doc file to its template" }))
-}).annotate({
-  title: QUALITY_FILE,
-  description: "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection"
-}).check(Schema3.makeFilter(({ size, sources }) => size === undefined || (sources?.production ?? []).length > 0 || "declares size, which holds no production file without sources.production", {
-  toJsonSchema: () => ({
-    if: { required: ["size"] },
-    then: { required: ["sources"], properties: { sources: { required: ["production"], properties: { production: { minItems: 1 } } } } }
-  })
-}), Schema3.makeFilter(({ changeSignal, features = [] }) => changeSignal === undefined || features.length > 0 || "declares changeSignal, which maps a change to no owner without features", {
-  toJsonSchema: () => ({
-    if: { required: ["changeSignal"] },
-    then: { required: ["features"], properties: { features: { minItems: 1 } } }
-  })
-}));
-var LegacyManifest = Schema3.Struct({
-  ciWiring: Schema3.optionalKey(Schema3.Struct({
-    gates: Schema3.optionalKey(Schema3.NonEmptyArray(Command)),
-    scheduled: Schema3.optionalKey(Schema3.Array(Command)),
-    lintGates: Schema3.optionalKey(LintGates),
-    defaultBranch: Schema3.optionalKey(Schema3.NonEmptyString)
-  })),
-  commitIdentity: Schema3.optionalKey(CommitIdentity)
-});
-var LEGACY_KEYS = ["ciWiring", "commitIdentity"];
-
-class QualityUnreadable extends Schema3.TaggedError()("QualityUnreadable", {
-  message: Schema3.String
-}) {
-}
-var MANIFEST = "package.json";
-var decodeQualityJson = Schema3.decodeUnknownEffect(Schema3.fromJsonString(Quality), { onExcessProperty: "error" });
-var decodeManifestJson = Schema3.decodeUnknownEffect(Schema3.fromJsonString(LegacyManifest));
-var decodeQuality = (text, source) => decodeQualityJson(text).pipe(Effect.mapError((cause) => new QualityUnreadable({ message: `${source}: ${cause.message}` })));
-function fromLegacy({ ciWiring, commitIdentity }) {
-  const gates = {
-    ...ciWiring?.gates === undefined ? {} : { ci: ciWiring.gates },
-    ...ciWiring?.scheduled === undefined ? {} : { scheduled: ciWiring.scheduled },
-    ...ciWiring?.lintGates === undefined ? {} : { lint: ciWiring.lintGates }
-  };
-  return {
-    ...ciWiring?.defaultBranch === undefined ? {} : { defaultBranch: ciWiring.defaultBranch },
-    ...Object.keys(gates).length === 0 ? {} : { gates },
-    ...commitIdentity === undefined ? {} : { commitIdentity }
-  };
-}
-var decodeManifest = (text, source) => decodeManifestJson(text).pipe(Effect.map((manifest) => ({
-  keys: LEGACY_KEYS.filter((key) => manifest[key] !== undefined),
-  quality: fromLegacy(manifest)
-})), Effect.mapError((cause) => new QualityUnreadable({ message: `${source}: ${cause.message}` })));
-var UNDECLARED = { keys: [], quality: {} };
-var readQuality = Effect.fn("readQuality")(function* (root) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const read = (file) => fs.readFileString(path.join(root, file)).pipe(Effect.mapError((cause) => new QualityUnreadable({ message: `cannot read ${file}: ${cause.message}` })));
-  const legacy = (yield* fs.exists(path.join(root, MANIFEST))) ? yield* decodeManifest(yield* read(MANIFEST), MANIFEST) : UNDECLARED;
-  const keys = legacy.keys.join(" and ");
-  if (yield* fs.exists(path.join(root, QUALITY_FILE))) {
-    if (legacy.keys.length > 0) {
-      return yield* new QualityUnreadable({
-        message: `${MANIFEST} still sets ${keys}, which ${QUALITY_FILE} replaces; move what it holds there`
-      });
-    }
-    return { source: QUALITY_FILE, quality: yield* decodeQuality(yield* read(QUALITY_FILE), QUALITY_FILE) };
-  }
-  if (legacy.keys.length > 0) {
-    const them = legacy.keys.length === 1 ? "it" : "them";
-    yield* Console.error(`${MANIFEST} sets ${keys}, which a later minor release stops reading; move ${them} into ${QUALITY_FILE}`);
-  }
-  return { source: MANIFEST, quality: legacy.quality };
-});
-
-// scripts/feature-rules.ts
-var TESTS = "^tests/";
-function escaped(literal) {
-  return literal.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
-}
-function globPattern(glob) {
-  const segments = glob.split("/");
-  const body = segments.map((segment, index) => {
-    if (segment === "**")
-      return "(?:[^/]+/)*";
-    const pattern = segment.split("*").map(escaped).join("[^/]*");
-    return index === segments.length - 1 ? pattern : `${pattern}/`;
-  });
-  return `^${body.join("")}$`;
-}
-function rulesFor(features) {
-  return features.map(({ name, root, entries, allowFrom = [] }) => ({
-    name: `feature-${name}-entries`,
-    severity: "error",
-    comment: `Outside ${root}/, ${name} is imported through ${entries.join(", ")}. Import one of those, or list the importer in the feature's allowFrom in quality.json.`,
-    from: { pathNot: [`^${escaped(root)}/`, TESTS, ...allowFrom.map(globPattern)] },
-    to: { path: `^${escaped(root)}/`, pathNot: entries.map((entry) => `^${escaped(entry)}$`) }
-  }));
-}
-var decode = Schema4.decodeUnknownSync(Quality);
-function featureRules(quality) {
-  return rulesFor(decode(quality, { onExcessProperty: "error" }).features ?? []);
-}
-export {
-  globPattern,
-  featureRules
-};

package/docs/configs/quality-file.md

@@ -1,103 +0,0 @@
-# The quality file
-
-`quality.json` at the repository root says what the repository has opted into, and a reader looks it up to learn what each key holds and which bin reads it.
-
-## Keys
-
-The kit's bins find the file at the git root and read it there:
-
-```json
-{
-  "$schema": "./node_modules/@avi2dg/checks/quality.schema.json",
-  "defaultBranch": "main",
-  "gates": {
-    "ci": ["bun run lint", "bun run typecheck", "bun run test"],
-    "scheduled": ["bunx checks-flake --runs 10 --report flake-report.json"]
-  },
-  "runsOn": ["self-hosted", "Linux", "X64", "winbox"],
-  "commitIdentity": { "authors": [{ "name": "avi2d", "email": "avi2dg@gmail.com" }] },
-  "sources": {
-    "production": ["src/**/*.ts"],
-    "effect": { "paths": ["src/**/*.ts"], "exempt": ["src/host/*.ts"] }
-  },
-  "size": { "applies": "ratchet", "tests": { "fileLines": 800 } },
-  "features": [
-    {
-      "name": "billing",
-      "root": "src/billing",
-      "entries": ["src/billing/index.ts"],
-      "allowFrom": ["src/main.ts"],
-      "proof": "tests/e2e/billing.test.ts"
-    }
-  ],
-  "changeSignal": "advisory",
-  "agentRules": { "on": [], "off": [] },
-  "docs": { "pages": { "reference": ["docs/gates/*.md"], "explanation": ["docs/design.md"] } }
-}
-```
-
-<!-- generated quality-keys: bun run build writes it from Quality in scripts/quality-file.ts and scripts/doc-blocks.ts -->
-
-| Key | Read by | Holds |
-| --- | --- | --- |
-| `defaultBranch` | `checks-lint`, `checks-ci-wiring`, `checks-quality` | the branch pull requests merge into, `main` when absent |
-| `gates.ci` | `checks-ci-wiring`, `checks-quality` | the commands CI runs on every pull request, as [checks-ci-wiring](../gates/checks-ci-wiring.md) says |
-| `gates.scheduled` | `checks-ci-wiring` | the commands a schedule runs |
-| `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply, as [Gate selection](../gates/checks-lint.md#gate-selection) says |
-| `runsOn` | `checks-quality` | the runner labels every job the ci and commitlint workflows run on, `ubuntu-latest` when absent |
-| `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit, as [checks-commit-identity](../gates/checks-commit-identity.md) says |
-| `sources.production` | `checks-size-budget`, `checks-repetition`, `checks-quality` | the source the repository ships, as [checks-size-budget](../gates/checks-size-budget.md) and [checks-repetition](../gates/checks-repetition.md) say |
-| `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not, as [The Effect rules](effect-rules.md) says |
-| `sources.libraries` | `checks-vendor`, `checks-test-layout` | the libraries pinned to a shared read-only clone, as [checks-vendor](../gates/checks-vendor.md) says |
-| `size` | `checks-size-budget` | the size budget of production and test files, and how a change is held to it, as [checks-size-budget](../gates/checks-size-budget.md) says |
-| `features` | `featureRules`, `checks-feature-owners` | each feature's root, entries, exempt importers and proof, as [checks-feature-owners](../gates/checks-feature-owners.md) says |
-| `changeSignal` | `checks-feature-owners` | `advisory` to list the feature owners a change touches |
-| `agentRules.on` | agent Rule selection, not the kit | catalogued Rules switched on for this repository |
-| `agentRules.off` | agent Rule selection, not the kit | catalogued Rules switched off for this repository |
-| `docs.pages` | `checks-docs` | the Diátaxis mode of each page, by glob, as [checks-docs](../gates/checks-docs.md) says |
-| `docs.forConsumers` | `checks-docs` | the living docs that speak to a repository installing this one, by glob, whose `bun run` commands name that repository's scripts |
-
-<!-- end generated quality-keys -->
-
-Every key is optional.
-
-## Schema
-
-The bins decode the file with one Effect `Schema`, and the package ships `quality.schema.json` emitted from that schema.
-The `$schema` line therefore gives an editor the verdict the bins reach, save what no JSON Schema can express across two values, which the bins refuse:
-
-- a Rule switched both on and off
-- a feature entry outside its root
-- two features with one name or sharing a root
-
-A key the schema does not name is refused, not ignored, so a misspelt `sources` cannot switch the Effect rules off unnoticed.
-
-## Globs
-
-A glob in `sources` starts at the repository root, names a directory first, uses `*` only within a segment and `**` only as a whole one, and ends in a file name with an extension.
-Those are the globs oxlint, the language service and git all read alike.
-oxlint matches `*.ts` at any depth where the other two match it at the root alone, so the schema refuses it, and `**/*.ts` means every depth to all three.
-The language service matches nothing for `src/**` and oxlint nothing for `src/lib`, so the schema refuses both, and `src/**/*.ts` and `src/lib/*.ts` say it to all three.
-
-## Keys moved from package.json
-
-A repository with no `quality.json` still has `ciWiring` and `commitIdentity` read from `package.json`, with a notice on each read.
-One with both files exits 2 until `package.json` drops them.
-The keys map one for one:
-
-<!-- generated legacy-keys: bun run build writes it from LegacyManifest in scripts/quality-file.ts, QUALITY_FILE in scripts/gates.ts and scripts/doc-blocks.ts -->
-
-| `package.json` | `quality.json` |
-| --- | --- |
-| `ciWiring.gates` | `gates.ci` |
-| `ciWiring.scheduled` | `gates.scheduled` |
-| `ciWiring.lintGates` | `gates.lint` |
-| `ciWiring.defaultBranch` | `defaultBranch` |
-| `commitIdentity` | `commitIdentity` |
-
-<!-- end generated legacy-keys -->
-
-## Related topics
-
-- [checks-quality](../gates/checks-quality.md)
-- [Why it is shaped this way](../design.md)

package/docs/gates/checks-feature-owners.md

@@ -1,113 +0,0 @@
-# checks-feature-owners
-
-`checks-feature-owners` is the gate that holds each declared feature to a runnable proof and lists the feature owners a change touches, and a reader looks it up to declare a feature.
-
-## What it checks
-
-A repository opts a feature in by declaring, in `quality.json`, the directory it owns, the files code outside it imports it through, the files that may reach past those, and the end-to-end test that proves it runs:
-
-```json
-"features": [
-  {
-    "name": "billing",
-    "root": "src/billing",
-    "entries": ["src/billing/index.ts"],
-    "allowFrom": ["src/main.ts", "src/cli/*.ts"],
-    "proof": "tests/e2e/billing.test.ts"
-  }
-],
-"changeSignal": "advisory"
-```
-
-`root` is a directory and `entries` are files under it, both without globs.
-`allowFrom` holds globs of the same shape as `sources`.
-`proof` is a `.test.ts` or `.test.tsx` file under `tests/e2e/`.
-Nothing moves, since a root is wherever the feature already lives.
-`quality.json` refuses an entry outside its root, a name used twice, and two features sharing a root or one root inside another, so a file has at most one owner.
-
-The gate fails when a feature's proof cannot prove it:
-
-- the proof or an entry is not in the head commit
-- the proof does not parse
-- the proof imports none of the feature's entries
-
-An import counts when it is a runtime `import`, `export ... from` or `export * from` of a relative path that names an entry.
-It names the entry by its own name, by the `.js`, `.jsx`, `.mjs` or `.cjs` spelling of it, or without an extension, the way a directory `index` is imported.
-`.js` names a `.tsx` entry as well as a `.ts` one.
-`import type` does not count, and neither does a path alias.
-The proof runs in `bun run test` like any end-to-end test, which is what shows it passes.
-
-With `changeSignal` set to `advisory` it also lists each owner the range touches, with the paths it touched under the owner's root or at its proof, and still passes.
-Whether a change that spans owners is one coherent slice is for a reviewer to judge.
-A rename counts at both of its paths.
-
-## What it reads
-
-It reads `features` and `changeSignal` from `quality.json`, each proof and entry from the head commit, and the paths the range touches.
-
-## Arguments
-
-```sh
-checks-feature-owners <base-ref> <head-ref>
-checks-feature-owners <ref>
-```
-
-With two arguments the range starts where the head branched from the base, at their merge-base.
-With one it is that commit against its parent, or against the empty tree for a repository's first commit.
-
-## Exit codes
-
-| Code | When |
-| --- | --- |
-| 0 | every feature's proof imports one of its entries |
-| 1 | a feature's proof cannot prove it |
-| 2 | `quality.json` does not decode, which is where a proof outside `tests/e2e/` is refused, or a ref does not resolve |
-
-## Sample output
-
-```
-feature-owners: 1 problem(s) with the features' runnable proofs:
-  billing: proof tests/e2e/billing.test.ts imports none of its entries, src/billing/index.ts
-```
-
-With `changeSignal` set to `advisory`:
-
-```
-feature-owners: advisory, the range touches 2 feature owner(s); a reviewer judges whether they make one slice:
-  billing: src/billing/charge.ts, src/billing/tax.ts
-  invoices: src/invoices/tax.ts, tests/e2e/invoices.test.ts
-```
-
-## Opting out
-
-A repository that declares no feature passes.
-`quality.json` refuses a `changeSignal` without features, which would map a change to no owner.
-A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
-
-## Import boundary
-
-`dist/feature-rules.js` compiles `features` into one dependency-cruiser rule per feature, which `.dependency-cruiser.cjs` spreads beside its own:
-
-```js
-const { featureRules } = require("@avi2dg/checks/dist/feature-rules.js");
-
-module.exports = {
-  extends: "./node_modules/@avi2dg/checks/dependency-cruiser.config.js",
-  forbidden: [...featureRules(require("./quality.json"))],
-};
-```
-
-A module outside a feature's root that imports a file inside it must import one of the feature's `entries`.
-Modules under `tests/` and the files `allowFrom` matches, such as a CLI or a harness, may import any file in it:
-
-```
-error feature-billing-entries: src/report.ts → src/billing/charge.ts
-```
-
-`featureRules` decodes its argument with the schema the bins use and throws the schema's refusal when it does not decode, which stops the cruise.
-It is an ES module, as `effect` is, so a `.cjs` config loads it through `require`, which needs node 20.19, 22.12 or later.
-
-## Related topics
-
-- [The dependency rules](../configs/dependency-rules.md)
-- [The quality file](../configs/quality-file.md)