@avi2dg/checks 0.20.0 → 0.22.0

package/quality.schema.json

@@ -1,496 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "$schema": {
-      "type": "string"
-    },
-    "defaultBranch": {
-      "type": "string",
-      "minLength": 1,
-      "description": "The branch pull requests merge into; main when absent"
-    },
-    "gates": {
-      "type": "object",
-      "properties": {
-        "ci": {
-          "type": "array",
-          "prefixItems": [
-            {
-              "$ref": "#/$defs/Command"
-            }
-          ],
-          "minItems": 1,
-          "items": {
-            "$ref": "#/$defs/Command"
-          },
-          "description": "The commands CI runs on every pull request to the default branch, each one plain command"
-        },
-        "scheduled": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/Command"
-          },
-          "description": "The commands a cron-scheduled workflow runs"
-        },
-        "lint": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": [
-              "checks-lint-coverage",
-              "checks-test-layout",
-              "checks-commit-identity",
-              "checks-comment-gate",
-              "checks-suppressions-ratchet",
-              "checks-ci-wiring",
-              "checks-docs",
-              "checks-quality",
-              "checks-size-budget",
-              "checks-repetition",
-              "checks-feature-owners",
-              "checks-quarantine-clock"
-            ]
-          },
-          "allOf": [
-            {
-              "contains": {
-                "const": "checks-commit-identity"
-              }
-            },
-            {
-              "contains": {
-                "const": "checks-comment-gate"
-              }
-            },
-            {
-              "contains": {
-                "const": "checks-suppressions-ratchet"
-              }
-            },
-            {
-              "contains": {
-                "const": "checks-ci-wiring"
-              }
-            },
-            {
-              "contains": {
-                "const": "checks-docs"
-              }
-            },
-            {
-              "contains": {
-                "const": "checks-quarantine-clock"
-              }
-            }
-          ]
-        }
-      },
-      "additionalProperties": false
-    },
-    "commitIdentity": {
-      "type": "object",
-      "properties": {
-        "authors": {
-          "type": "array",
-          "prefixItems": [
-            {
-              "$ref": "#/$defs/Identity"
-            }
-          ],
-          "minItems": 1,
-          "items": {
-            "$ref": "#/$defs/Identity"
-          },
-          "description": "The identities allowed to author and commit, in place of the kit's default owner"
-        }
-      },
-      "required": [
-        "authors"
-      ],
-      "additionalProperties": false
-    },
-    "sources": {
-      "type": "object",
-      "properties": {
-        "production": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/PathGlob"
-          },
-          "description": "The source the repository ships, as against tests and tooling"
-        },
-        "libraries": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/Library"
-          }
-        },
-        "effect": {
-          "type": "object",
-          "properties": {
-            "paths": {
-              "type": "array",
-              "prefixItems": [
-                {
-                  "$ref": "#/$defs/PathGlob"
-                }
-              ],
-              "minItems": 1,
-              "items": {
-                "$ref": "#/$defs/PathGlob"
-              },
-              "description": "Where source is written in Effect, held to the Effect rules of oxlint and the language service"
-            },
-            "exempt": {
-              "type": "array",
-              "items": {
-                "$ref": "#/$defs/PathGlob"
-              },
-              "description": "Files under paths the Effect rules pass over"
-            }
-          },
-          "required": [
-            "paths"
-          ],
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false
-    },
-    "size": {
-      "type": "object",
-      "properties": {
-        "applies": {
-          "type": "string",
-          "enum": [
-            "ratchet",
-            "all"
-          ],
-          "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. ratchet when absent. The rest are listed as advisory"
-        },
-        "production": {
-          "type": "object",
-          "properties": {
-            "fileLines": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The most lines a file may hold, blank and comment lines counted; 400 when absent"
-            },
-            "functionLines": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The most lines a function may span, blank and comment lines counted; 100 when absent"
-            },
-            "statements": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The most statements a function may hold; 30 when absent"
-            },
-            "complexity": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The highest cognitive complexity a function may reach, a switch counted once; 15 when absent"
-            },
-            "depth": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The deepest a block may nest inside a function; 4 when absent"
-            }
-          },
-          "additionalProperties": false,
-          "description": "The budget of the files under sources.production, and of the files listed as advisory outside tests/"
-        },
-        "tests": {
-          "type": "object",
-          "properties": {
-            "fileLines": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The most lines a file may hold, blank and comment lines counted; 600 when absent"
-            },
-            "statements": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The most statements a function may hold; 50 when absent"
-            },
-            "complexity": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The highest cognitive complexity a function may reach, a switch counted once; 15 when absent"
-            },
-            "depth": {
-              "type": "integer",
-              "exclusiveMinimum": 0,
-              "description": "The deepest a block may nest inside a function; 4 when absent"
-            }
-          },
-          "additionalProperties": false,
-          "description": "The budget of the files under tests/, which sets no limit on a function's lines"
-        }
-      },
-      "additionalProperties": false,
-      "description": "The size budget oxlint holds production and test files to, read by checks-size-budget"
-    },
-    "features": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
-            "description": "The owner the dependency rule and the change signal name"
-          },
-          "root": {
-            "$ref": "#/$defs/DirectoryPath"
-          },
-          "entries": {
-            "type": "array",
-            "prefixItems": [
-              {
-                "$ref": "#/$defs/FilePath_1"
-              }
-            ],
-            "minItems": 1,
-            "items": {
-              "$ref": "#/$defs/FilePath_1"
-            },
-            "description": "The files under root that code outside it imports the feature through"
-          },
-          "allowFrom": {
-            "type": "array",
-            "items": {
-              "$ref": "#/$defs/PathGlob"
-            },
-            "description": "Files outside root that may import past its entries, such as a CLI or a harness; tests/ always may"
-          },
-          "proof": {
-            "$ref": "#/$defs/ProofPath"
-          }
-        },
-        "required": [
-          "name",
-          "root",
-          "entries",
-          "proof"
-        ],
-        "additionalProperties": false
-      }
-    },
-    "changeSignal": {
-      "type": "string",
-      "enum": [
-        "advisory"
-      ],
-      "description": "Report which feature owners a change touches, without failing on it"
-    },
-    "agentRules": {
-      "type": "object",
-      "properties": {
-        "on": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/RuleName"
-          },
-          "description": "Catalogued Rules switched on here"
-        },
-        "off": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/RuleName"
-          },
-          "description": "Catalogued Rules switched off here"
-        }
-      },
-      "additionalProperties": false
-    },
-    "docs": {
-      "type": "object",
-      "properties": {
-        "pages": {
-          "type": "object",
-          "properties": {
-            "tutorial": {
-              "type": "array",
-              "items": {
-                "$ref": "#/$defs/PathGlob"
-              },
-              "description": "The pages written as a tutorial, which teaches by building one thing"
-            },
-            "how-to": {
-              "type": "array",
-              "items": {
-                "$ref": "#/$defs/PathGlob"
-              },
-              "description": "The pages written as a how-to, which walks one task"
-            },
-            "reference": {
-              "type": "array",
-              "items": {
-                "$ref": "#/$defs/PathGlob"
-              },
-              "description": "The pages written as reference, which describes a thing to be looked up"
-            },
-            "explanation": {
-              "type": "array",
-              "items": {
-                "$ref": "#/$defs/PathGlob"
-              },
-              "description": "The pages written as an explanation, which says why"
-            }
-          },
-          "additionalProperties": false,
-          "description": "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
-        },
-        "forConsumers": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/DocGlob"
-          },
-          "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"
-        }
-      },
-      "additionalProperties": false,
-      "description": "What checks-docs reads to map a doc file to its template"
-    }
-  },
-  "additionalProperties": false,
-  "title": "quality.json",
-  "description": "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection",
-  "allOf": [
-    {
-      "if": {
-        "required": [
-          "size"
-        ]
-      },
-      "then": {
-        "required": [
-          "sources"
-        ],
-        "properties": {
-          "sources": {
-            "required": [
-              "production"
-            ],
-            "properties": {
-              "production": {
-                "minItems": 1
-              }
-            }
-          }
-        }
-      }
-    },
-    {
-      "if": {
-        "required": [
-          "changeSignal"
-        ]
-      },
-      "then": {
-        "required": [
-          "features"
-        ],
-        "properties": {
-          "features": {
-            "minItems": 1
-          }
-        }
-      }
-    }
-  ],
-  "$defs": {
-    "Command": {
-      "type": "string",
-      "minLength": 1
-    },
-    "Identity": {
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1
-        },
-        "email": {
-          "type": "string",
-          "minLength": 1
-        }
-      },
-      "required": [
-        "name",
-        "email"
-      ],
-      "additionalProperties": false
-    },
-    "PathGlob": {
-      "type": "string",
-      "pattern": "^(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+)(?:\\/(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+))*\\/(?:[\\w.@+-]|\\*(?!\\*))*\\.\\w+$",
-      "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 ./"
-    },
-    "FilePath": {
-      "type": "string",
-      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]*\\.\\w+$",
-      "description": "The manifest inside the clone holding the version; package.json when absent"
-    },
-    "Library": {
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string",
-          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
-          "description": "The link checks-vendor manages under repos/"
-        },
-        "package": {
-          "type": "string",
-          "minLength": 1,
-          "description": "The npm package whose installed version picks the tag"
-        },
-        "repository": {
-          "type": "string",
-          "minLength": 1,
-          "description": "The git remote checks-vendor clones the tag from"
-        },
-        "tag": {
-          "type": "string",
-          "pattern": "\\{version\\}",
-          "description": "The tag template, with {version} for the installed version"
-        },
-        "path": {
-          "$ref": "#/$defs/FilePath"
-        }
-      },
-      "required": [
-        "name",
-        "package",
-        "repository",
-        "tag"
-      ],
-      "additionalProperties": false
-    },
-    "DirectoryPath": {
-      "type": "string",
-      "pattern": "^(?!\\.\\.?(?:\\/|$))[\\w.@+-]+(?:\\/(?!\\.\\.?(?:\\/|$))[\\w.@+-]+)*$",
-      "description": "The directory the feature owns"
-    },
-    "FilePath_1": {
-      "type": "string",
-      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]*\\.\\w+$"
-    },
-    "ProofPath": {
-      "type": "string",
-      "pattern": "^tests\\/e2e\\/(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]+\\.test\\.tsx?$",
-      "description": "The end-to-end test that imports one of entries"
-    },
-    "RuleName": {
-      "type": "string",
-      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-    },
-    "DocGlob": {
-      "type": "string",
-      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+)\\/)*(?:[\\w.@+-]|\\*(?!\\*))*\\.\\w+$",
-      "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"
-    }
-  }
-}

