@starci/eslint-canon-fe 1.0.1 → 1.2.0

package/index.mjs

@@ -90,6 +90,23 @@ export const ruleOwners = Object.fromEntries(
   CONTRIBUTIONS.flatMap((entry) => Object.keys(entry.rules).map((name) => [name, entry.law])),
 )
 
+/**
+ * Every (law, rule name) pair as DECLARED, before any collapsing.
+ *
+ * `ruleOwners` above and `rules` below are both built with `Object.fromEntries`, which silently
+ * keeps the last writer when two laws declare one name. A guard that walks either of them cannot
+ * see a collision - the duplicate is gone before it looks, so every name appears exactly once BY
+ * CONSTRUCTION and the check passes forever while being blind.
+ *
+ * That is not hypothetical. The back-end twin had this exact shape, three rules were declared by two
+ * laws each, one copy was discarded on import, and its guard reported green throughout. This axis
+ * has no collision today; publishing the raw declarations is what keeps that a FACT rather than an
+ * assumption nobody can test.
+ */
+export const ruleDeclarations = CONTRIBUTIONS.flatMap((entry) =>
+  Object.keys(entry.rules).map((name) => ({ law: entry.law, name })),
+)
+
 /** Every rule this canon publishes, keyed by its published name. */
 export const rules = Object.fromEntries(
   CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.rules)),

package/landmark.mjs

