@antelopejs/tooling-configs 0.0.8 → 0.2.0

package/dist/bin/sync.mjs

@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+import { a as formatCeilings, t as CEILINGS_FILE } from "../ceilings--pJmhSde.mjs";
+import { a as repositoryRoot, o as runCli } from "../files-BSl0U8lT.mjs";
+import { a as repositoryTools, i as parseManifest, n as managedPackage, o as toolingVersions, r as packageManager, t as execCommand } from "../package-B1aipTbn.mjs";
+import { t as measureBaseline } from "../ratchet-DNsVZH9s.mjs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { isMap, isScalar, isSeq, parseDocument } from "yaml";
+//#region src/guardrails/agents-block.ts
+const AGENTS_BLOCK_START = "<!-- antelopejs-guardrails:start -->";
+const AGENTS_BLOCK_END = "<!-- antelopejs-guardrails:end -->";
+const COMMENTS = `### Comments
+
+Say it in code. A constraint belongs in a type, a lint rule, or a test. A public item's contract belongs in TSDoc (\`/** */\`) on that item. The only other comments are lint directives that name their rules, \`@ts-expect-error <reason>\`, \`SAFETY: <reason>\` above a type assertion, \`/*!\` license headers, and bundler or formatter directives.`;
+const TESTS = `### Tests
+
+Hold every test you write or keep to this checklist:
+
+- Name the wrong implementation this test fails on. A test with no answer is deleted, not kept.
+- No test reads the file it tests. Drive the behaviour through the public interface.
+- An invariant over many files is a lint rule, not a test.`;
+const SHARED_RULES = [
+	["Formatting", "oxfmt"],
+	["Lint findings are errors; no rule warns", "oxlint preset"],
+	["Comments are TSDoc, directives, or `SAFETY:` only", "`antelopejs/no-comments`"],
+	["Every test asserts", "`antelopejs/require-assertion`"],
+	["Tests read no files outside fixtures, helpers, locales", "`antelopejs/no-fs-read-in-tests`"],
+	["No assertion that restates a constant", "`antelopejs/no-constant-value-assertion`"],
+	["No test whose only check is \"is a function\"", "`antelopejs/no-typeof-function-only-test`"],
+	["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"]
+];
+const FULL_RULES = [
+	["Files ≤ 20,000 bytes, tests included", "`antelopejs-check-size` (pre-commit)"],
+	["Existing debt only shrinks", "`antelopejs-ratchet`"],
+	["Types check", "`tsc` (pre-push)"],
+	["No dead files, exports, or dependencies", "knip"],
+	["Managed files match the pack", "`antelopejs-sync --check`"],
+	["A test names the wrong implementation it catches", "review; no tool"]
+];
+/** Pads each column the way oxfmt does, so formatting AGENTS.md never reports sync drift. */
+function ruleTable(rows) {
+	const table = [["Rule", "Enforced by"], ...rows];
+	const widths = [0, 1].map((column) => Math.max(...table.map((row) => row[column].length)));
+	const line = (cells) => `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(" | ")} |`;
+	const [header, ...body] = table.map(line);
+	return [
+		"### What enforces what",
+		"",
+		header,
+		line(widths.map((width) => "-".repeat(width))),
+		...body
+	].join("\n");
+}
+function pointers(context) {
+	const lines = [];
+	if (context.verificationSkill !== void 0) lines.push(`Prove a change works with the verification skill in [\`${context.verificationSkill}\`](${context.verificationSkill}) before you call it done.`);
+	if (context.glossary !== void 0) lines.push(`Name things with the terms in [\`${context.glossary}\`](${context.glossary}).`);
+	return lines;
+}
+function fullBody(context) {
+	return [
+		"## Guardrails",
+		"",
+		"Finish every change with `pnpm run checks`. It runs typecheck, lint, format, knip, tests, size, ratchet, and sync, and prints only what failed. The change is done when it prints no failure.",
+		"",
+		...pointers(context).flatMap((line) => [line, ""]),
+		"The tools enforce most rules, listed in the table at the end. The sections below hold the rules no tool checks.",
+		"",
+		COMMENTS,
+		"",
+		TESTS,
+		"",
+		"### Debt",
+		"",
+		"`guardrails.ratchet.json` records the lint findings and oversize files this repository already had. Its numbers only go down. After you remove debt, run `pnpm run ratchet:update` and commit the lowered file. A rule listed there is off for `oxlint`. The ratchet counts it instead, and the pre-commit hook rejects it on every line you add.",
+		"",
+		ruleTable([...SHARED_RULES, ...FULL_RULES])
+	];
+}
+function templateBody(context) {
+	return [
+		"## Guardrails",
+		"",
+		"Lint with `oxlint` and format with `oxfmt`; both read the configs at the repository root. Fix every finding: no rule warns.",
+		"",
+		...pointers(context).flatMap((line) => [line, ""]),
+		COMMENTS,
+		"",
+		TESTS,
+		"",
+		ruleTable(SHARED_RULES)
+	];
+}
+/** The managed block, markers included, ending with a newline. */
+function agentsBlock(context) {
+	const body = context.profile === "full" ? fullBody(context) : templateBody(context);
+	return [
+		AGENTS_BLOCK_START,
+		"<!-- Managed by @antelopejs/tooling-configs. `antelopejs-sync` rewrites everything between these markers; write repository-specific guidance outside them. -->",
+		"",
+		...body,
+		"",
+		AGENTS_BLOCK_END,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/guardrails/templates.ts
+const PRESET_CONFIGS = [
+	{
+		path: "oxlint.config.ts",
+		legacy: [".oxlintrc.json"],
+		specifier: "@antelopejs/tooling-configs/oxc/lint",
+		content: "import { defineConfig } from \"oxlint\";\nimport { antelopePreset } from \"@antelopejs/tooling-configs/oxc/lint\";\n\nexport default defineConfig({\n  extends: [antelopePreset()],\n  options: { typeAware: true },\n});\n"
+	},
+	{
+		path: "oxfmt.config.ts",
+		legacy: [".oxfmtrc.json"],
+		specifier: "@antelopejs/tooling-configs/oxc/fmt",
+		content: "import { antelopeFmtPreset } from \"@antelopejs/tooling-configs/oxc/fmt\";\n\nexport default antelopeFmtPreset();\n"
+	},
+	{
+		path: "knip.config.ts",
+		legacy: [
+			"knip.json",
+			"knip.jsonc",
+			".knip.json"
+		],
+		specifier: "@antelopejs/tooling-configs/knip",
+		content: "import { antelopeKnipConfig } from \"@antelopejs/tooling-configs/knip\";\n\nexport default antelopeKnipConfig();\n"
+	}
+];
+function presetConfig(current, preset, tools) {
+	const target = tools.presets[preset.path];
+	const specifier = target.replaceAll("/", "\\/").replaceAll(".", "\\.");
+	const imported = new RegExp(`(?:\\bfrom\\s*|\\bimport\\s*\\(?\\s*)["']${specifier}["']`);
+	if (current === void 0) return preset.content.replace(preset.specifier, target);
+	if (imported.test(current)) return current;
+	const importLine = preset.content.split("\n").filter((line) => line.includes(preset.specifier)).join("\n").replace(preset.specifier, target);
+	throw new Error(`${preset.path} does not import its preset. Add \`${importLine}\` and extend that preset, then rerun antelopejs-sync. The file was not replaced.`);
+}
+function lefthook(current, manager, tools) {
+	const exec = execCommand(manager);
+	const document = parseDocument(current ?? "{}\n");
+	if (document.errors.length) throw new Error(`lefthook.yml: ${document.errors.map(({ message }) => message).join("; ")}`);
+	if (!isMap(document.contents)) throw new Error("lefthook.yml must contain a YAML mapping. Merge the guardrail hooks manually and rerun antelopejs-sync.");
+	if (current === void 0) document.contents.flow = false;
+	const glob = "*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}";
+	const hooks = {
+		"pre-commit": {
+			"antelopejs-format": {
+				run: `${exec} oxfmt --no-error-on-unmatched-pattern {staged_files}`,
+				stage_fixed: true
+			},
+			"antelopejs-lint": {
+				glob,
+				run: `${exec} oxlint --no-error-on-unmatched-pattern {staged_files}`
+			},
+			"antelopejs-size": { run: `${tools.hookPrefix}${tools.commands.size} --staged {staged_files}` },
+			"antelopejs-ratchet": {
+				glob,
+				run: `${tools.hookPrefix}${tools.commands.ratchet} --staged {staged_files}`
+			}
+		},
+		"pre-push": { "antelopejs-typecheck": { run: `${manager} run typecheck` } }
+	};
+	for (const [hook, commands] of Object.entries(hooks)) {
+		for (const path of [[hook], [hook, "commands"]]) {
+			if (!document.hasIn(path)) document.setIn(path, document.createNode({}));
+			if (!isMap(document.getIn(path))) throw new Error(`lefthook.yml: ${path.join(".")} must be a mapping. Preserve the existing hook and merge its commands before rerunning antelopejs-sync.`);
+		}
+		for (const [key, command] of Object.entries(commands)) document.setIn([
+			hook,
+			"commands",
+			key
+		], document.createNode(command));
+	}
+	return document.toString({ lineWidth: 0 });
+}
+const SETUP_SCRIPT = `#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$BASH_SOURCE")/.."
+export CI=1 COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+major="$(tr -d 'v[:space:]' < .nvmrc)"
+if [[ "$(node -p 'process.versions.node.split(".")[0]')" != "$major" ]]; then
+  if command -v fnm >/dev/null 2>&1; then
+    eval "$(fnm env --shell bash)"
+    fnm install "$major"
+    fnm use "$major"
+  else
+    export NVM_DIR="\${NVM_DIR:-$HOME/.nvm}"
+    if [[ ! -s "$NVM_DIR/nvm.sh" ]]; then
+      git clone --quiet --depth 1 --branch v0.40.3 https://github.com/nvm-sh/nvm.git "$NVM_DIR"
+    fi
+    source "$NVM_DIR/nvm.sh" --no-use
+    nvm install "$major"
+    nvm use "$major"
+  fi
+fi
+pin="$(node -p 'JSON.parse(require("node:fs").readFileSync("package.json", "utf8")).packageManager || "pnpm"')"
+manager="\${pin%%@*}"
+corepack enable
+if [[ "$pin" == *@* ]]; then
+  corepack prepare "$pin" --activate
+fi
+case "$manager" in
+  pnpm) pnpm install --frozen-lockfile ;;
+  yarn) YARN_ENABLE_IMMUTABLE_INSTALLS=true yarn install --frozen-lockfile ;;
+  npm) npm ci ;;
+  bun) bun install --frozen-lockfile ;;
+  *) printf 'Unsupported package manager %s\\n' "$manager" >&2; exit 1 ;;
+esac
+`;
+//#endregion
+//#region src/guardrails/workflow.ts
+const MISSING_CHECKS_WORKFLOW = "No workflow in .github/workflows runs pnpm run checks. Add a step running `pnpm run checks` (or `pnpm checks`), or a job using AntelopeJS/.github/.github/workflows/ci-node.yml@<ref>.";
+function hasChecksWorkflow(root) {
+	const directory = join(root, ".github/workflows");
+	if (!existsSync(directory)) return false;
+	for (const file of readdirSync(directory).filter((name) => /\.ya?ml$/.test(name))) {
+		const document = parseDocument(readFileSync(join(directory, file), "utf8"));
+		if (document.errors.length) continue;
+		const jobs = document.get("jobs", true);
+		if (!isMap(jobs)) continue;
+		for (const { value: job } of jobs.items) {
+			if (!isMap(job)) continue;
+			const uses = job.get("uses", true);
+			if (isScalar(uses) && /^AntelopeJS\/\.github\/\.github\/workflows\/ci-node\.yml@\S+$/.test(String(uses.value))) return true;
+			const steps = job.get("steps", true);
+			if (!isSeq(steps)) continue;
+			for (const step of steps.items) {
+				if (!isMap(step)) continue;
+				const run = step.get("run", true);
+				if (isScalar(run) && /(?:^|\n|&&|;)\s*pnpm\s+(?:run\s+)?checks(?=\s*(?:$|\n|&&|;|#))/.test(String(run.value))) return true;
+			}
+		}
+	}
+	return false;
+}
+//#endregion
+//#region src/guardrails/sync.ts
+const LEGACY_COMMENT_INSTRUCTION = "- Explain non-obvious constraints and decisions in comments; avoid restating the code. Document public contracts with TSDoc.";
+function managedAgents(current = "", context) {
+	const start = current.indexOf(AGENTS_BLOCK_START);
+	const end = current.indexOf(AGENTS_BLOCK_END);
+	if (start === -1 !== (end === -1) || end < start) throw new Error("AGENTS.md has incomplete guardrails markers. Repair the markers before syncing.");
+	const notes = [];
+	const clean = (text) => text.split("\n").filter((line) => {
+		if (line.replace(/\r$/, "") !== LEGACY_COMMENT_INSTRUCTION) return true;
+		notes.push("Removed the legacy comment instruction from AGENTS.md's hand-written part.");
+		return false;
+	}).join("\n");
+	let before = clean(start === -1 ? current : current.slice(0, start));
+	const after = start === -1 ? "" : clean(current.slice(end + 34));
+	if (context.claude) before = `${before.trimEnd()}${before.trim() ? "\n\n" : ""}${clean(context.claude).trimEnd()}\n\n`;
+	const block = agentsBlock(context);
+	return {
+		content: start === -1 ? `${before}${before && !before.endsWith("\n") ? "\n" : ""}${before && !before.endsWith("\n\n") ? "\n" : ""}${block}` : `${before}${block.trimEnd()}${after}`,
+		notes
+	};
+}
+const MANAGED_ARTIFACTS = [
+	...PRESET_CONFIGS.map((preset) => ({
+		path: preset.path,
+		profiles: ["full", "template"],
+		desired: (current, context) => ({
+			content: presetConfig(current, preset, context.tools),
+			notes: []
+		})
+	})),
+	{
+		path: "lefthook.yml",
+		profiles: ["full"],
+		desired: (current, context) => ({
+			content: lefthook(current, context.manager, context.tools),
+			notes: []
+		})
+	},
+	{
+		path: "package.json",
+		profiles: ["full"],
+		desired: (current, context) => ({
+			content: managedPackage(current, context.versions, context),
+			notes: []
+		})
+	},
+	{
+		path: ".nvmrc",
+		profiles: ["full"],
+		desired: () => ({
+			content: "24\n",
+			notes: []
+		})
+	},
+	{
+		path: ".agents/setup",
+		profiles: ["full"],
+		desired: () => ({
+			content: SETUP_SCRIPT,
+			notes: []
+		}),
+		mode: 493
+	},
+	{
+		path: "AGENTS.md",
+		profiles: ["full", "template"],
+		desired: managedAgents
+	},
+	{
+		path: "CLAUDE.md",
+		profiles: ["full"],
+		desired: (_current, context) => ({
+			content: "@AGENTS.md\n",
+			notes: context.claude ? ["Moved CLAUDE.md content into AGENTS.md's hand-written part before the managed block."] : []
+		})
+	},
+	{
+		path: CEILINGS_FILE,
+		profiles: ["full"],
+		desired: (current, context) => ({
+			content: current ?? context.baseline,
+			notes: []
+		})
+	}
+];
+function planSync(current, modes, context) {
+	const plan = [];
+	for (const preset of PRESET_CONFIGS) for (const file of preset.legacy) if (current.has(file)) plan.push({
+		kind: "error",
+		path: file,
+		message: `${file}: move its settings into ${preset.path} extending "${context.tools.presets[preset.path]}". Delete ${file}, then rerun antelopejs-sync.`
+	});
+	for (const artifact of MANAGED_ARTIFACTS) {
+		if (!artifact.profiles.includes(context.profile)) continue;
+		try {
+			const { content, notes } = artifact.desired(current.get(artifact.path), context);
+			const changed = current.get(artifact.path) !== content || artifact.mode !== void 0 && (artifact.mode & 73) !== 0 && ((modes.get(artifact.path) ?? 0) & 73) === 0;
+			if (notes.length) plan.push({
+				kind: "migrated",
+				path: artifact.path,
+				content,
+				mode: artifact.mode,
+				notes
+			});
+			else if (changed) plan.push({
+				kind: "write",
+				path: artifact.path,
+				content,
+				mode: artifact.mode
+			});
+			else plan.push({
+				kind: "unchanged",
+				path: artifact.path
+			});
+		} catch (error) {
+			plan.push({
+				kind: "error",
+				path: artifact.path,
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	return plan;
+}
+function verificationSkill(root) {
+	for (const directory of [
+		".agents/skills",
+		".claude/skills",
+		"skills"
+	]) {
+		if (!existsSync(join(root, directory))) continue;
+		for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+			const path = `${directory}/${entry.name}/SKILL.md`;
+			if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && existsSync(join(root, path))) return path;
+		}
+	}
+}
+function repositorySnapshot(root) {
+	const current = /* @__PURE__ */ new Map();
+	const modes = /* @__PURE__ */ new Map();
+	for (const file of [...MANAGED_ARTIFACTS.map(({ path }) => path), ...PRESET_CONFIGS.flatMap(({ legacy }) => legacy)]) {
+		const path = join(root, file);
+		if (existsSync(path)) {
+			current.set(file, readFileSync(path, "utf8"));
+			modes.set(file, statSync(path).mode & 511);
+		}
+	}
+	return {
+		current,
+		modes
+	};
+}
+function linksTo(root, link, target) {
+	const path = join(root, link);
+	return lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink() === true && resolve(root, readlinkSync(path)) === join(root, target);
+}
+function claudeProse(root, current) {
+	if (linksTo(root, "CLAUDE.md", "AGENTS.md") || linksTo(root, "AGENTS.md", "CLAUDE.md")) return "";
+	const claude = current.get("CLAUDE.md")?.trim() ?? "";
+	if (!claude.includes("\n") && /^(?:@?(?:\.\/)?AGENTS\.md|(?:See |Refer to )?\[AGENTS\.md\]\((?:\.\/)?AGENTS\.md\)(?: for .*)?\.?)$/i.test(claude)) return "";
+	return claude;
+}
+function repositoryContext(root, current, profile) {
+	const manifest = parseManifest(current.get("package.json") ?? "{}");
+	const lint = PRESET_CONFIGS[0];
+	const desiredLint = current.get(lint.path) ?? lint.content;
+	return {
+		profile,
+		manager: packageManager(manifest),
+		versions: toolingVersions(),
+		tools: repositoryTools(manifest),
+		typeAware: /\btypeAware["']?\s*:\s*true\b/.test(desiredLint),
+		nuxt: Boolean(manifest.dependencies?.nuxt || manifest.devDependencies?.nuxt || readdirSync(root).some((name) => name.startsWith("nuxt.config."))),
+		claude: profile === "full" ? claudeProse(root, current) : "",
+		baseline: "",
+		verificationSkill: verificationSkill(root),
+		glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file)))
+	};
+}
+function writeArtifacts(root, artifacts) {
+	for (const artifact of artifacts) {
+		const path = join(root, artifact.path);
+		mkdirSync(dirname(path), { recursive: true });
+		if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()) unlinkSync(path);
+		writeFileSync(path, artifact.content);
+		if (artifact.mode !== void 0) chmodSync(path, artifact.mode);
+	}
+}
+function syncRepository(root, options = {}) {
+	const profile = options.profile ?? "full";
+	const { current, modes } = repositorySnapshot(root);
+	const manifest = parseManifest(current.get("package.json") ?? "{}");
+	const context = repositoryContext(root, current, profile);
+	let plan = planSync(current, modes, context);
+	const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
+	const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
+	if (profile === "full" && !hasChecksWorkflow(root)) {
+		if (options.check) errors.push(MISSING_CHECKS_WORKFLOW);
+		else notes.push(MISSING_CHECKS_WORKFLOW);
+	}
+	if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json")) {
+		const lint = PRESET_CONFIGS[0];
+		const desired = presetConfig(current.get(lint.path), lint, context.tools);
+		context.baseline = formatCeilings(measureBaseline(root, desired === current.get(lint.path) ? void 0 : desired));
+		plan = planSync(current, modes, context);
+	}
+	const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
+	if (!options.check && !errors.length) writeArtifacts(root, writes);
+	const requiredDependencies = ["lefthook", "knip"];
+	if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
+	const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
+	return {
+		artifacts: plan,
+		paths: errors.length ? [] : writes.map(({ path }) => path),
+		errors,
+		notes,
+		dependenciesAdded
+	};
+}
+//#endregion
+//#region src/bin/sync.ts
+runCli(() => {
+	const { values } = parseArgs({ options: {
+		check: { type: "boolean" },
+		profile: {
+			type: "string",
+			default: "full"
+		}
+	} });
+	if (values.profile !== "full" && values.profile !== "template") throw new Error("--profile must be full or template.");
+	const result = syncRepository(repositoryRoot(), {
+		check: values.check,
+		profile: values.profile
+	});
+	for (const note of result.notes) process.stdout.write(`Note: ${values.check || result.errors.length ? "Planned migration. " : ""}${note}\n`);
+	for (const error of result.errors) process.stderr.write(`${error}\n`);
+	if (result.errors.length) return 1;
+	for (const path of result.paths) process.stdout.write(`${values.check ? "Drift" : "Updated"}: ${path}${values.check ? "; run antelopejs-sync" : ""}\n`);
+	if (!result.paths.length) process.stdout.write("Guardrails are in sync.\n");
+	if (!values.check && result.dependenciesAdded) process.stdout.write("Added devDependencies. Run install with your package manager before using the hooks or checks.\n");
+	return values.check && result.paths.length ? 1 : 0;
+});
+//#endregion
+export {};

package/dist/ceilings--pJmhSde.mjs

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+//#region src/guardrails/ceilings.ts
+/** The per-repository ratchet file, at the repository root. */
+const CEILINGS_FILE = "guardrails.ratchet.json";
+/**
+* Set by the ratchet when it measures: the oxlint preset then ignores the
+* ceilings and reports every rule, so the counts include the existing debt.
+*/
+const MEASURE_ENV = "ANTELOPEJS_RATCHET_MEASURE";
+/** Largest authored file, in bytes, tests included. */
+const MAX_FILE_BYTES = 2e4;
+const EMPTY_CEILINGS = {
+	rules: {},
+	oversizeFiles: {}
+};
+/** Finds the nearest git directory or worktree marker, falling back to cwd outside git. */
+function findGitRoot(cwd = process.cwd()) {
+	let directory = resolve(cwd);
+	while (!existsSync(join(directory, ".git"))) {
+		const parent = dirname(directory);
+		if (parent === directory) return resolve(cwd);
+		directory = parent;
+	}
+	return directory;
+}
+/** Reads the ceilings at `root`; a repository without the file has no debt. */
+function readCeilings(root) {
+	const path = join(root, CEILINGS_FILE);
+	if (!existsSync(path)) return EMPTY_CEILINGS;
+	return parseCeilings(readFileSync(path, "utf8"), path);
+}
+/** Parses the ceilings file, rejecting anything but non-negative integer counts. */
+function parseCeilings(text, source) {
+	const parsed = JSON.parse(text);
+	if (parsed === null || Array.isArray(parsed)) throw new Error(`${source}: expected an object with "rules" and "oversizeFiles"`);
+	return {
+		rules: parseCounts(parsed.rules, `${source}: rules`),
+		oversizeFiles: parseCounts(parsed.oversizeFiles, `${source}: oversizeFiles`)
+	};
+}
+function parseCounts(value, source) {
+	if (value === void 0) return {};
+	if (value === null || Array.isArray(value)) throw new Error(`${source}: expected an object of counts`);
+	const counts = {};
+	for (const [key, count] of Object.entries(value)) {
+		if (!Number.isInteger(count) || count < 0) throw new Error(`${source}: "${key}" must be a non-negative integer`);
+		counts[key] = count;
+	}
+	return counts;
+}
+function sortedCounts(counts) {
+	return Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)));
+}
+/** Serializes ceilings with sorted keys, so rewriting an unchanged file is a no-op. */
+function formatCeilings(ceilings) {
+	const sorted = {
+		rules: sortedCounts(ceilings.rules),
+		oversizeFiles: sortedCounts(ceilings.oversizeFiles)
+	};
+	return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+//#endregion
+export { formatCeilings as a, findGitRoot as i, MAX_FILE_BYTES as n, readCeilings as o, MEASURE_ENV as r, CEILINGS_FILE as t };

package/dist/eslint.mjs

@@ -10,13 +10,18 @@ import { createConfigForNuxt } from "@nuxt/eslint-config/flat";
 * layers carry today) would fight it on every save.
 */
 const ANTELOPE_NUXT_RULES = {
+	/** Import order follows side-effectful setup and belongs to the formatter. */
 	"import/first": "off",
 	"import/order": "off",
+	/** Single-word pages are intentional; withDefaults supplies prop defaults. */
 	"vue/multi-word-component-names": "off",
 	"vue/require-default-prop": "off",
+	/** CMS blocks and forms require structural types in the interface layer. */
 	"@typescript-eslint/no-explicit-any": "off",
 	"@typescript-eslint/no-empty-object-type": "off",
+	/** Separate event signatures preserve their documentation. */
 	"@typescript-eslint/unified-signatures": "off",
+	/** Underscores mark intentionally unused bindings. */
 	"@typescript-eslint/no-unused-vars": ["error", {
 		argsIgnorePattern: "^_",
 		varsIgnorePattern: "^_",
@@ -35,13 +40,28 @@ const ANTELOPE_NUXT_RULES = {
 * ```
 */
 function antelopeNuxtConfig(options = {}) {
+	const overrides = {
+		...ANTELOPE_NUXT_RULES,
+		...options.rules
+	};
 	return createConfigForNuxt({
 		features: { tooling: true },
 		dirs: { src: options.dirs ?? [] }
-	}).overrideRules({
-		...ANTELOPE_NUXT_RULES,
-		...options.rules
-	});
+	}).onResolved((configs) => configs.map((config) => {
+		if (config.rules === void 0) return config;
+		const rules = { ...config.rules };
+		for (const [name, original] of Object.entries(rules)) {
+			const rule = overrides[name] === void 0 ? original : overrides[name];
+			if (rule === null) delete rules[name];
+			else if (rule === "warn" || rule === 1) rules[name] = "error";
+			else if (Array.isArray(rule) && (rule[0] === "warn" || rule[0] === 1)) rules[name] = ["error", ...rule.slice(1)];
+			else rules[name] = rule;
+		}
+		return {
+			...config,
+			rules
+		};
+	}));
 }
 //#endregion
 export { ANTELOPE_NUXT_RULES, antelopeNuxtConfig };