@monte3l/groundwork 0.1.0-next.1 → 1.0.0-rc.3

package/dist/toolchain/rules.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 const NONE = { checked: 0, failures: [] };
 const lower = (value) => typeof value === "string" ? value.toLowerCase() : undefined;
 /**
@@ -185,6 +187,7 @@ function scriptTsconfig(script) {
     const match = /\btsc\b[^&|;\n]*?\s(?:-b|--build|-p|--project)\s+(?:--\S+\s+)*([^\s&|;]+\.json)/.exec(script);
     return match?.[1]?.replace(/^\.\//, "");
 }
+/** Confirms every CI/lefthook lane invokes verify.mjs by static group name, not by step id or a dynamic matrix -- otherwise a new gate can silently go unenforced in one surface while it passes in another. */
 const gateLaneParity = {
     id: "gate-lane-parity",
     level: "structural",
@@ -241,6 +244,7 @@ function enginesBounds(range) {
     };
 }
 // --- structural rules ------------------------------------------------------
+/** A tsconfig that fails to parse breaks every rule that reads its chain -- reporting the parse error itself, first, keeps a later rule's silence from being mistaken for a clean file. */
 const tsconfigParses = {
     id: "tsconfig-parses",
     level: "structural",
@@ -255,6 +259,7 @@ const tsconfigParses = {
         })),
     }),
 };
+/** An `extends` specifier that resolves to no file silently drops every option the base file would have set -- tsc itself gives no error until something downstream trips on the missing option. */
 const tsconfigExtendsResolves = {
     id: "tsconfig-extends-resolves",
     level: "structural",
@@ -274,6 +279,7 @@ const tsconfigExtendsResolves = {
         };
     },
 };
+/** The tsconfig `build` compiles must actually set an outDir (or `build` emits .js next to sources) and must not set noEmit -- and if a separate tooling tsconfig sits beside it, that one must set noEmit, or typecheck starts emitting too. */
 const tsconfigEmitCoherence = {
     id: "tsconfig-emit-coherence",
     level: "structural",
@@ -310,6 +316,7 @@ const tsconfigEmitCoherence = {
         return { checked, failures };
     },
 };
+/** A verify step naming a package.json script, a file, or a group that doesn't exist is a wiring defect no offline check other than this one would catch before someone actually runs it. */
 const gateWiring = {
     id: "gate-wiring",
     level: "structural",
@@ -375,6 +382,7 @@ const gateWiring = {
         return { checked, failures };
     },
 };
+/** `.node-version` outside the range package.json's `engines.node` declares means the pinned dev/CI Node isn't even a Node version the project claims to support. */
 const nodePinCoherence = {
     id: "node-pin-coherence",
     level: "structural",
@@ -408,6 +416,7 @@ const nodePinCoherence = {
     },
 };
 // --- rubric rules ----------------------------------------------------------
+/** The strict-family flags are the floor current TypeScript guidance recommends; tsc raises no warning for a flag simply left off, so this is the only check that notices. */
 const strictFlags = {
     id: "strict-flags",
     level: "rubric",
@@ -434,6 +443,7 @@ const strictFlags = {
         return { checked: STRICT_FLAGS.length + 1, failures };
     },
 };
+/** Warns ahead of a TypeScript major that removes an option outright -- by the time tsc itself rejects it, the fix is no longer a choice, it's an emergency. */
 const tsconfigOptionLifecycle = {
     id: "tsconfig-option-lifecycle",
     level: "rubric",
@@ -470,6 +480,7 @@ const tsconfigOptionLifecycle = {
         return { checked: files.length, failures };
     },
 };
+/** An outdated `module`/`moduleResolution`/`target` still compiles fine today, but forgoes current Node/bundler resolution semantics and syntax the project doesn't need to lower. */
 const moduleTargetModern = {
     id: "module-target-modern",
     level: "rubric",
@@ -514,6 +525,7 @@ const moduleTargetModern = {
         return { checked, failures };
     },
 };
+/** ESLint 10 reads only eslint.config.* -- a lingering legacy eslintrc file means either an old ESLint is still in play, or a current one is silently linting nothing. */
 const eslintFlatConfig = {
     id: "eslint-flat-config",
     level: "rubric",
@@ -533,6 +545,7 @@ const eslintFlatConfig = {
         };
     },
 };