@@ -1,5 +1,5 @@
 /**
- * Rules for the LANDMARK law - `fe/canon/patterns/landmark.md`.
+ * Rules for the LANDMARK law - `patterns/fe/landmark/INDEX.md`.
  *
  * WHY THESE EXIST. A registry makes the failure silent. A key named `dashboard-main` records the
  * intent exactly and renders a `div`, because the branch that draws registry nodes draws divs. An
@@ -51,13 +51,13 @@ export const isRouteFile = (filename) => /\/app\/(?:.*\/)?(?:layout|page)\.tsx$/
  * The landmark used to be a named branch, so "the outermost file that composes the screen" and "a
  * file under `app/`" were the same sentence — the branch was imported into the route file and that
  * was that. Then the mark moved into the contract entry as `host: "main"`, and the two sentences
- * came apart: the entry is rendered by whoever renders the screen's outermost frame, and LAYOUT-6
+ * came apart: the entry is rendered by whoever renders the screen's outermost frame, and FILE-6
  * says that is emphatically NOT the route file. A route names which page renders at which URL and
  * draws nothing.
  *
  * Held to route files only, the two laws then refused each other. Every page moved out of `app/` to
- * satisfy LAYOUT-6 was reported for misplacing its landmark, and the only way to satisfy both at
- * once was to leave the page owner in the routing tree — which is the defect LAYOUT-6 exists to
+ * satisfy FILE-6 was reported for misplacing its landmark, and the only way to satisfy both at
+ * once was to leave the page owner in the routing tree — which is the defect FILE-6 exists to
  * prevent. A rule that can only be satisfied by breaking another rule is a finding about the rule.
  *
  * What the guarantee actually was, and still is: ONE main per document, owned by whoever owns the
@@ -213,10 +213,10 @@ export const rules = {
      *
      * A frame whose CONTRACT ENTRY declares `host: "main"` is not that. Nobody imported a landmark;
      * the registry says which element this key's node opens, and the frame obeys. That entry is
-     * rendered by whoever renders the screen's outermost node - and LAYOUT-6 says the route file is
+     * rendered by whoever renders the screen's outermost node - and FILE-6 says the route file is
      * emphatically not it, because a route mounts a page and draws nothing. Holding both shapes to
      * route files only made the two laws refuse each other, and the only way to satisfy both was to
-     * leave the page owner in the routing tree, which is the defect LAYOUT-6 exists to prevent.
+     * leave the page owner in the routing tree, which is the defect FILE-6 exists to prevent.
      */
     create(context) {
       const filename = context.filename || context.getFilename()

package/lint-adoption.mjs

@@ -1,116 +1,116 @@
-/**
- * Repository-level audit for effective StarCi FE lint adoption.
- *
- * An ESLint config can import a plugin, copy a plugin, or call itself StarCi while still leaving
- * canonical rules switched off. The only useful evidence is the effective config ESLint applies
- * to a real production file. This audit compares that printed config with this canon.
- */
-/**
- * Where the component tree sits, per supported repository shape.
- *
- * ONE BRANCH, IN ONE PLACE. The difference between a monorepo and a single app is not a difference
- * of law - the rules, their severities and the inline-config refusal are identical. It is only
- * WHERE the law applies. Written out in each repository's config, that fact became two hand-kept
- * lists, and the lists did what hand-kept lists do: one enabled 43 rules, the other 53, and canon
- * had 49. Neither repository was wrong on purpose; nothing told either of them.
- *
- * The candidate path is included deliberately. A Preview candidate is the exact source Apply later
- * ports into production, and leaving it ungoverned means the one file that becomes production was
- * judged by nothing.
- */
-const LAYOUT_GLOBS = {
-    monorepo: [
-        "packages/ui/src/**/*.{ts,tsx}",
-        "apps/*/src/**/*.{ts,tsx}",
-        "**/candidate/src/**/*.{ts,tsx}",
-    ],
-    "single-app": [
-        "src/**/*.{ts,tsx}",
-        "**/candidate/src/**/*.{ts,tsx}",
-    ],
-}
-
-/** The repository shapes this canon knows how to govern. */
-export const LAYOUTS = Object.keys(LAYOUT_GLOBS)
-
-/**
- * The one flat-config block that attaches this canon to a repository.
- *
- * A consuming `eslint.config.mjs` spreads the result and owns nothing else about the rules: not
- * which are on, not their severity, not whether an inline comment may switch one off. Its own
- * plugins, its own ignores and its own language options stay its own business - what it may not
- * keep is a second opinion about the law.
- *
- * @param {object} input - Attachment options.
- * @param {"monorepo" | "single-app"} input.layout - Which shape this repository has.
- * @param {object} input.plugin - The plugin object, imported from this canon.
- * @param {object} input.recommended - The recommendation, imported from this canon.
- * @param {object} input.linterOptions - The linter options, imported from this canon.
- * @returns {object} One flat-config block.
- */
-export const starciFeConfig = ({ layout, plugin, recommended, linterOptions }) => {
-    const files = LAYOUT_GLOBS[layout]
-    if (!files) {
-        throw new Error(`unknown layout "${layout}" - expected one of: ${LAYOUTS.join(", ")}`)
-    }
-    /*
-     * `recommended` is a FLAT rule map here, not a config object with a `rules` key - and reaching
-     * for `.rules` on it is the mistake this line exists to stop repeating. Spread that way it
-     * yields `undefined`, the block ends up with zero rules, and the repository lints clean while
-     * being governed by nothing. That is the worst possible failure for this file: green, silent,
-     * and indistinguishable from success. Both spellings are accepted so neither shape can produce
-     * an empty block.
-     */
-    const rules = recommended?.rules ?? recommended
-    if (!rules || Object.keys(rules).length === 0) {
-        throw new Error("starciFeConfig received an empty recommendation - a config with no rules is not adoption")
-    }
-    return {
-        files,
-        linterOptions,
-        plugins: { "starci-fe": plugin },
-        rules: { ...rules },
-    }
-}
-
-/** Convert every flat-config severity spelling to its numeric meaning. */
-const severityOf = (setting) => {
-  const severity = Array.isArray(setting) ? setting[0] : setting
-  if (severity === "error") return 2
-  if (severity === "warn") return 1
-  if (severity === "off") return 0
-  return severity
-}
-
-/**
- * Compare an `eslint --print-config` result with the canonical recommendation.
- *
- * @param {object} printedConfig - Parsed effective ESLint config for one production probe file.
- * @param {Record<string, string | number | unknown[]>} expectedRules - Canonical rule levels.
- */
-export const auditLintAdoption = (printedConfig, expectedRules) => {
-  const actualRules = printedConfig?.rules ?? {}
-  const missing = []
-  const nonError = []
-
-  for (const name of Object.keys(expectedRules).sort()) {
-    if (actualRules[name] === undefined) {
-      missing.push(name)
-      continue
-    }
-    if (severityOf(actualRules[name]) !== 2) nonError.push(name)
-  }
-
-  const refusesInlineConfig = printedConfig?.linterOptions?.noInlineConfig === true
-  return {
-    ok: missing.length === 0 && nonError.length === 0 && refusesInlineConfig,
-    missing,
-    nonError,
-    refusesInlineConfig,
-  }
-}
-
-/** Repository audits are gathered beside rules, but are not ESLint AST rules themselves. */
-export const audits = { "effective-config": auditLintAdoption }
-export const rules = {}
-export const recommended = {}
+/**
+ * Repository-level audit for effective StarCi FE lint adoption.
+ *
+ * An ESLint config can import a plugin, copy a plugin, or call itself StarCi while still leaving
+ * canonical rules switched off. The only useful evidence is the effective config ESLint applies
+ * to a real production file. This audit compares that printed config with this canon.
+ */
+/**
+ * Where the component tree sits, per supported repository shape.
+ *
+ * ONE BRANCH, IN ONE PLACE. The difference between a monorepo and a single app is not a difference
+ * of law - the rules, their severities and the inline-config refusal are identical. It is only
+ * WHERE the law applies. Written out in each repository's config, that fact became two hand-kept
+ * lists, and the lists did what hand-kept lists do: one enabled 43 rules, the other 53, and canon
+ * had 49. Neither repository was wrong on purpose; nothing told either of them.
+ *
+ * The candidate path is included deliberately. A Preview candidate is the exact source Apply later
+ * ports into production, and leaving it ungoverned means the one file that becomes production was
+ * judged by nothing.
+ */
+const LAYOUT_GLOBS = {
+    monorepo: [
+        "packages/ui/src/**/*.{ts,tsx}",
+        "apps/*/src/**/*.{ts,tsx}",
+        "**/candidate/src/**/*.{ts,tsx}",
+    ],
+    "single-app": [
+        "src/**/*.{ts,tsx}",
+        "**/candidate/src/**/*.{ts,tsx}",
+    ],
+}
+
+/** The repository shapes this canon knows how to govern. */
+export const LAYOUTS = Object.keys(LAYOUT_GLOBS)
+
+/**
+ * The one flat-config block that attaches this canon to a repository.
+ *
+ * A consuming `eslint.config.mjs` spreads the result and owns nothing else about the rules: not
+ * which are on, not their severity, not whether an inline comment may switch one off. Its own
+ * plugins, its own ignores and its own language options stay its own business - what it may not
+ * keep is a second opinion about the law.
+ *
+ * @param {object} input - Attachment options.
+ * @param {"monorepo" | "single-app"} input.layout - Which shape this repository has.
+ * @param {object} input.plugin - The plugin object, imported from this canon.
+ * @param {object} input.recommended - The recommendation, imported from this canon.
+ * @param {object} input.linterOptions - The linter options, imported from this canon.
+ * @returns {object} One flat-config block.
+ */
+export const starciFeConfig = ({ layout, plugin, recommended, linterOptions }) => {
+    const files = LAYOUT_GLOBS[layout]
+    if (!files) {
+        throw new Error(`unknown layout "${layout}" - expected one of: ${LAYOUTS.join(", ")}`)
+    }
+    /*
+     * `recommended` is a FLAT rule map here, not a config object with a `rules` key - and reaching
+     * for `.rules` on it is the mistake this line exists to stop repeating. Spread that way it
+     * yields `undefined`, the block ends up with zero rules, and the repository lints clean while
+     * being governed by nothing. That is the worst possible failure for this file: green, silent,
+     * and indistinguishable from success. Both spellings are accepted so neither shape can produce
+     * an empty block.
+     */
+    const rules = recommended?.rules ?? recommended
+    if (!rules || Object.keys(rules).length === 0) {
+        throw new Error("starciFeConfig received an empty recommendation - a config with no rules is not adoption")
+    }
+    return {
+        files,
+        linterOptions,
+        plugins: { "starci-fe": plugin },
+        rules: { ...rules },
+    }
+}
+
+/** Convert every flat-config severity spelling to its numeric meaning. */
+const severityOf = (setting) => {
+  const severity = Array.isArray(setting) ? setting[0] : setting
+  if (severity === "error") return 2
+  if (severity === "warn") return 1
+  if (severity === "off") return 0
+  return severity
+}
+
+/**
+ * Compare an `eslint --print-config` result with the canonical recommendation.
+ *
+ * @param {object} printedConfig - Parsed effective ESLint config for one production probe file.
+ * @param {Record<string, string | number | unknown[]>} expectedRules - Canonical rule levels.
+ */
+export const auditLintAdoption = (printedConfig, expectedRules) => {
+  const actualRules = printedConfig?.rules ?? {}
+  const missing = []
+  const nonError = []
+
+  for (const name of Object.keys(expectedRules).sort()) {
+    if (actualRules[name] === undefined) {
+      missing.push(name)
+      continue
+    }
+    if (severityOf(actualRules[name]) !== 2) nonError.push(name)
+  }
+
+  const refusesInlineConfig = printedConfig?.linterOptions?.noInlineConfig === true
+  return {
+    ok: missing.length === 0 && nonError.length === 0 && refusesInlineConfig,
+    missing,
+    nonError,
+    refusesInlineConfig,
+  }
+}
+
+/** Repository audits are gathered beside rules, but are not ESLint AST rules themselves. */
+export const audits = { "effective-config": auditLintAdoption }
+export const rules = {}
+export const recommended = {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "UNLICENSED",