@noctcore/lint-meta-rules 0.1.0

package/dist/index.cjs

@@ -0,0 +1,748 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RULE_FACTORIES: () => RULE_FACTORIES,
+  RULE_IDS: () => RULE_IDS,
+  countLines: () => countLines,
+  createAgentsDocPresenceRule: () => createAgentsDocPresenceRule,
+  createAllRules: () => createAllRules,
+  createCanonicalHelpersSingleHomeRule: () => createCanonicalHelpersSingleHomeRule,
+  createFileSizeRatchetRule: () => createFileSizeRatchetRule,
+  createLayerRankRule: () => createLayerRankRule,
+  createNoClonedComponentFoldersRule: () => createNoClonedComponentFoldersRule,
+  createNoWarnSeverityRule: () => createNoWarnSeverityRule,
+  createPackageShapeRule: () => createPackageShapeRule,
+  createTestRunnerSegregationRule: () => createTestRunnerSegregationRule,
+  createTestSiblingEnforcementRule: () => createTestSiblingEnforcementRule,
+  createTestWorkspaceEnrollmentRule: () => createTestWorkspaceEnrollmentRule,
+  createUiPrimitiveShapeRule: () => createUiPrimitiveShapeRule,
+  createWorkspaceGraphParityRule: () => createWorkspaceGraphParityRule
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rules/shared.ts
+function dirOf(rel, basename = "package.json") {
+  return rel.replace(new RegExp(`/${escapeRegExp(basename)}$`), "");
+}
+function baseName(pathLike) {
+  const parts = pathLike.split("/").filter(Boolean);
+  return parts[parts.length - 1] ?? pathLike;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function countLines(text) {
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines.length;
+}
+function recursiveGlobs(roots, extensions) {
+  return roots.flatMap((root) => extensions.map((ext) => `${root}/**/*${ext}`));
+}
+
+// src/rules/agents-doc-presence.ts
+function createAgentsDocPresenceRule(options = {}) {
+  const docFile = options.docFile ?? "AGENTS.md";
+  const requireAtRoot = options.requireAtRoot ?? true;
+  const surfaceGlobs = options.surfaceGlobs ?? ["apps/*/package.json"];
+  const packageGlobs = options.packageGlobs ?? ["packages/*/package.json"];
+  const optOut = new Set(options.optOut ?? []);
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "agents-doc-presence",
+    category: "source-text",
+    ciCritical,
+    description: `${docFile} must exist at the repo root, every surface, and every non-opted-out package.`,
+    run(ctx) {
+      const violations = [];
+      const requireDoc = (dir, label) => {
+        const rel = dir === "" ? docFile : `${dir}/${docFile}`;
+        if (!ctx.exists(rel)) {
+          violations.push({
+            file: rel,
+            rule: "agents-doc-presence",
+            message: `${label} is missing an ${docFile} agent contract. Add one (or, for a trivial leaf package, add it to the opt-out list with justification).`
+          });
+        }
+      };
+      if (requireAtRoot) requireDoc("", "The repo root");
+      for (const pkg of surfaceGlobs.flatMap((g) => ctx.glob(g))) {
+        requireDoc(dirOf(pkg), "Surface");
+      }
+      for (const pkg of packageGlobs.flatMap((g) => ctx.glob(g))) {
+        const dir = dirOf(pkg);
+        if (optOut.has(dir)) continue;
+        requireDoc(dir, "Package");
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/canonical-helpers-single-home.ts
+var EXPORT_DECL_RE = /\bexport\s+(?:async\s+)?(?:function|const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+var EXPORT_LIST_RE = /\bexport\s*\{\s*([^}]+?)\s*\}/g;
+function extractExportedNames(content) {
+  const names = /* @__PURE__ */ new Set();
+  let m;
+  EXPORT_DECL_RE.lastIndex = 0;
+  while ((m = EXPORT_DECL_RE.exec(content)) !== null) {
+    if (m[1] !== void 0) names.add(m[1]);
+  }
+  EXPORT_LIST_RE.lastIndex = 0;
+  while ((m = EXPORT_LIST_RE.exec(content)) !== null) {
+    const list = m[1] ?? "";
+    for (const part of list.split(",")) {
+      const ident = part.trim().split(/\s+as\s+/i)[0]?.trim() ?? "";
+      if (/^[A-Za-z_$]/.test(ident)) names.add(ident);
+    }
+  }
+  return Array.from(names);
+}
+function createCanonicalHelpersSingleHomeRule(options = {}) {
+  const include = options.include ?? ["apps/web/src/**/*.utils.ts"];
+  const excludeContains = options.excludeContains ?? ["/lib/"];
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "canonical-helpers-single-home",
+    category: "source-text",
+    ciCritical,
+    description: "Pure helpers must live in one canonical home (flag the same exported symbol appearing in multiple homes).",
+    run(ctx) {
+      const violations = [];
+      const files = include.flatMap((g) => ctx.glob(g)).filter((f) => !excludeContains.some((frag) => f.includes(frag)));
+      const nameToHomes = {};
+      for (const file of files) {
+        const content = ctx.read(file) ?? "";
+        for (const name of extractExportedNames(content)) {
+          (nameToHomes[name] ??= []).push(file);
+        }
+      }
+      for (const [name, homes] of Object.entries(nameToHomes)) {
+        const first = homes[0];
+        if (homes.length > 1 && first !== void 0) {
+          violations.push({
+            file: first,
+            rule: "canonical-helpers-single-home",
+            message: `Helper '${name}' lives in multiple homes (${homes.join(", ")}) \u2014 consolidate to the canonical one.`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/file-size-ratchet.ts
+var import_harness = require("@noctcore/harness");
+var DEFAULT_EXCLUDE_CONTAINS = [".test.", ".spec.", ".stories."];
+function createFileSizeRatchetRule(options = {}) {
+  const id = options.id ?? "file-size-ratchet";
+  const roots = options.roots ?? [];
+  const extensions = options.extensions ?? [".ts", ".tsx"];
+  const cap = options.cap ?? 400;
+  const excludeContains = options.excludeContains ?? DEFAULT_EXCLUDE_CONTAINS;
+  const excludePrefixes = options.excludePrefixes ?? [];
+  const tightenRatio = options.tightenRatio ?? 0.85;
+  const baselineDir = options.baselineDir ?? import_harness.DEFAULT_BASELINE_DIR;
+  const ciCritical = options.ciCritical ?? true;
+  function sourceFiles(ctx) {
+    return recursiveGlobs(roots, extensions).flatMap((pattern) => ctx.glob(pattern)).filter(
+      (rel) => !excludeContains.some((frag) => rel.includes(frag)) && !excludePrefixes.some((prefix) => rel.startsWith(prefix))
+    ).sort();
+  }
+  function currentOffenders(ctx) {
+    const map = {};
+    for (const file of sourceFiles(ctx)) {
+      const text = ctx.read(file);
+      if (text === null) continue;
+      const n = countLines(text);
+      if (n > cap) map[file] = n;
+    }
+    return map;
+  }
+  return {
+    id,
+    category: "source-text",
+    ciCritical,
+    description: `Source files stay at or under ${cap} raw lines. Today's offenders are grandfathered by ${baselineDir}/${id}.json; a new/grown offender fails, and a stale/shrunk baseline entry demands tightening.`,
+    baseline(ctx) {
+      return currentOffenders(ctx);
+    },
+    run(ctx) {
+      const baseline = (0, import_harness.loadBaseline)(ctx, id, baselineDir);
+      const violations = [];
+      for (const [file, n] of Object.entries(currentOffenders(ctx))) {
+        if ((0, import_harness.isGrandfathered)(baseline, file, n)) {
+          console.error(
+            `[grandfathered] ${id} (${file}): ${n} lines frozen by baseline (cap ${cap}) \u2014 split to ratchet down.`
+          );
+        } else {
+          violations.push({
+            file,
+            rule: id,
+            message: `file exceeds the ${cap}-line cap: ${n} lines. New files never join the baseline and frozen files may not grow \u2014 split it.`
+          });
+        }
+      }
+      for (const [file, frozen] of Object.entries(baseline)) {
+        const text = ctx.read(file);
+        if (text === null) {
+          violations.push({
+            file,
+            rule: id,
+            message: `baseline entry is stale \u2014 the file no longer exists. Remove it and update the baseline.`
+          });
+          continue;
+        }
+        const n = countLines(text);
+        if (n <= cap) {
+          violations.push({
+            file,
+            rule: id,
+            message: `baseline entry is stale \u2014 the file is now within the ${cap}-line cap (${n} lines). Remove it and update the baseline.`
+          });
+        } else if (n < frozen * tightenRatio) {
+          violations.push({
+            file,
+            rule: id,
+            message: `baseline entry is over-generous \u2014 the file shrank below its frozen ${frozen} (now ${n} lines). Tighten it and update the baseline.`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/layer-rank.ts
+var DEFAULT_SOURCE_GLOBS = [
+  "packages/*/src/**/*.ts",
+  "packages/*/src/**/*.tsx",
+  "apps/*/src/**/*.ts",
+  "apps/*/src/**/*.tsx"
+];
+function createLayerRankRule(options = {}) {
+  const scope = options.scope ?? "@nightcore";
+  const ranks = options.ranks ?? {};
+  const surfacePrefix = options.surfacePrefix ?? "apps/";
+  const surfaceRank = options.surfaceRank;
+  const dirPattern = new RegExp(options.packageDirPattern ?? "^packages/([^/]+)/");
+  const sourceGlobs = options.sourceGlobs ?? DEFAULT_SOURCE_GLOBS;
+  const ciCritical = options.ciCritical ?? true;
+  const importRe = new RegExp(`from\\s+['"]${escapeRegExp(scope)}\\/([a-z0-9-]+)`, "g");
+  function importerRank(rel) {
+    if (surfaceRank !== void 0 && rel.startsWith(surfacePrefix)) return surfaceRank;
+    const m = dirPattern.exec(rel);
+    const key = m?.[1];
+    if (key === void 0) return null;
+    return ranks[key] ?? null;
+  }
+  return {
+    id: "layer-rank",
+    category: "source-text",
+    ciCritical,
+    description: "Fixed dependency direction by rank: a module imports only strictly-lower-ranked <scope> packages (equal/upward forbidden).",
+    run(ctx) {
+      const violations = [];
+      const files = sourceGlobs.flatMap((g) => ctx.glob(g));
+      for (const f of files) {
+        if (f.endsWith(".test.ts") || f.endsWith(".test.tsx")) continue;
+        const fromRank = importerRank(f);
+        if (fromRank === null) continue;
+        const body = ctx.read(f) ?? "";
+        for (const m of body.matchAll(importRe)) {
+          const target = m[1];
+          if (target === void 0) continue;
+          const toRank = ranks[target];
+          if (toRank === void 0) continue;
+          if (toRank >= fromRank) {
+            const kind = toRank === fromRank ? "sideways" : "upward";
+            violations.push({
+              file: f,
+              rule: "layer-rank",
+              message: `Forbidden ${kind} import: ${scope}/${target} (rank ${toRank}) from a rank-${fromRank} module. A module may import only strictly-lower-ranked ${scope} packages. Add a fa\xE7ade/bridge seam instead of a new edge.`
+            });
+          }
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/no-cloned-component-folders.ts
+function createNoClonedComponentFoldersRule(options = {}) {
+  const componentsRoot = options.componentsRoot ?? "apps/web/src/components";
+  const barrelFile = options.barrelFile ?? "index.ts";
+  const excludedFeatures = new Set(options.excludedFeatures ?? ["ui", "app"]);
+  const allowedClones = new Set(options.allowedClones ?? []);
+  const sharedDest = options.sharedDest ?? "components/ui";
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "no-cloned-component-folders",
+    category: "source-text",
+    ciCritical,
+    description: "A component folder name may exist under only ONE feature. Shared surfaces are hoisted; divergent ones get a divergent name. Today\u2019s clones are frozen in a shrinking allowlist.",
+    run(ctx) {
+      const violations = [];
+      const byName = /* @__PURE__ */ new Map();
+      for (const rel of ctx.glob(`${componentsRoot}/*/*/${barrelFile}`)) {
+        const segments = rel.split("/");
+        const name = segments[segments.length - 2];
+        const feature = segments[segments.length - 3];
+        if (name === void 0 || feature === void 0) continue;
+        if (excludedFeatures.has(feature)) continue;
+        const features = byName.get(name) ?? [];
+        features.push(feature);
+        byName.set(name, features);
+      }
+      for (const [name, features] of byName) {
+        if (features.length < 2 || allowedClones.has(name)) continue;
+        const sorted = [...features].sort();
+        violations.push({
+          file: `${componentsRoot}/{${sorted.join(",")}}/${name}`,
+          rule: "no-cloned-component-folders",
+          message: `Component folder '${name}' is cloned across ${features.length} features (${sorted.join(", ")}) \u2014 clone drift in the making. Hoist it to ${sharedDest} or rename to reflect divergent semantics.`
+        });
+      }
+      for (const name of allowedClones) {
+        const features = byName.get(name) ?? [];
+        if (features.length < 2) {
+          violations.push({
+            file: `${componentsRoot}/*/${name}`,
+            rule: "no-cloned-component-folders",
+            message: `Allowlist entry '${name}' is stale \u2014 the clone group no longer exists. Remove it from allowedClones (the allowlist only shrinks).`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/no-warn-severity.ts
+var DEFAULT_CONFIG_FILES = ["eslint.config.js", "eslint.config.mjs", "eslint.config.cjs"];
+function createNoWarnSeverityRule(options = {}) {
+  const configFiles = options.configFiles ?? DEFAULT_CONFIG_FILES;
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "no-warn-severity",
+    category: "config",
+    ciCritical,
+    description: "ESLint severity is 'error' or 'off', never 'warn'. A rule that matters is an error; a failure is fixed, not silenced.",
+    run(ctx) {
+      const violations = [];
+      for (const configFile of configFiles) {
+        const config = ctx.read(configFile);
+        if (config === null) continue;
+        config.split(/\r?\n/).forEach((line, i) => {
+          const code = line.replace(/\r$/, "").replace(/\/\/.*$/, "");
+          if (/['"]warn['"]/.test(code)) {
+            violations.push({
+              file: configFile,
+              rule: "no-warn-severity",
+              message: `Line ${i + 1}: ESLint 'warn' severity is forbidden \u2014 use 'error' or 'off'.`,
+              line: i + 1
+            });
+          }
+        });
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/package-shape.ts
+function createPackageShapeRule(options = {}) {
+  const scope = options.scope ?? "@nightcore";
+  const libraryGlobs = options.libraryGlobs ?? ["packages/*/package.json"];
+  const appGlobs = options.appGlobs ?? ["apps/*/package.json"];
+  const externalNames = options.externalNames ?? {};
+  const barrelPath = options.barrelPath ?? "src/index.ts";
+  const distMarker = options.distMarker ?? "dist/";
+  const distFields = options.distFields ?? ["main", "module", "types"];
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "package-shape",
+    category: "config",
+    ciCritical,
+    description: "Every workspace is named <scope>/<dir>; library packages expose a barrel and point main/module/types/exports at the built output.",
+    run(ctx) {
+      const violations = [];
+      const groups = [
+        { globs: libraryGlobs, library: true },
+        { globs: appGlobs, library: false }
+      ];
+      for (const group of groups) {
+        const rels = group.globs.flatMap((g) => ctx.glob(g));
+        for (const rel of rels) {
+          const raw = ctx.read(rel);
+          if (raw === null) continue;
+          let pkg;
+          try {
+            pkg = JSON.parse(raw);
+          } catch {
+            violations.push({ file: rel, rule: "package-shape", message: "package.json is not valid JSON." });
+            continue;
+          }
+          const dir = dirOf(rel);
+          const expected = externalNames[dir] ?? `${scope}/${baseName(dir)}`;
+          if (pkg.name !== expected) {
+            violations.push({
+              file: rel,
+              rule: "package-shape",
+              message: `Workspace name '${String(pkg.name)}' must equal '${expected}' (the directory it lives in).`
+            });
+          }
+          if (!group.library) continue;
+          if (!ctx.exists(`${dir}/${barrelPath}`)) {
+            violations.push({
+              file: rel,
+              rule: "package-shape",
+              message: `Library package must expose a single barrel at ${dir}/${barrelPath}.`
+            });
+          }
+          for (const field of distFields) {
+            const val = pkg[field];
+            if (typeof val === "string" && !val.includes(distMarker)) {
+              violations.push({
+                file: rel,
+                rule: "package-shape",
+                message: `package.json "${field}" ('${val}') must point at the built output containing '${distMarker}'.`
+              });
+            }
+          }
+          if (pkg.exports && !JSON.stringify(pkg.exports).includes(distMarker)) {
+            violations.push({
+              file: rel,
+              rule: "package-shape",
+              message: `package.json "exports" must reference the built output containing '${distMarker}'.`
+            });
+          }
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/test-runner-segregation.ts
+function createTestRunnerSegregationRule(options = {}) {
+  const bunPackageGlobs = options.bunPackageGlobs ?? ["packages/*/package.json"];
+  const bunExtraDirs = options.bunExtraDirs ?? [];
+  const vitestDirs = options.vitestDirs ?? [];
+  const bunRunnerImport = options.bunRunnerImport ?? "bun:test";
+  const foreignRunnerImport = options.foreignRunnerImport ?? "vitest";
+  const ciCritical = options.ciCritical ?? true;
+  const importRe = (spec) => new RegExp(`from\\s+['"]${escapeRegExp(spec)}['"]`);
+  const bunRe = importRe(bunRunnerImport);
+  const foreignRe = importRe(foreignRunnerImport);
+  return {
+    id: "test-runner-segregation",
+    category: "testing",
+    ciCritical,
+    description: `Bun-side packages use '${bunRunnerImport}'; foreign-side packages use '${foreignRunnerImport}'. Never mix runners.`,
+    run(ctx) {
+      const violations = [];
+      const vitestSet = new Set(vitestDirs);
+      const pkgDirs = bunPackageGlobs.flatMap((g) => ctx.glob(g)).map((p) => dirOf(p));
+      const bunDirs = [...pkgDirs.filter((d) => !vitestSet.has(d)), ...bunExtraDirs];
+      const testsIn = (dir) => [
+        ...ctx.glob(`${dir}/**/*.test.ts`),
+        ...ctx.glob(`${dir}/**/*.test.tsx`)
+      ];
+      for (const dir of bunDirs) {
+        for (const f of testsIn(dir)) {
+          const body = ctx.read(f) ?? "";
+          if (foreignRe.test(body)) {
+            violations.push({
+              file: f,
+              rule: "test-runner-segregation",
+              message: `Bun-side test imports '${foreignRunnerImport}' \u2014 use '${bunRunnerImport}'.`
+            });
+          }
+          if (!bunRe.test(body)) {
+            violations.push({
+              file: f,
+              rule: "test-runner-segregation",
+              message: `Bun-side test must import its runner from '${bunRunnerImport}'.`
+            });
+          }
+        }
+      }
+      for (const dir of vitestDirs) {
+        for (const f of testsIn(dir)) {
+          const body = ctx.read(f) ?? "";
+          if (bunRe.test(body)) {
+            violations.push({
+              file: f,
+              rule: "test-runner-segregation",
+              message: `Foreign-side test imports '${bunRunnerImport}' \u2014 use '${foreignRunnerImport}'.`
+            });
+          }
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/test-sibling-enforcement.ts
+function createTestSiblingEnforcementRule(options = {}) {
+  const include = options.include ?? ["apps/web/src/**/*.utils.ts"];
+  const testExtensions = options.testExtensions ?? [".test.ts", ".test.tsx"];
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "test-sibling-enforcement",
+    category: "source-text",
+    ciCritical,
+    description: "Every source file matched by `include` must have a colocated sibling test. Pure helpers must ship a test.",
+    run(ctx) {
+      const violations = [];
+      for (const file of include.flatMap((g) => ctx.glob(g))) {
+        const base = file.replace(/\.tsx?$/, "");
+        const siblings = testExtensions.map((ext) => `${base}${ext}`);
+        if (!siblings.some((sib) => ctx.exists(sib))) {
+          violations.push({
+            file,
+            rule: "test-sibling-enforcement",
+            message: `'${file}' is missing a colocated sibling test (${siblings.join(" or ")}). Pure helpers must ship a colocated test.`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/test-workspace-enrollment.ts
+function createTestWorkspaceEnrollmentRule(options = {}) {
+  const scriptName = options.scriptName ?? "test:node";
+  const manifestPath = options.manifestPath ?? "package.json";
+  const packageGlobs = options.packageGlobs ?? ["packages/*/package.json"];
+  const extraDirs = options.extraDirs ?? [];
+  const excludeDirs = new Set(options.excludeDirs ?? []);
+  const testGlobSuffix = options.testGlobSuffix ?? "**/*.test.ts";
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "test-workspace-enrollment",
+    category: "testing",
+    ciCritical,
+    description: `Every candidate package with test files must be enumerated in the root '${scriptName}' script.`,
+    run(ctx) {
+      const root = ctx.read(manifestPath);
+      if (root === null) return [];
+      let scripts = {};
+      try {
+        scripts = JSON.parse(root).scripts ?? {};
+      } catch {
+        return [];
+      }
+      const script = scripts[scriptName] ?? "";
+      const violations = [];
+      const dirs = [
+        ...packageGlobs.flatMap((g) => ctx.glob(g)).map((p) => dirOf(p)),
+        ...extraDirs
+      ];
+      for (const dir of dirs) {
+        if (excludeDirs.has(dir)) continue;
+        const hasTests = ctx.glob(`${dir}/${testGlobSuffix}`).length > 0;
+        if (!hasTests) continue;
+        if (!script.includes(dir)) {
+          violations.push({
+            file: manifestPath,
+            rule: "test-workspace-enrollment",
+            message: `Package '${dir}' has test files but is not listed in the '${scriptName}' script \u2014 its tests run in no CI gate. Add '${dir}' to '${scriptName}'.`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/ui-primitive-shape.ts
+function createUiPrimitiveShapeRule(options = {}) {
+  const uiRoot = options.uiRoot ?? "apps/web/src/components/ui";
+  const barrelFile = options.barrelFile ?? "index.ts";
+  const roles = options.roles ?? ["test", "stories"];
+  const extension = options.extension ?? ".tsx";
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: "ui-primitive-shape",
+    category: "source-text",
+    ciCritical,
+    description: `A folder primitive under the ui root must ship its proof siblings (${roles.join(", ")}); a flat primitive must not carry sibling proof files at the root.`,
+    run(ctx) {
+      const violations = [];
+      for (const barrel of ctx.glob(`${uiRoot}/*/${barrelFile}`)) {
+        const dir = barrel.replace(new RegExp(`/${barrelFile}$`), "");
+        const name = baseName(dir);
+        for (const role of roles) {
+          const rel = `${dir}/${name}.${role}${extension}`;
+          if (!ctx.exists(rel)) {
+            violations.push({
+              file: dir,
+              rule: "ui-primitive-shape",
+              message: `ui folder-primitive '${name}' is missing ${name}.${role}${extension}. A ui primitive complex enough to be a folder must ship its proof siblings (or stay a flat presentational file).`
+            });
+          }
+        }
+      }
+      for (const flat of ctx.glob(`${uiRoot}/[A-Z]*${extension}`)) {
+        const name = baseName(flat).replace(new RegExp(`${extension.replace(/\./g, "\\.")}$`), "");
+        for (const role of roles) {
+          const sibling = `${uiRoot}/${name}.${role}${extension}`;
+          if (ctx.exists(sibling)) {
+            violations.push({
+              file: flat,
+              rule: "ui-primitive-shape",
+              message: `ui flat primitive '${name}${extension}' has a sibling ${name}.${role}${extension} at the ui root \u2014 move both into a '${name}/' folder with ${barrelFile}.`
+            });
+          }
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/workspace-graph-parity.ts
+function createWorkspaceGraphParityRule(options = {}) {
+  const scope = options.scope ?? "@nightcore";
+  const packageGlobs = options.packageGlobs ?? ["packages/*/package.json", "apps/*/package.json"];
+  const srcDir = options.srcDir ?? "src";
+  const ciCritical = options.ciCritical ?? true;
+  const esc = escapeRegExp(scope);
+  return {
+    id: "workspace-graph-parity",
+    category: "config",
+    ciCritical,
+    description: "Imported <scope>/* specifiers must be declared workspace:* deps, and tsconfig references must mirror those deps.",
+    run(ctx) {
+      const violations = [];
+      const declaredRe = new RegExp(`"(${esc}\\/[a-z0-9-]+)"\\s*:\\s*"workspace:[^"]*"`, "g");
+      const importRe = new RegExp(`from\\s+['"](${esc}\\/[a-z0-9-]+)`, "g");
+      for (const rel of packageGlobs.flatMap((g) => ctx.glob(g))) {
+        const raw = ctx.read(rel);
+        if (raw === null) continue;
+        const dir = dirOf(rel);
+        const self = `${scope}/${baseName(dir)}`;
+        const declared = new Set(
+          Array.from(raw.matchAll(declaredRe), (m) => m[1]).filter(
+            (s) => s !== void 0
+          )
+        );
+        const imported = /* @__PURE__ */ new Set();
+        const srcFiles = [
+          ...ctx.glob(`${dir}/${srcDir}/**/*.ts`),
+          ...ctx.glob(`${dir}/${srcDir}/**/*.tsx`)
+        ];
+        for (const f of srcFiles) {
+          if (f.endsWith(".test.ts") || f.endsWith(".test.tsx")) continue;
+          const body = ctx.read(f) ?? "";
+          for (const m of body.matchAll(importRe)) {
+            const spec = m[1];
+            if (spec !== void 0 && spec !== self) imported.add(spec);
+          }
+        }
+        for (const spec of imported) {
+          if (!declared.has(spec)) {
+            violations.push({
+              file: rel,
+              rule: "workspace-graph-parity",
+              message: `${self} imports ${spec} but does not declare it as a "workspace:*" dependency. Add it to package.json.`
+            });
+          }
+        }
+        const tsconfig = ctx.read(`${dir}/tsconfig.json`);
+        if (tsconfig !== null) {
+          const refDirs = new Set(
+            Array.from(tsconfig.matchAll(/"path"\s*:\s*"([^"]+)"/g), (m) => {
+              const parts = (m[1] ?? "").split("/").filter(Boolean);
+              return `${scope}/${parts[parts.length - 1] ?? ""}`;
+            })
+          );
+          for (const dep of declared) {
+            if (!refDirs.has(dep)) {
+              violations.push({
+                file: `${dir}/tsconfig.json`,
+                rule: "workspace-graph-parity",
+                message: `tsconfig "references" is missing ${dep}, a declared workspace:* dependency. References must mirror deps.`
+              });
+            }
+          }
+          for (const ref of refDirs) {
+            if (!declared.has(ref)) {
+              violations.push({
+                file: `${dir}/tsconfig.json`,
+                rule: "workspace-graph-parity",
+                message: `tsconfig references ${ref} but it is not a declared workspace:* dependency. References must mirror deps.`
+              });
+            }
+          }
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/index.ts
+var RULE_FACTORIES = {
+  "agents-doc-presence": createAgentsDocPresenceRule,
+  "canonical-helpers-single-home": createCanonicalHelpersSingleHomeRule,
+  "file-size-ratchet": createFileSizeRatchetRule,
+  "layer-rank": createLayerRankRule,
+  "no-cloned-component-folders": createNoClonedComponentFoldersRule,
+  "no-warn-severity": createNoWarnSeverityRule,
+  "package-shape": createPackageShapeRule,
+  "test-runner-segregation": createTestRunnerSegregationRule,
+  "test-sibling-enforcement": createTestSiblingEnforcementRule,
+  "test-workspace-enrollment": createTestWorkspaceEnrollmentRule,
+  "ui-primitive-shape": createUiPrimitiveShapeRule,
+  "workspace-graph-parity": createWorkspaceGraphParityRule
+};
+var RULE_IDS = Object.keys(RULE_FACTORIES);
+function createAllRules() {
+  return Object.values(RULE_FACTORIES).map((factory) => factory());
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RULE_FACTORIES,
+  RULE_IDS,
+  countLines,
+  createAgentsDocPresenceRule,
+  createAllRules,
+  createCanonicalHelpersSingleHomeRule,
+  createFileSizeRatchetRule,
+  createLayerRankRule,
+  createNoClonedComponentFoldersRule,
+  createNoWarnSeverityRule,
+  createPackageShapeRule,
+  createTestRunnerSegregationRule,
+  createTestSiblingEnforcementRule,
+  createTestWorkspaceEnrollmentRule,
+  createUiPrimitiveShapeRule,
+  createWorkspaceGraphParityRule
+});