@monte3l/groundwork 0.0.0

package/dist/toolchain/grade.js

@@ -0,0 +1,244 @@
+/**
+ * Grades a project's TypeScript toolchain. `gradeToolchain` reads the tsconfig
+ * chains, ESLint and vitest configs, `package.json`, and the verify-step
+ * wiring once into a `ToolchainSnapshot`, then runs every rule in `rules.ts`
+ * over it. Offline and read-only -- it reads project files and never runs
+ * them, so it is safe to point at an adopted project.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJsoncFile, stripJsoncNoise } from "../jsonc.js";
+import { walkBounded } from "../survey/fs-walk.js";
+import { RULES } from "./rules.js";
+import { loadTsconfigChain } from "./tsconfig-chain.js";
+import { TOOLCHAIN_CATEGORIES } from "./types.js";
+const PROJECT_WALK_DEPTH = 6;
+const FLAT_ESLINT = [
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs",
+    "eslint.config.ts",
+    "eslint.config.mts",
+    "eslint.config.cts",
+];
+const LEGACY_ESLINT = /^\.eslintrc(\.(js|cjs|json|ya?ml))?$/;
+const VITEST_CONFIGS = [
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "vitest.config.cts",
+    "vitest.config.js",
+    "vitest.config.mjs",
+    "vitest.config.cjs",
+];
+const STEPS_PATH = "bin/lib/verify-steps.mjs";
+const PACKS_PATH = "bin/lib/verify-steps.packs.json";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** File text exactly as written, or `undefined` when unreadable. */
+function readRaw(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** File text with comments stripped, or `undefined` when unreadable. */
+function readSource(path) {
+    try {
+        return stripJsoncNoise(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Reads `verify-steps.mjs` as data: the `GROUPS` list and every `{ id, group, cmd }` literal. */
+function scrapeGateSteps(text) {
+    const groupList = /\bGROUPS\s*=\s*\[([^\]]*)\]/.exec(text);
+    const groups = groupList === null
+        ? []
+        : [...(groupList[1] ?? "").matchAll(/"([^"]+)"/g)].map((m) => m[1] ?? "");
+    const steps = [];
+    for (const match of text.matchAll(/\bid:\s*"([^"]+)"([^{}]*?)\bcmd:\s*\[([^\]]*)\]/g)) {
+        const group = /\bgroup:\s*"([^"]+)"/.exec(match[2] ?? "");
+        steps.push({
+            id: match[1] ?? "",
+            group: group?.[1],
+            cmd: [...(match[3] ?? "").matchAll(/"([^"]*)"/g)].map((m) => m[1] ?? ""),
+        });
+    }
+    return { groups, steps };
+}
+/**
+ * Reads every `verify.mjs` invocation out of one YAML surface as data: the
+ * `--group`/`--step` each names. YAML is scraped, never parsed. An invocation
+ * naming neither (a matrix, or a bare full run) marks the surface `dynamic`.
+ */
+function scrapeLaneInvocations(text) {
+    const groups = [];
+    const steps = [];
+    let dynamic = false;
+    let seen = false;
+    for (const raw of text.split("\n")) {
+        const line = raw.replace(/(^|\s)#.*$/, "");
+        const at = line.indexOf("verify.mjs");
+        if (at === -1)
+            continue;
+        seen = true;
+        const rest = line.slice(at);
+        const group = /--group[ =]+([A-Za-z][\w-]*)/.exec(rest);
+        const step = /--step[ =]+([A-Za-z][\w-]*)/.exec(rest);
+        if (group?.[1] !== undefined)
+            groups.push(group[1]);
+        else if (step?.[1] !== undefined)
+            steps.push(step[1]);
+        else
+            dynamic = true;
+    }
+    return { seen, groups, steps, dynamic };
+}
+function loadSnapshot(root) {
+    const entries = walkBounded(root, PROJECT_WALK_DEPTH);
+    const projectFiles = new Set(entries.filter((e) => !e.isDirectory).map((e) => e.relPath));
+    const rootFiles = [...projectFiles].filter((p) => !p.includes("/"));
+    const packageRead = readJsoncFile(join(root, "package.json"));
+    const packageJson = packageRead.ok && isRecord(packageRead.value)
+        ? packageRead.value
+        : undefined;
+    const scripts = {};
+    const rawScripts = packageJson?.["scripts"];
+    if (isRecord(rawScripts)) {
+        for (const [name, cmd] of Object.entries(rawScripts)) {
+            if (typeof cmd === "string")
+                scripts[name] = cmd;
+        }
+    }
+    const tsconfigFiles = new Map();
+    const tsconfigLinks = [];
+    const chains = rootFiles
+        .filter((name) => /^tsconfig(\..+)?\.json$/.test(name))
+        .sort()
+        .map((name) => loadTsconfigChain(root, name));
+    for (const chain of chains) {
+        for (const file of chain.files) {
+            // A node_modules base is read for its options, never graded as ours.
+            if (file.rel.startsWith("node_modules/") || file.rel.startsWith("..")) {
+                continue;
+            }
+            if (!tsconfigFiles.has(file.rel)) {
+                tsconfigFiles.set(file.rel, {
+                    rel: file.rel,
+                    error: file.error,
+                    options: file.options,
+                });
+            }
+        }
+        for (const link of chain.links) {
+            if (!tsconfigLinks.some((l) => l.from === link.from && l.specifier === link.specifier)) {
+                tsconfigLinks.push(link);
+            }
+        }
+    }
+    const flatFile = FLAT_ESLINT.find((name) => projectFiles.has(name));
+    const vitestFile = VITEST_CONFIGS.find((name) => projectFiles.has(name));
+    const stepsText = projectFiles.has(STEPS_PATH)
+        ? readSource(join(root, STEPS_PATH))
+        : undefined;
+    const packsRead = projectFiles.has(PACKS_PATH)
+        ? readJsoncFile(join(root, PACKS_PATH))
+        : undefined;
+    const nodeVersionText = projectFiles.has(".node-version")
+        ? readSource(join(root, ".node-version"))
+        : undefined;
+    const lanes = [];
+    const laneSurfaces = [
+        [
+            rootFiles.find((name) => /^lefthook\.ya?ml$/.test(name)) ??
+                "lefthook.yml",
+            rootFiles.filter((name) => /^lefthook\.ya?ml$/.test(name)),
+        ],
+        [
+            ".github/workflows",
+            [...projectFiles].filter((p) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(p)),
+        ],
+    ];
+    for (const [surface, paths] of laneSurfaces) {
+        const text = paths.map((p) => readRaw(join(root, p)) ?? "").join("\n");
+        const lane = scrapeLaneInvocations(text);
+        // A surface that never runs verify.mjs is not judged: absence is no defect.
+        if (lane.seen) {
+            lanes.push({
+                surface,
+                groups: lane.groups,
+                steps: lane.steps,
+                dynamic: lane.dynamic,
+            });
+        }
+    }
+    return {
+        packageJson,
+        scripts,
+        nodeVersion: nodeVersionText?.trim(),
+        tsconfigFiles,
+        tsconfigLinks,
+        chains,
+        eslint: {
+            flatFile,
+            source: flatFile === undefined ? undefined : readSource(join(root, flatFile)),
+            legacy: rootFiles.filter((name) => LEGACY_ESLINT.test(name)),
+        },
+        vitest: {
+            file: vitestFile,
+            source: vitestFile === undefined
+                ? undefined
+                : readSource(join(root, vitestFile)),
+        },
+        gates: {
+            stepsFile: stepsText === undefined ? undefined : STEPS_PATH,
+            ...(stepsText === undefined
+                ? { groups: [], steps: [] }
+                : scrapeGateSteps(stepsText)),
+            packs: packsRead === undefined
+                ? undefined
+                : {
+                    path: PACKS_PATH,
+                    error: packsRead.ok ? undefined : packsRead.error,
+                },
+        },
+        lanes,
+        projectFiles,
+    };
+}
+/** Runs every rule over the project rooted at `rootDir` and tallies the result. */
+export function gradeToolchain(rootDir) {
+    const snapshot = loadSnapshot(rootDir);
+    const findings = [];
+    const structural = { checked: 0, failed: 0 };
+    const rubric = Object.fromEntries(TOOLCHAIN_CATEGORIES.map((category) => [
+        category,
+        { checked: 0, failed: 0 },
+    ]));
+    for (const rule of RULES) {
+        const result = rule.check(snapshot);
+        const tally = rule.level === "structural" ? structural : rubric[rule.category];
+        tally.checked += result.checked;
+        tally.failed += result.failures.length;
+        for (const failure of result.failures) {
+            findings.push({
+                ruleId: rule.id,
+                level: rule.level,
+                category: rule.category,
+                subject: failure.subject,
+                message: failure.message,
+            });
+        }
+    }
+    const rubricChecked = Object.values(rubric).reduce((sum, tally) => sum + tally.checked, 0);
+    const rubricFailed = Object.values(rubric).reduce((sum, tally) => sum + tally.failed, 0);
+    return {
+        findings,
+        structural,
+        rubric,
+        rubricScore: rubricChecked === 0 ? 1 : 1 - rubricFailed / rubricChecked,
+    };
+}
+//# sourceMappingURL=grade.js.map

package/dist/toolchain/rules.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The toolchain grader's rules. Each rule is a pure function over a
+ * `ToolchainSnapshot` read once by `grade.ts`, so none of them touches the
+ * filesystem. Structural rules catch wiring defects `tsc` and ESLint do not --
+ * a build project that emits nowhere, a verify step naming a script that does
+ * not exist -- and fail a gate. Rubric rules encode the floor official
+ * TypeScript / typescript-eslint guidance sets and only ever warn.
+ *
+ * `eslint.config.js`, `vitest.config.ts` and `verify-steps.mjs` are executable
+ * JavaScript, so their rules are regex scrapes over comment-stripped source,
+ * never evaluation. A scrape that finds the file but cannot tell the answer
+ * returns `{ checked: 0 }` rather than a failure: absence, or a shape this
+ * module cannot read, is never a defect.
+ *
+ * `templates/core/bin/lib/toolchain-rules.mjs` carries the same rules for the
+ * emitted gate; `tests/toolchain/toolchain-parity.test.ts` runs both over the
+ * real baseline and asserts identical findings. Change a rule in one, change
+ * the other in the same commit.
+ */
+import type { RuleLevel } from "../harness/types.js";
+import type { ChainLink, TsconfigChain } from "./tsconfig-chain.js";
+import type { ToolchainCategory } from "./types.js";
+/** A tsconfig file the project itself owns (a `node_modules` base is not graded as ours). */
+export interface OwnTsconfigFile {
+    rel: string;
+    error: string | undefined;
+    options: Record<string, unknown>;
+}
+export interface GateStep {
+    id: string;
+    group: string | undefined;
+    cmd: string[];
+}
+/** The `verify.mjs` invocations one YAML surface (lefthook, CI workflows) makes, scraped as data. */
+export interface LaneSurface {
+    surface: string;
+    groups: string[];
+    steps: string[];
+    /** An invocation named no static group or step (a matrix, or a bare full run). */
+    dynamic: boolean;
+}
+export interface ToolchainSnapshot {
+    /** Parsed `package.json`, or `undefined` when absent or unparseable. */
+    packageJson: Record<string, unknown> | undefined;
+    /** `package.json` `scripts`, string values only. */
+    scripts: Record<string, string>;
+    /** Trimmed `.node-version`, or `undefined` when absent. */
+    nodeVersion: string | undefined;
+    tsconfigFiles: Map<string, OwnTsconfigFile>;
+    tsconfigLinks: ChainLink[];
+    /** One chain per root-level `tsconfig*.json`. */
+    chains: TsconfigChain[];
+    eslint: {
+        flatFile: string | undefined;
+        /** Comment-stripped source. Rules regex-scrape it; nothing evaluates it. */
+        source: string | undefined;
+        legacy: string[];
+    };
+    vitest: {
+        file: string | undefined;
+        source: string | undefined;
+    };
+    gates: {
+        stepsFile: string | undefined;
+        groups: string[];
+        steps: GateStep[];
+        packs: {
+            path: string;
+            error: string | undefined;
+        } | undefined;
+    };
+    /** Surfaces that run `verify.mjs`; one that never does is absent, not failed. */
+    lanes: LaneSurface[];
+    /** Every project file (bounded walk), project-relative. */
+    projectFiles: Set<string>;
+}
+interface RuleFailure {
+    subject: string;
+    message: string;
+}
+interface RuleResult {
+    /** How many subjects the rule examined -- the denominator of the rubric score. */
+    checked: number;
+    failures: RuleFailure[];
+}
+export interface ToolchainRule {
+    id: string;
+    level: RuleLevel;
+    category: ToolchainCategory;
+    check: (snapshot: ToolchainSnapshot) => RuleResult;
+}
+interface LegacyOption {
+    option: string;
+    label: string;
+    deprecatedIn: number;
+    removedIn: number;
+    matches: (value: unknown) => boolean;
+}
+/**
+ * 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 declare const LEGACY_OPTIONS: readonly LegacyOption[];
+/**
+ * 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 declare const STRICT_FLAGS: readonly string[];
+/** Every rule, structural first. Order is the order findings are reported in. */
+export declare const RULES: readonly ToolchainRule[];
+export {};
+//# sourceMappingURL=rules.d.ts.map