+/** Without a type-checked preset and `projectService`, typescript-eslint runs syntax-only rules and silently skips every rule that needs real type information. */
 const eslintTypedLinting = {
     id: "eslint-typed-linting",
     level: "rubric",
@@ -573,6 +586,7 @@ const eslintTypedLinting = {
         return { checked: 2, failures };
     },
 };
+/** `bin/**` and `.claude/hooks/**` are code this project actually runs, not incidental scripts -- if ESLint has no config block for them, or actively ignores src, they ship unlinted. */
 const eslintCoversEmittedCode = {
     id: "eslint-covers-emitted-code",
     level: "rubric",
@@ -611,6 +625,7 @@ const eslintCoversEmittedCode = {
         return { checked, failures };
     },
 };
+/** A coverage threshold without `perFile: true` lets one well-tested file's coverage average out another file with none -- the gate passes while a whole file goes untested. */
 const coverageGate = {
     id: "coverage-gate",
     level: "rubric",
@@ -635,6 +650,7 @@ const coverageGate = {
         return { checked: 2, failures };
     },
 };
+/** An unpinned toolchain package, a missing `packageManager`, or an `@types/node` major that doesn't match the pinned Node version each make installs non-reproducible across machines and CI runs. */
 const toolchainPinShape = {
     id: "toolchain-pin-shape",
     level: "rubric",

package/dist/toolchain/tsconfig-chain.d.ts

@@ -5,6 +5,8 @@ interface ChainFile {
     rel: string;
     /** Why the file could not be used, or `undefined` when it parsed. */
     error: string | undefined;
+    /** True when `error` is a read failure (missing, unreadable, unresolvable, not a regular file) rather than a parse failure. */
+    readFailed: boolean;
     /** This file's own `compilerOptions`, unmerged. */
     options: Record<string, unknown>;
 }

package/dist/toolchain/tsconfig-chain.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Follows one tsconfig's `extends` chain and folds `compilerOptions` the way
  * TypeScript does: array entries (TS 5.0+) left to right, the file's own
@@ -7,20 +9,41 @@
  * Handles a relative target (`x`, `x.json`, `x/tsconfig.json`) and a bare
  * package specifier looked up under every ancestor `node_modules`. A package
  * `exports` map is out of scope -- such a specifier simply stays unresolved.
- * Nothing here throws: a file that cannot be read or parsed is recorded on
- * the chain, and the chain is marked incomplete.
+ * A file that is missing, unreadable (`EACCES`/`EPERM`, including under a
+ * directory this process cannot search), unresolvable (`ELOOP`) or
+ * unparseable is recorded on the chain, and the chain is marked incomplete;
+ * an unreachable `extends` target is followed and recorded as unreadable,
+ * never as missing. Any other failure (`EIO`, `EMFILE`, ...) on the
+ * existence check or the read throws an error naming the path, with the
+ * original as `cause`.
  */
 import { statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { readJsoncFile } from "../jsonc.js";
+import { SurveyReadError, isAbsentError, unresolvableCode, } from "../survey/internal/read-guard.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-function isFile(path) {
+/**
+ * Whether `path` is a candidate `extends` target: a regular file, or
+ * something this process cannot reach (`EACCES`/`EPERM`/`ELOOP`). The latter
+ * is taken as the target so `readJsoncFile` records it as unreadable with
+ * its errno -- never reported "does not exist" for a file that may well be
+ * there. `ENOENT`/`ENOTDIR` is not a candidate; any other errno throws.
+ */
+function isCandidateFile(path) {
+    let stats;
     try {
-        return statSync(path).isFile();
+        stats = statSync(path);
     }
-    catch {
-        return false;
+    catch (error) {
+        if (isAbsentError(error))
+            return false;
+        if (unresolvableCode(error) !== undefined)
+            return true;
+        throw new SurveyReadError(`could not check whether ${path} exists`, {
+            cause: error,
+        });
     }
+    return stats.isFile();
 }
 /** The `extends` value as a list: a string, or TypeScript 5.0+'s array form. */
 function extendsList(value) {
@@ -41,14 +64,14 @@ function resolveExtends(specifier, fromAbs) {
         const base = resolve(dirname(fromAbs), specifier);
         return {
             kind: "relative",
-            abs: candidates(base).find(isFile),
+            abs: candidates(base).find(isCandidateFile),
             attempted: base.endsWith(".json") ? base : `${base}.json`,
         };
     }
     let dir = dirname(fromAbs);
     for (;;) {
         const base = join(dir, "node_modules", specifier);
-        const abs = candidates(base).find(isFile);
+        const abs = candidates(base).find(isCandidateFile);
         if (abs !== undefined)
             return { kind: "package", abs, attempted: base };
         const parent = dirname(dir);
@@ -81,6 +104,7 @@ export function loadTsconfigChain(root, entry) {
                     : read.ok
                         ? "top level is not an object"
                         : read.error,
+                readFailed: !read.ok && read.stage === "read",
                 options: own,
             });
         }

package/dist/toolchain/types.d.ts

@@ -1,23 +1,35 @@
 /**
  * Shapes shared by the toolchain grader. Same two-level model as the harness
- * grader (`../harness/types.ts`): `structural` findings are wiring defects
- * `tsc` and ESLint do not catch and fail a gate; `rubric` findings are the
- * floor official TypeScript / typescript-eslint guidance sets and only ever
- * warn.
+ * grader (`../harness/types.ts`): `structural` findings are pass/fail wiring
+ * defects `tsc` and ESLint do not catch, and fail a gate. `rubric` findings
+ * are quality judgements scored against a checklist rather than pass/fail
+ * wiring checks; that checklist encodes the floor -- the minimum baseline of
+ * practice current official TypeScript / typescript-eslint guidance
+ * recommends -- and a rubric finding only ever warns.
  */
 import type { CheckTally, RuleLevel } from "../harness/types.js";
+/** The toolchain area a rule or finding belongs to (tsconfig, modules, eslint, testing, gates, deps). */
 export type ToolchainCategory = "tsconfig" | "modules" | "eslint" | "testing" | "gates" | "deps";
+/** Every {@link ToolchainCategory}, as an ordered list -- so rubric tallies are iterated in a fixed order. */
 export declare const TOOLCHAIN_CATEGORIES: readonly ToolchainCategory[];
+/** One rule's result against one subject. */
 export interface ToolchainFinding {
+    /** The id of the rule this finding came from. */
     ruleId: string;
+    /** Whether this finding fails the gate (`structural`) or only warns (`rubric`). */
     level: RuleLevel;
+    /** Which toolchain area this finding is about. */
     category: ToolchainCategory;
     /** The file, package, or verify step the finding is about. */
     subject: string;
+    /** Human-readable description of what the rule found. */
     message: string;
 }
+/** The full result of grading one project's toolchain. */
 export interface ToolchainGrade {
+    /** Every finding from every rule, in rule order. */
     findings: ToolchainFinding[];
+    /** The tally of structural checks: how many were checked and how many failed. */
     structural: CheckTally;
     /** Rubric tallies per category -- the absolute-quality measurement. */
     rubric: Record<ToolchainCategory, CheckTally>;

package/dist/toolchain/types.js

@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/** Every {@link ToolchainCategory}, as an ordered list -- so rubric tallies are iterated in a fixed order. */
 export const TOOLCHAIN_CATEGORIES = [
     "tsconfig",
     "modules",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@monte3l/groundwork",
-  "version": "0.1.0-next.1",
-  "description": "Deterministic Phase A bootstrapper: writes the m3l-groundwork baseline (toolchain + Claude Code harness) into a new directory, or surveys an existing project read-only. No prompts, no network beyond the package install.",
+  "version": "1.0.0-rc.3",
+  "description": "CLI that writes a TypeScript toolchain and Claude Code setup into an empty directory, or -- against an existing project -- read-only surveys it and reports the differences. No prompts, and no network access beyond the package install.",
   "keywords": [
     "typescript",
     "claude-code",
@@ -36,7 +36,8 @@
     "!dist/.tsbuildinfo",
     "bin",
     "templates",
-    "plugin"
+    "plugin",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public",