@starci/eslint-canon-fe 2.0.0 → 3.0.1

package/README.md

@@ -1,92 +1,38 @@
-# @starci/eslint-canon-fe
-
-**74 ESLint rules, from 18 laws, that hold a React front end to one way of being written.**
-
-Not a style pack. These rules enforce *architecture*: which tier a component belongs to, whether
-structure may be typed as a raw class string, where a vendor primitive may be imported, which file
-is allowed to fetch. Prettier decides how code looks; this decides what it is allowed to be.
-
-```bash
-npm i -D @starci/eslint-canon-fe
-```
-
-## Use it
-
-One block in `eslint.config.mjs`. It attaches every rule at the severity the canon asks for, and
-makes inline disable comments ineffective rather than merely discouraged.
-
-```js
-import starciFe, {
-    recommended,
-    linterOptions,
-    starciFeConfig,
-} from "@starci/eslint-canon-fe"
-
-export default [
-    // …your own ignores, language options and other plugins…
-    starciFeConfig({
-        layout: "single-app",       // or "monorepo"
-        plugin: starciFe,
-        recommended,
-        linterOptions,
-    }),
-]
-```
-
-`layout` is the one thing a repository owns. `single-app` governs `src/**`; `monorepo` governs
-`packages/ui/src/**` and `apps/*/src/**`. **Which globs the law applies to is your fact. What the
-law says is not** — so there is no option to switch a rule off or lower it to a warning.
-
-Prefer to wire it by hand? Every piece is exported: `rules`, `recommended`, `linterOptions`,
-`ruleOwners`, `audits`, `auditOwners`, `lawOwners`.
-
-## What it actually catches
-
-A sample, not the list:
-
-| Rule | What it stops |
-|---|---|
-| `no-literal-structural-class` | Layout classes typed straight onto an element instead of named in the contract registry |
-| `no-unknown-contract-key` | A structure key that no registry entry declares |
-| `presentational-purity` | A drawing component that fetches, so it can never be rendered from a test |
-| `connected-block-has-presentational-twin` | A block wired to data with no pure half to render |
-| `no-vendor-icon-outside-icon-leaf` | A vendor glyph imported anywhere but the one leaf that wraps it |
-| `no-arbitrary-value` · `no-fractional-step` | Values off the spacing scale, invented per call site |
-| `no-resting-twin-component` | A hand-kept skeleton tree that drifts from the thing it stands in for |
-| `no-inline-lint-config` | A disable comment switching the architecture off for one line |
-| `require-export-jsdoc` | An exported symbol with no stated reason to exist |
-| `no-second-language-in-source` | Copy hardcoded where the translation layer should own it |
-| `no-core-grammar-value-import-outside-adapter` | Core grammar values imported by product code instead of one adapter owner |
-| `surface-branch-requires-contract-render` | A surface used as a JSX children container instead of the contract/render lane |
-| `no-reactnode-escape-slot` | Pre-built ReactNode/JSX escaping a typed component boundary |
-| `runtime-contract-content-requires-component-type` | Runtime props paired with bound content instead of a ComponentType render |
-| `tree-contract-render-identity` | Tree/surface and its render contract claiming different identities |
-| `block-root-is-typed-composition` | A block rooted in an anonymous fragment or structural host element |
-
-Every rule names the law that declares it — `ruleOwners` maps rule name to law, so a failing build
-line leads straight to the document that explains why.
-
-## Why the rules are all errors
-
-Existing debt gets fixed before adoption. Lowering architecture to `warn` teaches every later author
-that the boundary is optional, and a boundary everyone learns is optional is not a boundary. There
-is no staged rollout mode, on purpose.
-
-## Companion
-
-- **[@starci/eslint-canon-be](https://www.npmjs.com/package/@starci/eslint-canon-be)** — the
-  back-end half: 37 rules from 15 laws covering CQRS, exceptions, transport, observability and
-  end-to-end flows.
-
-## Where the laws live
-
-Each rule is the enforceable half of a written law. The prose — why the rule exists, what it
-refuses, which cases sit just outside it — is published openly at
-[starci183/starci-claude-skills](https://github.com/starci183/starci-claude-skills).
-
-A rule that cannot be pointed at in real code is a proposal, not a law. Everything here is
-pointed at.
-
-## Requirements
-
-ESLint 9+ (flat config), Node 20.9+.
+# @starci/eslint-canon-fe
+
+The StarCi front-end lint canon for traditional React and TypeScript applications. It keeps
+component ownership, accessibility, loading behavior, vendor boundaries, translations, naming,
+and colocated class-name composition consistent without prescribing a custom rendering protocol.
+
+```bash
+npm i -D @starci/eslint-canon-fe
+```
+
+```js
+import starciFe, { recommended, linterOptions, starciFeConfig } from "@starci/eslint-canon-fe"
+
+export default [starciFeConfig({
+  layout: "single-app",
+  plugin: starciFe,
+  recommended,
+  linterOptions,
+})]
+```
+
+The `single-app` layout governs `src/**`; `monorepo` governs shared package and app source trees.
+The package publishes the plugin, recommended levels, repository audits, and layout helper from
+the root entry point.
+
+## Rules
+
+Rules cover comments, file layout, icons and vendor ownership, landmarks, loading states, naming,
+props, served locales, component splits, design tokens, translations, type safety, typography, and
+class-name ownership. Reusable class names belong in a colocated `classNames.ts` module and should
+be composed with HeroUI `cn` using one utility token per argument.
+
+Grammar is a business-neutral HeroUI-backed component package. Its components accept ordinary
+typed React props and children.
+
+## Requirements
+
+ESLint 9+ (flat config) and Node.js 20.9+.

package/class-names.mjs

@@ -0,0 +1,148 @@
+/**
+ * The classNames law: component markup consumes named styling declarations, while colocated
+ * classNames files own the utility-token composition.
+ */
+
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+const isComponentSource = (filename) => normalizePath(filename).includes("/src/components/")
+const isClassNamesFile = (filename) => /\/classNames\.tsx?$/.test(normalizePath(filename))
+const isClassAttribute = (node) => node.type === "JSXAttribute" && ["className", "class"].includes(node.name?.name)
+const isCn = (node) => node?.type === "Identifier" && node.name === "cn"
+
+const importedClassNames = (context) => {
+  const imports = new Set()
+  for (const statement of context.getSourceCode().ast.body) {
+    if (statement.type !== "ImportDeclaration" || statement.source.value !== "./classNames") continue
+    for (const specifier of statement.specifiers) imports.add(specifier.local.name)
+  }
+  return imports
+}
+
+const isExportedOwner = (node) => {
+  let current = node
+  while (current) {
+    if (["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"].includes(current.type)) {
+      current = current.parent
+      if (current?.type === "VariableDeclarator") current = current.parent
+      if (current?.type === "VariableDeclaration") current = current.parent
+      return ["ExportNamedDeclaration", "ExportDefaultDeclaration"].includes(current?.type)
+    }
+    if (current.type === "VariableDeclarator") {
+      current = current.parent?.parent
+      return ["ExportNamedDeclaration", "ExportDefaultDeclaration"].includes(current?.type)
+    }
+    current = current.parent
+  }
+  return false
+}
+
+const visitTokenLeaves = (node, report) => {
+  if (!node) return
+  if (node.type === "ArrayExpression") {
+    report(node, "array")
+    return
+  }
+  if (node.type === "Literal" && typeof node.value === "string") {
+    if (/\s/.test(node.value) || /\d+,\d+/.test(node.value)) report(node, "token")
+    return
+  }
+  if (node.type === "ConditionalExpression" || node.type === "LogicalExpression") {
+    visitTokenLeaves(node.consequent ?? node.left, report)
+    visitTokenLeaves(node.alternate ?? node.right, report)
+  }
+}
+
+const isEmptyClassName = (node) => node?.type === "Literal" && node.value === null || node?.type === "Identifier" && node.name === "undefined"
+
+const usesImportedClassName = (node, imported) => {
+  if (!node) return false
+  if (node.type === "Identifier") return imported.has(node.name) || node.name === "undefined"
+  if (isEmptyClassName(node)) return true
+  if (node.type === "CallExpression") {
+    if (node.callee.type === "Identifier") return imported.has(node.callee.name)
+    return node.callee.type === "MemberExpression" && node.callee.object.type === "Identifier" && imported.has(node.callee.object.name)
+  }
+  if (node.type === "MemberExpression") return node.object.type === "Identifier" && imported.has(node.object.name)
+  if (node.type === "ConditionalExpression") return usesImportedClassName(node.consequent, imported) && usesImportedClassName(node.alternate, imported)
+  if (node.type === "LogicalExpression") {
+    if (node.operator === "&&") return usesImportedClassName(node.right, imported)
+    return usesImportedClassName(node.left, imported) && usesImportedClassName(node.right, imported)
+  }
+  return false
+}
+
+/** Report className values written directly in component JSX. */
+export const noInlineClassName = {
+  meta: {
+    type: "problem",
+    docs: { description: "Component JSX must import a named className declaration." },
+    schema: [],
+    messages: { inline: "Move this className value to an imported colocated classNames.ts export." },
+  },
+  create(context) {
+    if (!isComponentSource(context.filename || context.getFilename())) return {}
+    const imported = importedClassNames(context)
+    return {
+      JSXAttribute(node) {
+        if (!isClassAttribute(node) || !node.value) return
+        const expression = node.value.type === "JSXExpressionContainer" ? node.value.expression : node.value
+        if (!usesImportedClassName(expression, imported)) context.report({ node, messageId: "inline" })
+      },
+    }
+  },
+}
+
+/** Require every classNames declaration to use the colocated classNames.ts convention. */
+export const classNamesInColocatedFile = {
+  meta: {
+    type: "problem",
+    docs: { description: "Reusable className declarations belong in colocated classNames.ts files." },
+    schema: [],
+    messages: { misplaced: "Put reusable className declarations in a colocated classNames.ts file." },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (!isComponentSource(filename)) return {}
+    return {
+      CallExpression(node) {
+        if (!isCn(node.callee) || isClassNamesFile(filename)) return
+        context.report({ node, messageId: "misplaced" })
+      },
+    }
+  },
+}
+
+/** Require variadic cn utility tokens: no arrays, whitespace-packed values, or fractional commas. */
+export const cnArgumentsAreSingleTokens = {
+  meta: {
+    type: "problem",
+    docs: { description: "Each cn argument is one valid utility token." },
+    schema: [],
+    messages: {
+      array: "Pass utility tokens to cn as variadic arguments, not an array.",
+      token: "Each cn argument must be one utility token without whitespace or malformed fractional commas.",
+      unexported: "Export every className declaration or function that produces a cn value.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (!isClassNamesFile(filename)) return {}
+    return {
+      CallExpression(node) {
+        if (!isCn(node.callee)) return
+        if (!isExportedOwner(node)) context.report({ node, messageId: "unexported" })
+        for (const argument of node.arguments) visitTokenLeaves(argument, (reportedNode, messageId) => context.report({ node: reportedNode, messageId }))
+      },
+    }
+  },
+}
+
+/** Every rule this law publishes. */
+export const rules = {
+  "no-inline-class-name": noInlineClassName,
+  "class-names-in-colocated-file": classNamesInColocatedFile,
+  "cn-arguments-are-single-tokens": cnArgumentsAreSingleTokens,
+}
+
+/** Recommended severity for the classNames law. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/file-layout.mjs

@@ -22,7 +22,7 @@ const TWO_FILE_TIERS = /\/src\/components\/(pages|layouts)\/([^/]+)\/(.+)$/
 const TWO_FILE_TIERS_WITH_CATEGORY = /\/src\/components\/(overlays)\/[^/]+\/([^/]+)\/(.+)$/
 
 /** The two halves, and the twin test of each, are the whole of what a surface folder may hold. */
-const ALLOWED_IN_SURFACE_FOLDER = /^(?:component|index)(?:\.spec)?\.tsx?$/
+const ALLOWED_IN_SURFACE_FOLDER = /^(?:component|index|classNames)(?:\.spec)?\.tsx?$/
 
 /** Folders that are not component code, whatever they are nested inside. */
 const NON_COMPONENT_FOLDERS = /\/src\/components\/.*\/(constants|utils|types|hooks)\//
@@ -36,7 +36,7 @@ const surfaceFolder = (filename) => {
 
 // -- FILE-2 --------------------------------------------------------------------------------------
 
-/** A page, layout or overlay folder holds its two halves and nothing else. */
+/** A page, layout or overlay folder holds its two halves and its colocated class-name module. */
 export const surfaceFolderTwoFilesOnly = {
   meta: {
     type: "problem",
@@ -44,7 +44,7 @@ export const surfaceFolderTwoFilesOnly = {
     schema: [],
     messages: {
       extra:
-        "`{{tier}}/{{name}}/` contains `{{rest}}` - a surface folder holds its two halves ONLY (`component.tsx` is the shape, `index.tsx` is the wiring). Whatever this is, it has a real home: a component of its own goes to `blocks/<category>/`, a closed arrangement to `composites/`, a fetch to `hooks/`, a pure helper to `modules/utils/`, a shape to `modules/types/`, copy or a config map to `resources/`. \"Only this screen uses it\" is how a folder becomes a second codebase.",
+        "`{{tier}}/{{name}}/` contains `{{rest}}` - a surface folder holds `component.tsx`, `index.tsx`, and an optional `classNames.ts`. Whatever else this is has a real home: a component of its own goes to `blocks/<category>/`, a closed arrangement to `composites/`, a fetch to `hooks/`, a pure helper to `modules/utils/`, a shape to `modules/types/`, copy or a config map to `resources/`.",
     },
   },
   create(context) {
@@ -164,7 +164,7 @@ export const noRuntimeNamespace = {
 const FEATURE_TIERS = /\/packages\/[^/]+\/src\/(blocks|overlays|pages|layouts)\//
 
 /** Tiers that know no feature, and therefore belong to the shared package. */
-const VOCABULARY_TIERS = /\/apps\/[^/]+\/src\/(?:components\/)?(contracts|leaves|composites|branches)\//
+const VOCABULARY_TIERS = /\/apps\/[^/]+\/src\/(?:components\/)?(leaves|composites|branches)\//
 
 /**
  * In a monorepo, the shared package stops below the block.
@@ -183,7 +183,7 @@ export const monorepoTierBelongsToItsSide = {
     type: "problem",
     docs: {
       description:
-        "In a monorepo the shared package holds contracts, leaves, composites and branches; blocks, overlays, layouts and pages belong to the app that owns the feature.",
+        "In a monorepo the shared package holds leaves, composites and branches; blocks, overlays, layouts and pages belong to the app that owns the feature.",
     },
     schema: [],
     messages: {
@@ -316,7 +316,6 @@ export const sourceTierMarkerMatchesFolder = {
       blocks: "block",
       branches: "branch",
       composites: "composite",
-      contracts: "contract",
       layouts: "layout",
       leaves: "leaf",
       overlays: "overlay",
@@ -353,7 +352,7 @@ export const noShellTier = {
     schema: [],
     messages: {
       shell:
-        "`shells/` is an untyped branch exemption. Move the owner to a named branch, replace children with typed contract content, and keep vendor mechanics closed there.",
+        "`shells/` is an untyped branch exemption. Move the owner to a named branch and keep vendor mechanics closed there.",
     },
   },
   create(context) {