cursedops 0.3.0 → 0.4.0

package/README.md

@@ -14,6 +14,7 @@ bun add cursedops
 | `cursedops/serve` | the static tier's four helpers — the path-traversal guard, the MIME table, the hashed-asset test, the crash handlers |
 | `cursedops/api-floor` | the rule that an unmatched `/api/...` is a phrase and never the app shell — the namespace predicates, the trailing-slash normaliser and the default 404 body. No `node:` import, so it mounts inside a Worker |
 | `cursedops/build-info` | which commit a checkout-served process is running and whether its tree was dirty — read once at load, and a `null` retried in the background rather than cached for the life of the process. `node:child_process`, so never in a Worker |
+| `cursedops/bound-lists` | the static check that no SQL builds an `IN (…)` list one `?` per value — the shape D1 500s on past 100 ids. Test-time only; the recorded third exception, see below |
 | `cursedops/public-surface` | the ratchet on a LIBRARY's public surface — a symbol count per export subpath against a committed baseline that may only fall — and its `public-surface` bin. Not an app's: the one entry here admitted for three published libraries, see below |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
@@ -71,6 +72,15 @@ adoption all three measured **identical per-subpath counts** to their own copies
 (`cwip` 60 subpaths/2,089 symbols, `cursedbelt` 51/1,837, `cursedbelt-server` 34/992) —
 a consolidation that moves a count has changed the measurement, not the plumbing.
 
+🔴 **`bound-lists` is the third recorded exception, admitted by rule 3 at three consumers.**
+It was written once, by `collections` (`src/server/boundLists.test.ts`, 2026-09-22), after
+the shape it refuses drew an empty gallery for every folder over 100 files on D1. The same
+day `music` was found carrying 24 sites and `vault` four — the identical trap in two more D1
+Workers — so the choice was two more copies of the scanner or one here. Copies are what
+`check-copies` exists to refuse, and a forked scanner is a check that quietly stops matching.
+It is mechanism only: each app passes its own root and directories and keeps its own
+"not vacuous" assertion about which files the scan must reach.
+
 ### What was deliberately left in the apps
 
 The comparison that produced this library found three areas that are genuinely

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedops",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard among them — and the API floor that keeps an unmatched /api/... from ever being answered with the app shell — the commit and dirty flag a checkout-served process reports, retried rather than cached when git loses a boot race — and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
 	"type": "module",
 	"scripts": {
@@ -42,6 +42,12 @@
 			"source": "./src/smoke.ts",
 			"import": "./src/smoke.ts"
 		},
+		"./bound-lists": {
+			"types": "./src/boundLists.ts",
+			"bun": "./src/boundLists.ts",
+			"source": "./src/boundLists.ts",
+			"import": "./src/boundLists.ts"
+		},
 		"./build-info": {
 			"types": "./src/buildInfo.ts",
 			"bun": "./src/buildInfo.ts",

package/src/boundLists.ts

@@ -0,0 +1,86 @@
+/**
+ * 🔴 No SQL builds a parameter list one `?` per value.
+ *
+ * `IN (${ids.map(() => "?").join(", ")})` is green on every fixture and a 500 on D1 the moment
+ * the list passes 100 — the cap is per statement, and every other parameter in the statement
+ * shares it. Measured 2026-09-22 in `collections`: about twenty call sites had the shape, and
+ * the first one found drew an empty gallery for every folder of more than 100 files. The same
+ * day `music` was found carrying 24 of them and `vault` four, which is what put the scanner
+ * here instead of in a third copy.
+ *
+ * The fix everywhere is `inArray` from `cursedbelt-server/d1`: the whole list as ONE JSON
+ * parameter through `json_each`, whatever its length. This proves the shape cannot come back
+ * in a line no test happens to drive.
+ *
+ * A line that genuinely needs one `?` per value — a fixed, known-small arity, like a multi-row
+ * VALUES list already sized by `chunkForBind` — carries `bound-list:ok <why>` on the same line
+ * or the one above. The reason is the point: an excuse that does not say why the list is
+ * bounded is the bug, filed under a comment.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export interface BoundListFinding {
+	file: string;
+	line: number;
+	shape: string;
+	text: string;
+}
+
+const SHAPES: { name: string; pattern: RegExp }[] = [
+	{ name: "an IN list interpolated into SQL", pattern: /\bIN\s*\(\s*\$\{/i },
+	{ name: "one placeholder generated per value", pattern: /=>\s*(["'`])\?\1/ },
+];
+const EXCUSE = /bound-list:ok\s+\S/;
+
+/** The scan, over one file's text. */
+export function scanBoundLists(file: string, source: string): BoundListFinding[] {
+	const lines = source.split("\n");
+	const out: BoundListFinding[] = [];
+	lines.forEach((text, index) => {
+		const trimmed = text.trim();
+		// A comment that QUOTES the shape is documentation of the trap, not the trap.
+		if (trimmed.startsWith("*") || trimmed.startsWith("//") || trimmed.startsWith("/*")) return;
+		for (const { name, pattern } of SHAPES) {
+			if (!pattern.test(text)) continue;
+			if (EXCUSE.test(text) || EXCUSE.test(lines[index - 1] ?? "")) continue;
+			out.push({ file, line: index + 1, shape: name, text: trimmed });
+		}
+	});
+	return out;
+}
+
+function sources(dir: string): string[] {
+	const out: string[] = [];
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) {
+			if (name !== "node_modules") out.push(...sources(path));
+		} else if (/\.tsx?$/.test(name) && !/\.(test|spec)\.tsx?$/.test(name)) out.push(path);
+	}
+	return out;
+}
+
+/**
+ * Scan every non-test `.ts`/`.tsx` file under `dirs` (relative to `root`). `scanned` is
+ * returned so the caller can prove the scan is not vacuous — assert it contains the files
+ * that held the shape when the check was adopted.
+ */
+export function boundListFindings(
+	root: string,
+	dirs: readonly string[],
+): { scanned: string[]; findings: BoundListFinding[] } {
+	const files = dirs.flatMap((dir) => sources(join(root, dir)));
+	return {
+		scanned: files.map((file) => relative(root, file)),
+		findings: files.flatMap((file) => scanBoundLists(relative(root, file), readFileSync(file, "utf8"))),
+	};
+}
+
+/** One line per finding, the form an `expect(...).toEqual([])` prints usefully. */
+export const describeFindings = (findings: readonly BoundListFinding[]): string[] =>
+	findings.map((f) => `${f.file}:${f.line} — ${f.shape}: ${f.text}`);
+
+/** The message to hang on that `expect`. */
+export const BOUND_LIST_ADVICE =
+	"use `inArray` from cursedbelt-server/d1, or excuse the line with `bound-list:ok <why it is bounded>`";