package/scripts/feature-owners.ts

@@ -1,139 +0,0 @@
-#!/usr/bin/env bun
-import { parse } from "@swc/core";
-import { Console, Effect, Path, Schema } from "effect";
-import { changedPaths, git, pathsAt, rangeEnds, type Change } from "./git.ts";
-import { runMain } from "./main.ts";
-import { PROOF_DIRECTORY, type Feature } from "./quality-file.ts";
-import { rangeGateInputs } from "./range-gate.ts";
-
-type Unproven = {
-  readonly feature: string;
-  readonly reason: string;
-};
-
-type Touch = {
-  readonly feature: string;
-  readonly paths: readonly string[];
-};
-
-class ProofUnparsed extends Schema.TaggedError<ProofUnparsed>()("ProofUnparsed", {
-  message: Schema.String,
-}) {}
-
-const NAME = "feature-owners";
-const USAGE = "usage: feature-owners.ts <ref> | <base-ref> <head-ref>";
-const RELATIVE = /^\.\.?\//;
-const SCRIPT_EXTENSIONS = new Map([
-  [".js", [".ts", ".tsx"]],
-  [".jsx", [".tsx"]],
-  [".mjs", [".mts"]],
-  [".cjs", [".cts"]],
-]);
-
-const runtimeSpecifiers = Effect.fn("runtimeSpecifiers")(function* (file: string, source: string) {
-  const module = yield* Effect.tryPromise({
-    try: () => parse(source, { syntax: "typescript", tsx: file.endsWith(".tsx"), target: "esnext" }),
-    catch: (error) => new ProofUnparsed({ message: `${file} does not parse: ${String(error)}` }),
-  });
-  return module.body.flatMap((item) => {
-    if (item.type === "ImportDeclaration" && !item.typeOnly) return [item.source.value];
-    // swc types source as optional, but a local export such as `export { x }` carries null.
-    if (item.type === "ExportNamedDeclaration" && !item.typeOnly && item.source) return [item.source.value];
-    if (item.type === "ExportAllDeclaration") return [item.source.value];
-    return [];
-  });
-});
-
-const candidatesFor = Effect.fn("candidatesFor")(function* (importer: string, specifier: string) {
-  if (!RELATIVE.test(specifier)) return [];
-  const path = yield* Path.Path;
-  const target = path.join(path.dirname(importer), specifier);
-  const extension = path.extname(target);
-  const sources = SCRIPT_EXTENSIONS.get(extension);
-  if (sources !== undefined) return [target, ...sources.map((source) => `${target.slice(0, -extension.length)}${source}`)];
-  if (extension !== "") return [target];
-  return [`${target}.ts`, `${target}.tsx`, `${target}/index.ts`, `${target}/index.tsx`];
-});
-
-const proofImportsAnEntry = Effect.fn("proofImportsAnEntry")(function* (root: string, head: string, feature: Feature) {
-  const source = yield* git(["cat-file", "blob", `${head}:${feature.proof}`], root);
-  const specifiers = yield* runtimeSpecifiers(feature.proof, source);
-  const reached = yield* Effect.forEach(specifiers, (specifier) => candidatesFor(feature.proof, specifier));
-  return reached.flat().some((path) => feature.entries.includes(path));
-});
-
-const unproven = Effect.fn("unproven")(function* (root: string, head: string, features: readonly Feature[]) {
-  const declared = features.flatMap((feature) => [feature.proof, ...feature.entries]);
-  const present = new Set(yield* pathsAt(head, declared.map((path) => `:(literal)${path}`), root));
-  const found: Unproven[] = [];
-  for (const feature of features) {
-    const refuse = (reason: string) => found.push({ feature: feature.name, reason });
-    for (const entry of feature.entries.filter((path) => !present.has(path))) refuse(`entry ${entry} is not in the head commit`);
-    if (!present.has(feature.proof)) {
-      refuse(`proof ${feature.proof} is not in the head commit`);
-      continue;
-    }
-    const reason = yield* proofImportsAnEntry(root, head, feature).pipe(
-      Effect.map((imports) => (imports ? undefined : `proof ${feature.proof} imports none of its entries, ${feature.entries.join(", ")}`)),
-      Effect.catchTag("ProofUnparsed", (error) => Effect.succeed(`proof ${error.message}`)),
-    );
-    if (reason !== undefined) refuse(reason);
-  }
-  return found;
-});
-
-function ownerOf(features: readonly Feature[], path: string): string | undefined {
-  return features.find((feature) => path.startsWith(`${feature.root}/`) || path === feature.proof)?.name;
-}
-
-function touches(features: readonly Feature[], changes: readonly Change[]): readonly Touch[] {
-  const byOwner = new Map<string, string[]>();
-  for (const change of changes) {
-    for (const path of change.kind === "renamed" ? [change.from, change.path] : [change.path]) {
-      const owner = ownerOf(features, path);
-      if (owner === undefined) continue;
-      byOwner.set(owner, [...(byOwner.get(owner) ?? []), path]);
-    }
-  }
-  return features.flatMap((feature) => {
-    const paths = byOwner.get(feature.name);
-    return paths === undefined ? [] : [{ feature: feature.name, paths }];
-  });
-}
-
-function proofReport(features: readonly Feature[], found: readonly Unproven[]): string {
-  if (found.length === 0) {
-    return `${NAME}: ${features.length} feature(s) keep a proof under ${PROOF_DIRECTORY} that imports an entry`;
-  }
-  return [
-    `${NAME}: ${found.length} problem(s) with the features' runnable proofs:`,
-    ...found.map(({ feature, reason }) => `  ${feature}: ${reason}`),
-  ].join("\n");
-}
-
-function signalReport(touched: readonly Touch[]): string {
-  if (touched.length === 0) return `${NAME}: advisory, the range touches no feature owner`;
-  const judge = touched.length > 1 ? "; a reviewer judges whether they make one slice" : "";
-  return [
-    `${NAME}: advisory, the range touches ${touched.length} feature owner(s)${judge}:`,
-    ...touched.map(({ feature, paths }) => `  ${feature}: ${paths.join(", ")}`),
-  ].join("\n");
-}
-
-const owners = Effect.gen(function* () {
-  const { refs, root, source, quality } = yield* rangeGateInputs(USAGE);
-  const features = quality.features ?? [];
-  if (features.length === 0) {
-    yield* Console.log(`${NAME}: ${source} declares no feature`);
-    return true;
-  }
-  const { base, head } = yield* rangeEnds(refs.first, refs.second, root);
-  const found = yield* unproven(root, head, features);
-  yield* Console.log(proofReport(features, found));
-  if (quality.changeSignal === "advisory") {
-    yield* Console.log(signalReport(touches(features, yield* changedPaths(base, head, [], root))));
-  }
-  return found.length === 0;
-});
-
-if (import.meta.main) runMain(NAME, owners);