@monte3l/groundwork 0.0.0

package/dist/toolchain/rules.js

@@ -0,0 +1,706 @@
+const NONE = { checked: 0, failures: [] };
+const lower = (value) => typeof value === "string" ? value.toLowerCase() : undefined;
+/**
+ * Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them
+ * (`outFile` and `moduleResolution: classic` already went in 6.0).
+ * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
+ */
+export const LEGACY_OPTIONS = [
+    {
+        option: "baseUrl",
+        label: "baseUrl",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => value !== undefined,
+    },
+    {
+        option: "outFile",
+        label: "outFile",
+        deprecatedIn: 6,
+        removedIn: 6,
+        matches: (value) => value !== undefined,
+    },
+    {
+        option: "moduleResolution",
+        label: "moduleResolution: node",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => ["node", "node10"].includes(lower(value) ?? ""),
+    },
+    {
+        option: "moduleResolution",
+        label: "moduleResolution: classic",
+        deprecatedIn: 6,
+        removedIn: 6,
+        matches: (value) => lower(value) === "classic",
+    },
+    {
+        option: "target",
+        label: "target: es5",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => lower(value) === "es5",
+    },
+    {
+        option: "downlevelIteration",
+        label: "downlevelIteration",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => value === true,
+    },
+    {
+        option: "module",
+        label: "module: amd|umd|system|none",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => ["amd", "umd", "system", "systemjs", "none"].includes(lower(value) ?? ""),
+    },
+    {
+        option: "esModuleInterop",
+        label: "esModuleInterop: false",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => value === false,
+    },
+    {
+        option: "allowSyntheticDefaultImports",
+        label: "allowSyntheticDefaultImports: false",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => value === false,
+    },
+    {
+        option: "alwaysStrict",
+        label: "alwaysStrict: false",
+        deprecatedIn: 6,
+        removedIn: 7,
+        matches: (value) => value === false,
+    },
+];
+/**
+ * The strict-family flags the baseline enables, plus `skipLibCheck`. Three
+ * omissions are deliberate and must not be "completed": `isolatedDeclarations`
+ * (the build project sets it alone; the tooling project includes tests/, which
+ * it does not tolerate), `noUnusedLocals`/`noUnusedParameters`
+ * (`@typescript-eslint/no-unused-vars` covers both with an `^_` escape hatch
+ * tsc's flags lack), and `forceConsistentCasingInFileNames` (defaults on).
+ * `allowUnreachableCode` is graded separately -- it must be `false`.
+ */
+export const STRICT_FLAGS = [
+    "strict",
+    "noUncheckedIndexedAccess",
+    "noImplicitOverride",
+    "exactOptionalPropertyTypes",
+    "verbatimModuleSyntax",
+    "isolatedModules",
+    "noFallthroughCasesInSwitch",
+    "noImplicitReturns",
+    "noPropertyAccessFromIndexSignature",
+    "noUncheckedSideEffectImports",
+    "skipLibCheck",
+];
+const MODERN_MODULES = new Set([
+    "nodenext",
+    "node16",
+    "node18",
+    "node20",
+    "preserve",
+]);
+const MODERN_RESOLUTIONS = new Set(["nodenext", "node16", "bundler"]);
+const MIN_TARGET_YEAR = 2022;
+const PIN_PACKAGES = [
+    "typescript",
+    "eslint",
+    "typescript-eslint",
+    "@types/node",
+];
+const PNPM_BUILTINS = new Set([
+    "exec",
+    "dlx",
+    "install",
+    "i",
+    "add",
+    "remove",
+    "update",
+    "audit",
+    "pack",
+    "publish",
+    "store",
+    "config",
+    "env",
+    "create",
+]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// --- helpers shared by rules -----------------------------------------------
+/** The first number in a range: `^6.0.3` gives 6. `undefined` when there is none (`workspace:*`, `catalog:`). */
+function majorOf(spec) {
+    const match = /(\d+)/.exec(spec ?? "");
+    return match?.[1] === undefined ? undefined : Number(match[1]);
+}
+function depSpec(snapshot, name) {
+    const pkg = snapshot.packageJson;
+    if (pkg === undefined)
+        return undefined;
+    for (const key of ["devDependencies", "dependencies"]) {
+        const section = pkg[key];
+        if (isRecord(section)) {
+            const spec = section[name];
+            if (typeof spec === "string")
+                return spec;
+        }
+    }
+    return undefined;
+}
+const isUnpinned = (spec) => /^\s*(\*|x|latest|next)?\s*$/i.test(spec);
+/**
+ * The chain a project's strict-flag judgement is made over: `tsconfig.json`,
+ * else the first chain no other chain extends (a leaf, not a base), else the
+ * first.
+ */
+function primaryChain(snapshot) {
+    const named = snapshot.chains.find((chain) => chain.entry === "tsconfig.json");
+    if (named !== undefined)
+        return named;
+    const leaf = snapshot.chains.find((chain) => !snapshot.chains.some((other) => other !== chain && other.files.some((f) => f.rel === chain.entry)));
+    return leaf ?? snapshot.chains[0];
+}
+function ownFiles(snapshot) {
+    return [...snapshot.tsconfigFiles.values()].filter((file) => file.error === undefined);
+}
+/** The first year an ES target denotes; `Infinity` for `esnext`; `undefined` when unrecognised. */
+function targetYear(target) {
+    const value = lower(target);
+    if (value === "esnext")
+        return Infinity;
+    const match = /^es(\d+)$/.exec(value ?? "");
+    if (match?.[1] === undefined)
+        return undefined;
+    const n = Number(match[1]);
+    return n < 100 ? n + 2009 : n;
+}
+/** The `.json` file a `tsc -b|-p <file>` script names, if it names one. */
+function scriptTsconfig(script) {
+    if (script === undefined)
+        return undefined;
+    const match = /\btsc\b[^&|;\n]*?\s(?:-b|--build|-p|--project)\s+(?:--\S+\s+)*([^\s&|;]+\.json)/.exec(script);
+    return match?.[1]?.replace(/^\.\//, "");
+}
+const gateLaneParity = {
+    id: "gate-lane-parity",
+    level: "structural",
+    category: "gates",
+    check: (s) => {
+        const { groups } = s.gates;
+        if (groups.length === 0)
+            return NONE;
+        const failures = [];
+        let checked = 0;
+        for (const lane of s.lanes) {
+            // A lane that runs verify.mjs with no static group (a matrix, or a bare
+            // full run) cannot be judged by reading it.
+            if (lane.dynamic)
+                continue;
+            for (const group of groups) {
+                checked += 1;
+                if (!lane.groups.includes(group)) {
+                    failures.push({
+                        subject: lane.surface,
+                        message: `has no \`verify.mjs --group ${group}\` invocation, so that group's steps are never gated here`,
+                    });
+                }
+            }
+            for (const named of new Set(lane.groups)) {
+                if (groups.includes(named))
+                    continue;
+                checked += 1;
+                failures.push({
+                    subject: lane.surface,
+                    message: `runs \`verify.mjs --group ${named}\`, but ${named} is not in GROUPS (${groups.join(", ")})`,
+                });
+            }
+            for (const step of new Set(lane.steps)) {
+                checked += 1;
+                failures.push({
+                    subject: lane.surface,
+                    message: `runs \`verify.mjs --step ${step}\` by id; name a group instead so a new step joins this lane without editing it`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+/** The lower and upper major an `engines.node` range implies; `undefined` for `||` ranges. */
+function enginesBounds(range) {
+    if (range.includes("||"))
+        return undefined;
+    const low = /(?:^|\s)(?:>=|\^|~|=)?\s*v?(\d+)/.exec(range);
+    const high = /<\s*(\d+)/.exec(range);
+    return {
+        min: low?.[1] === undefined ? undefined : Number(low[1]),
+        max: high?.[1] === undefined ? undefined : Number(high[1]),
+    };
+}
+// --- structural rules ------------------------------------------------------
+const tsconfigParses = {
+    id: "tsconfig-parses",
+    level: "structural",
+    category: "tsconfig",
+    check: (s) => ({
+        checked: s.tsconfigFiles.size,
+        failures: [...s.tsconfigFiles.values()]
+            .filter((file) => file.error !== undefined)
+            .map((file) => ({
+            subject: file.rel,
+            message: `does not parse as JSONC: ${file.error ?? ""}`,
+        })),
+    }),
+};
+const tsconfigExtendsResolves = {
+    id: "tsconfig-extends-resolves",
+    level: "structural",
+    category: "tsconfig",
+    check: (s) => {
+        // A bare specifier that resolves nowhere is not a failure: before
+        // `pnpm install` there is no node_modules to look in.
+        const judged = s.tsconfigLinks.filter((link) => link.kind === "relative" || link.resolved);
+        return {
+            checked: judged.length,
+            failures: judged
+                .filter((link) => !link.resolved)
+                .map((link) => ({
+                subject: link.from,
+                message: `extends "${link.specifier}", which resolves to no file`,
+            })),
+        };
+    },
+};
+const tsconfigEmitCoherence = {
+    id: "tsconfig-emit-coherence",
+    level: "structural",
+    category: "tsconfig",
+    check: (s) => {
+        const buildName = scriptTsconfig(s.scripts["build"]);
+        const build = s.chains.find((chain) => chain.entry === buildName);
+        if (build === undefined || !build.complete)
+            return NONE;
+        const failures = [];
+        let checked = 2;
+        if (build.options["outDir"] === undefined) {
+            failures.push({
+                subject: build.entry,
+                message: "is compiled by the `build` script but sets no outDir, so tsc emits .js next to the sources",
+            });
+        }
+        if (build.options["noEmit"] === true) {
+            failures.push({
+                subject: build.entry,
+                message: "is compiled by the `build` script but sets noEmit: true, so `build` emits nothing",
+            });
+        }
+        const tooling = s.chains.find((chain) => chain.entry === "tsconfig.json");
+        if (tooling !== undefined && tooling.complete && tooling !== build) {
+            checked += 1;
+            if (tooling.options["noEmit"] !== true) {
+                failures.push({
+                    subject: tooling.entry,
+                    message: `sits beside ${build.entry} as the tooling project but does not set noEmit: true, so typecheck would emit`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+const gateWiring = {
+    id: "gate-wiring",
+    level: "structural",
+    category: "gates",
+    check: (s) => {
+        const { stepsFile, groups, steps, packs } = s.gates;
+        const failures = [];
+        let checked = 0;
+        const scripts = s.packageJson === undefined ? undefined : s.scripts;
+        for (const step of steps) {
+            const [tool, first, second] = step.cmd;
+            if (tool === "pnpm" && scripts !== undefined && first !== undefined) {
+                const script = first === "run" ? second : first;
+                if (script !== undefined && !PNPM_BUILTINS.has(script)) {
+                    checked += 1;
+                    if (scripts[script] === undefined) {
+                        failures.push({
+                            subject: `${stepsFile ?? ""} step "${step.id}"`,
+                            message: `runs \`pnpm ${script}\`, but package.json has no "${script}" script`,
+                        });
+                    }
+                }
+            }
+            if (tool === "node" && first !== undefined && !first.startsWith("-")) {
+                checked += 1;
+                if (!s.projectFiles.has(first)) {
+                    failures.push({
+                        subject: `${stepsFile ?? ""} step "${step.id}"`,
+                        message: `runs \`node ${first}\`, which does not exist`,
+                    });
+                }
+            }
+            if (groups.length > 0 && step.group !== undefined) {
+                checked += 1;
+                if (!groups.includes(step.group)) {
+                    failures.push({
+                        subject: `${stepsFile ?? ""} step "${step.id}"`,
+                        message: `names group "${step.group}", which is not in GROUPS (${groups.join(", ")})`,
+                    });
+                }
+            }
+        }
+        if (steps.length > 0) {
+            for (const group of groups) {
+                checked += 1;
+                if (!steps.some((step) => step.group === group)) {
+                    failures.push({
+                        subject: `${stepsFile ?? ""} group "${group}"`,
+                        message: "has no step, so its lefthook lane and CI job gate nothing",
+                    });
+                }
+            }
+        }
+        if (packs !== undefined) {
+            checked += 1;
+            if (packs.error !== undefined) {
+                failures.push({
+                    subject: packs.path,
+                    message: `does not parse as JSON: ${packs.error}`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+const nodePinCoherence = {
+    id: "node-pin-coherence",
+    level: "structural",
+    category: "gates",
+    check: (s) => {
+        const pkg = s.packageJson;
+        const engines = pkg !== undefined && isRecord(pkg["engines"])
+            ? pkg["engines"]["node"]
+            : undefined;
+        if (s.nodeVersion === undefined || typeof engines !== "string")
+            return NONE;
+        const pin = /^v?(\d+)/.exec(s.nodeVersion);
+        const bounds = enginesBounds(engines);
+        if (pin?.[1] === undefined || bounds === undefined)
+            return NONE;
+        const major = Number(pin[1]);
+        const failures = [];
+        if (bounds.min !== undefined && major < bounds.min) {
+            failures.push({
+                subject: ".node-version",
+                message: `pins Node ${major}, below the ${bounds.min} that package.json engines.node ("${engines}") requires`,
+            });
+        }
+        if (bounds.max !== undefined && major >= bounds.max) {
+            failures.push({
+                subject: ".node-version",
+                message: `pins Node ${major}, at or above the ${bounds.max} that package.json engines.node ("${engines}") excludes`,
+            });
+        }
+        return { checked: 1, failures };
+    },
+};
+// --- rubric rules ----------------------------------------------------------
+const strictFlags = {
+    id: "strict-flags",
+    level: "rubric",
+    category: "tsconfig",
+    check: (s) => {
+        const chain = primaryChain(s);
+        if (chain === undefined || !chain.complete)
+            return NONE;
+        const failures = [];
+        const expectValue = (flag, wanted) => {
+            const value = chain.options[flag];
+            if (value === wanted)
+                return;
+            failures.push({
+                subject: chain.entry,
+                message: value === undefined
+                    ? `${flag} is not set (want ${wanted})`
+                    : `${flag} is ${JSON.stringify(value)} (want ${wanted})`,
+            });
+        };
+        for (const flag of STRICT_FLAGS)
+            expectValue(flag, true);
+        expectValue("allowUnreachableCode", false);
+        return { checked: STRICT_FLAGS.length + 1, failures };
+    },
+};
+const tsconfigOptionLifecycle = {
+    id: "tsconfig-option-lifecycle",
+    level: "rubric",
+    category: "tsconfig",
+    check: (s) => {
+        const major = majorOf(depSpec(s, "typescript"));
+        const files = ownFiles(s);
+        const failures = [];
+        for (const file of files) {
+            const hits = [];
+            if (major !== undefined) {
+                for (const row of LEGACY_OPTIONS) {
+                    if (!row.matches(file.options[row.option]))
+                        continue;
+                    if (major >= row.removedIn)
+                        hits.push(`${row.label} (removed)`);
+                    else if (major >= row.deprecatedIn)
+                        hits.push(`${row.label} (deprecated)`);
+                    else if (major + 1 >= row.removedIn) {
+                        hits.push(`${row.label} (removed in TypeScript ${row.removedIn})`);
+                    }
+                }
+            }
+            if (file.options["ignoreDeprecations"] !== undefined) {
+                hits.push("ignoreDeprecations (a migration aid, not a long-term setting)");
+            }
+            if (hits.length > 0) {
+                failures.push({
+                    subject: file.rel,
+                    message: `sets ${hits.join(", ")}`,
+                });
+            }
+        }
+        return { checked: files.length, failures };
+    },
+};
+const moduleTargetModern = {
+    id: "module-target-modern",
+    level: "rubric",
+    category: "modules",
+    check: (s) => {
+        const chain = primaryChain(s);
+        if (chain === undefined || !chain.complete)
+            return NONE;
+        const module = chain.options["module"];
+        const moduleResolution = chain.options["moduleResolution"];
+        const target = chain.options["target"];
+        const failures = [];
+        let checked = 0;
+        if (module !== undefined) {
+            checked += 1;
+            if (!MODERN_MODULES.has(lower(module) ?? "")) {
+                failures.push({
+                    subject: chain.entry,
+                    message: `module is ${JSON.stringify(module)}; use nodenext (Node) or preserve (bundler)`,
+                });
+            }
+        }
+        if (moduleResolution !== undefined) {
+            checked += 1;
+            if (!MODERN_RESOLUTIONS.has(lower(moduleResolution) ?? "")) {
+                failures.push({
+                    subject: chain.entry,
+                    message: `moduleResolution is ${JSON.stringify(moduleResolution)}; use nodenext or bundler`,
+                });
+            }
+        }
+        const year = targetYear(target);
+        if (year !== undefined) {
+            checked += 1;
+            if (year < MIN_TARGET_YEAR) {
+                failures.push({
+                    subject: chain.entry,
+                    message: `target is ${JSON.stringify(target)}; es2022 or later is the floor`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+const eslintFlatConfig = {
+    id: "eslint-flat-config",
+    level: "rubric",
+    category: "eslint",
+    check: (s) => {
+        const { flatFile, legacy } = s.eslint;
+        if (flatFile !== undefined)
+            return { checked: 1, failures: [] };
+        if (legacy.length === 0)
+            return NONE;
+        return {
+            checked: 1,
+            failures: legacy.map((name) => ({
+                subject: name,
+                message: "is a legacy eslintrc config; ESLint 10 reads only eslint.config.*",
+            })),
+        };
+    },
+};
+const eslintTypedLinting = {
+    id: "eslint-typed-linting",
+    level: "rubric",
+    category: "eslint",
+    check: (s) => {
+        const { flatFile, source } = s.eslint;
+        if (flatFile === undefined || source === undefined)
+            return NONE;
+        const direct = /\bfrom\s+["']typescript-eslint["']|require\(\s*["']typescript-eslint["']\s*\)/.test(source);
+        if (!direct) {
+            // A preset composed through a shared config package cannot be judged
+            // from this file alone -- say nothing rather than claim it is untyped.
+            if (/["'](?:@[^/"']+\/)?eslint-config[^"']*["']/.test(source))
+                return NONE;
+            return {
+                checked: 1,
+                failures: [
+                    {
+                        subject: flatFile,
+                        message: "does not use typescript-eslint, so no TypeScript-aware rules run",
+                    },
+                ],
+            };
+        }
+        const failures = [];
+        if (!/\b(?:recommended|strict)TypeChecked\b/.test(source)) {
+            failures.push({
+                subject: flatFile,
+                message: "uses typescript-eslint without a type-checked preset (recommendedTypeChecked or strictTypeChecked)",
+            });
+        }
+        if (!/\bprojectService\s*:/.test(source)) {
+            failures.push({
+                subject: flatFile,
+                message: "does not set parserOptions.projectService, so type-aware rules cannot read type information",
+            });
+        }
+        return { checked: 2, failures };
+    },
+};
+const eslintCoversEmittedCode = {
+    id: "eslint-covers-emitted-code",
+    level: "rubric",
+    category: "eslint",
+    check: (s) => {
+        const { flatFile, source } = s.eslint;
+        if (flatFile === undefined || source === undefined)
+            return NONE;
+        const failures = [];
+        let checked = 1;
+        const ignored = [...source.matchAll(/\bignores\s*:\s*\[([\s\S]*?)\]/g)]
+            .flatMap((block) => [...(block[1] ?? "").matchAll(/["']([^"']+)["']/g)])
+            .map((literal) => literal[1] ?? "");
+        for (const glob of ignored.filter((g) => /^(\*\*\/)?src(\/|$)/.test(g))) {
+            failures.push({
+                subject: flatFile,
+                message: `ignores "${glob}", so the project's own source is never linted`,
+            });
+        }
+        const files = [...s.projectFiles];
+        const scopes = [
+            ["bin/", /\.(?:mjs|js)$/, /["']bin\/[^"']*["']/],
+            [".claude/hooks/", /\.(?:mjs|js)$/, /["']\.claude\/hooks\/[^"']*["']/],
+        ];
+        for (const [prefix, extension, block] of scopes) {
+            if (!files.some((p) => p.startsWith(prefix) && extension.test(p)))
+                continue;
+            checked += 1;
+            if (!block.test(source)) {
+                failures.push({
+                    subject: flatFile,
+                    message: `has no config block for ${prefix}**, whose scripts are code this project runs`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+const coverageGate = {
+    id: "coverage-gate",
+    level: "rubric",
+    category: "testing",
+    check: (s) => {
+        const { file, source } = s.vitest;
+        if (file === undefined || source === undefined)
+            return NONE;
+        const failures = [];
+        if (!/\bthresholds\s*:/.test(source)) {
+            failures.push({
+                subject: file,
+                message: "sets no coverage thresholds, so coverage can fall without failing anything",
+            });
+        }
+        if (!/\bperFile\s*:\s*true\b/.test(source)) {
+            failures.push({
+                subject: file,
+                message: "does not set coverage.thresholds.perFile: true, so one well-covered file hides an untested one",
+            });
+        }
+        return { checked: 2, failures };
+    },
+};
+const toolchainPinShape = {
+    id: "toolchain-pin-shape",
+    level: "rubric",
+    category: "deps",
+    check: (s) => {
+        const pkg = s.packageJson;
+        if (pkg === undefined)
+            return NONE;
+        const failures = [];
+        let checked = 0;
+        const packages = [...PIN_PACKAGES];
+        if (s.vitest.file !== undefined || depSpec(s, "vitest") !== undefined) {
+            packages.push("vitest");
+        }
+        for (const name of packages) {
+            checked += 1;
+            const spec = depSpec(s, name);
+            if (spec === undefined) {
+                failures.push({
+                    subject: name,
+                    message: "is not declared in package.json",
+                });
+            }
+            else if (isUnpinned(spec)) {
+                failures.push({
+                    subject: name,
+                    message: `is "${spec}", not a real version range, so installs are not reproducible`,
+                });
+            }
+        }
+        checked += 1;
+        if (typeof pkg["packageManager"] !== "string") {
+            failures.push({
+                subject: "package.json",
+                message: "declares no packageManager, so the package-manager version is unpinned",
+            });
+        }
+        const types = majorOf(depSpec(s, "@types/node"));
+        const pin = /^v?(\d+)/.exec(s.nodeVersion ?? "");
+        if (types !== undefined && pin?.[1] !== undefined) {
+            checked += 1;
+            if (types !== Number(pin[1])) {
+                failures.push({
+                    subject: "@types/node",
+                    message: `is major ${types}, but .node-version pins Node ${pin[1]}, so types describe a different runtime`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+/** Every rule, structural first. Order is the order findings are reported in. */
+export const RULES = [
+    tsconfigParses,
+    tsconfigExtendsResolves,
+    tsconfigEmitCoherence,
+    gateWiring,
+    gateLaneParity,
+    nodePinCoherence,
+    strictFlags,
+    tsconfigOptionLifecycle,
+    moduleTargetModern,
+    eslintFlatConfig,
+    eslintTypedLinting,
+    eslintCoversEmittedCode,
+    coverageGate,
+    toolchainPinShape,
+];
+//# sourceMappingURL=rules.js.map