cursedbelt 3.0.2 → 4.1.0

package/scripts/guardrailsEnforce.ts

@@ -147,7 +147,7 @@
 // run, so these stay few and visible. A malformed/unrecognized-category directive is
 // ignored (its violations still fire) and a warning is printed.
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, relative } from "node:path";
 
 const IGNORE_DIR_NAMES = new Set(["node_modules", "dist", "dist-deploy", ".git", "build", "coverage"]);
@@ -179,7 +179,15 @@ interface Rule {
 }
 
 export function walk(dir: string, out: string[] = []): string[] {
-	let entries: ReturnType<typeof readdirSync>;
+	// 🔴 `Dirent[]`, never `ReturnType<typeof readdirSync>`. `readdirSync` is OVERLOADED, and
+	// `ReturnType` of an overloaded function is the LAST overload — which @types/node 24 made
+	// `Dirent<NonSharedBuffer>[]` when `Dirent` became generic, while the call below returns
+	// the string-encoding overload's `Dirent<string>[]`. The annotation was always a guess at
+	// an overload set somebody else maintains; a release reordered it and the guess became
+	// five compile errors that every consumer of `cursedbelt/guardrails` inherited (task 172).
+	// Bare `Dirent` is `Dirent<string>` under >=24's default type argument and is the plain
+	// non-generic class before that, so this spelling is correct on both.
+	let entries: Dirent[];
 	try {
 		entries = readdirSync(dir, { withFileTypes: true });
 	} catch {
@@ -201,13 +209,69 @@ export function walk(dir: string, out: string[] = []): string[] {
 	return out;
 }
 
+/** Index just past the string/template literal opening at `start`. Quoted attribute values
+ *  are skipped so a `//` inside one reads as the URL it is (`src="https://…"`) rather than
+ *  as the start of a comment. `'`/`"` stop at a newline — an unterminated quote must not
+ *  swallow the rest of the file; a backtick may span lines and nests `${…}`. */
+function skipQuoted(source: string, start: number): number {
+	const quote = source[start];
+	let i = start + 1;
+	if (quote !== "`") {
+		while (i < source.length && source[i] !== quote && source[i] !== "\n") {
+			i += source[i] === "\\" ? 2 : 1;
+		}
+		return Math.min(i + 1, source.length);
+	}
+	let depth = 0;
+	while (i < source.length) {
+		if (source[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (depth === 0 && source[i] === "`") return i + 1;
+		if (source.slice(i, i + 2) === "${") {
+			depth++;
+			i += 2;
+			continue;
+		}
+		if (depth > 0 && source[i] === "}") depth--;
+		i++;
+	}
+	return i;
+}
+
 /** Slice from a `<button` (or similar) match to the end of its opening tag, tolerating
- *  `{...}` JS expressions in attribute values that may themselves contain `>`. */
+ *  `{...}` JS expressions in attribute values that may themselves contain `>`
+ *  (`onClick={() => …}`, which works because that `>` sits inside braces).
+ *
+ *  JSX permits line and block comments INSIDE an attribute list, and a comment is prose —
+ *  so it may contain an angle bracket ("a radio-like list rather than a `<select>`").
+ *  Those are skipped the same way `blankComments` skips them, because a `>` written in prose
+ *  used to end the tag here and make every attribute below it invisible — the
+ *  `guardrails-ignore` opt-out included. `blankComments` cannot simply be run first: the
+ *  opt-out checks read this slice and must see the ORIGINAL comment text (see the
+ *  no-raw-action-button check below), so the skip only suppresses TERMINATION; the comment
+ *  stays in what is returned. */
 function extractOpeningTag(source: string, startIndex: number): string {
 	let i = startIndex;
 	let braceDepth = 0;
 	while (i < source.length) {
+		const two = source.slice(i, i + 2);
+		if (two === "//") {
+			const end = source.indexOf("\n", i);
+			i = end === -1 ? source.length : end;
+			continue;
+		}
+		if (two === "/*") {
+			const end = source.indexOf("*/", i + 2);
+			i = end === -1 ? source.length : end + 2;
+			continue;
+		}
 		const ch = source[i];
+		if (ch === '"' || ch === "'" || ch === "`") {
+			i = skipQuoted(source, i);
+			continue;
+		}
 		if (ch === "{") braceDepth++;
 		else if (ch === "}") braceDepth--;
 		else if (ch === ">" && braceDepth <= 0) {

package/scripts/paths.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * `bun run paths` — the generation's whole-tree laws, run over THIS repo's tree.
+ *
+ * {@link TOOLS} is the list: `check-paths.ts` (the one law — exactly one file in a generation
+ * may contain a literal path) and `check-doc-citations.ts` (every `docs/<name>.md` this repo
+ * points a reader at must exist, with the sections it names). Both are generation-scoped rules
+ * a repo proves about ITSELF — rule 3, a repo's gate proves that repo — both are located the
+ * same way, and both have to fail this step rather than be skipped.
+ *
+ * ## 🔴 Why this is a wrapper and not `bun ../../tools/check-paths.ts .`
+ *
+ * That spelling assumes this checkout sits at a fixed depth under the generation root, and a
+ * WORKTREE never does: the working agreement puts worktrees outside every generation by
+ * construction, under the machine-wide worktrees root. Measured 2026-09-17 in a worktree,
+ * with no changes to any script — `error: Module not found "../../tools/check-paths.ts"`,
+ * and the gate stops on its FIRST step. Seventeen packages spelled it that way, and the failure
+ * mode is not the error — it is the workaround: an agent that cannot run its repo's gate moves
+ * back into the shared checkout another agent is holding, or lands without a green gate — and
+ * the second one is invisible afterwards.
+ *
+ * {@link findForgeRoot} walks up for `forge.env`, the same marker `tools/check-paths.ts` and
+ * the runner both use, so the three cannot disagree. {@link viaWorktree} is the worktree case:
+ * a worktree's `.git` is a FILE pointing at the primary checkout's git directory, so the
+ * primary is discoverable with no environment variable and no guess.
+ *
+ * 🔴 **No generation, no pass.** Answering "fine" because the check could not be located is how
+ * a rule stops being enforced without anybody deciding to stop enforcing it — so every failure
+ * to locate exits 1, and says which of the two walks came back empty.
+ *
+ * `tools/check-paths.ts` is what keeps this spelling honest across the roster: a repo whose
+ * `paths` script reaches a tool through a relative `../` module path fails the whole-generation
+ * run, which is the check that this whole file is the fix for.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The generation's tools this repo runs over its own tree, in the order they should fail. */
+const TOOLS = ["check-paths.ts", "check-doc-citations.ts"];
+
+/** How far up either walk looks before giving up — a bound, so a misuse is `null` in ms. */
+const MAX_HOPS = 16;
+
+/** Walk up from `from` for a directory containing `marker`, or `null`. */
+function walkUp(from: string, marker: string): string | null {
+	let dir = resolve(from);
+	for (let hops = 0; hops < MAX_HOPS; hops++) {
+		if (existsSync(join(dir, marker))) return dir;
+		const up = dirname(dir);
+		if (up === dir) return null;
+		dir = up;
+	}
+	return null;
+}
+
+/** The directory holding `forge.env` above `from`, or `null` when that is not inside a generation. */
+function findForgeRoot(from: string): string | null {
+	return walkUp(from, "forge.env");
+}
+
+/** The generation above the checkout this WORKTREE was cut from, or `null` on anything unexpected. */
+function viaWorktree(from: string): string | null {
+	try {
+		const git = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+			cwd: from,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (git.status !== 0) return null;
+		const gitDir = (git.stdout ?? "").trim();
+		if (!gitDir || !gitDir.startsWith("/")) return null;
+		// `<primary>/.git` → `<primary>`, then the ordinary walk up.
+		return findForgeRoot(dirname(gitDir));
+	} catch {
+		return null;
+	}
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+/** This checkout — the nearest ancestor holding a `package.json`, so it is right in a worktree. */
+const repo = walkUp(here, "package.json");
+const root = findForgeRoot(here) ?? viaWorktree(here);
+
+if (!repo) {
+	console.error(`✗ no package.json above ${here}, so there is no repo to check.`);
+	process.exit(1);
+}
+if (!root) {
+	console.error("✗ this checkout is not inside a generation and is not a worktree of one, so");
+	console.error(`  tools/{${TOOLS.join(",")}} cannot be located. Run it from a checkout under a`);
+	console.error("  generation, or from a worktree cut from one — a skipped check is not a passed one.");
+	process.exit(1);
+}
+
+for (const name of TOOLS) {
+	const tool = join(root, "tools", name);
+	if (!existsSync(tool)) {
+		console.error(`✗ ${tool} does not exist. The generation at ${root} has no ${name},`);
+		console.error("  so this repo cannot prove it obeys that law. That is a failure, not a skip.");
+		process.exit(1);
+	}
+	const result = spawnSync("bun", [tool, repo, ...process.argv.slice(2)], { stdio: "inherit" });
+	if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
+}