@starci/eslint-canon-fe 1.4.5 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @starci/eslint-canon-fe
 
-**58 ESLint rules, from 16 laws, that hold a React front end to one way of being written.**
+**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
@@ -55,7 +55,13 @@ A sample, not the list:
 | `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-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.

package/grammar-boundary.mjs

@@ -0,0 +1,431 @@
+/**
+ * The executable boundary between product components and `@starci/grammar`.
+ *
+ * Grammar describes a tree and branch adapters render it. Product blocks compose those typed
+ * pieces; they do not import Core values, smuggle pre-built JSX through ReactNode slots, or open a
+ * second runtime lane beside ComponentType. These rules keep that boundary mechanical.
+ */
+
+const normalizePath = (value) => String(value || "").replace(/\\/g, "/")
+
+const SURFACES = new Set(["SurfaceCard", "SurfaceFormCard", "SurfaceListCard", "HighlightCard"])
+const TYPED_ROOTS = new Set([...SURFACES, "Tree"])
+
+const filenameOf = (context) => normalizePath(context.filename || context.getFilename())
+const isTestFile = (filename) => /(?:^|\/)(?:__tests__\/.*|[^/]+\.(?:test|spec))\.[^/]+$/.test(filename)
+const isBranchOwner = (filename) => filename.includes("/src/components/branches/")
+const isGrammarContract = (filename) => /\/src\/components\/contracts\/grammar\.[^/]+$/.test(filename)
+const isProductSource = (filename) => filename.includes("/src/") && !isTestFile(filename)
+
+const jsxName = (node) => node?.name?.type === "JSXIdentifier" ? node.name.name : null
+
+const attribute = (node, name) =>
+  (node.attributes || []).find(
+    (entry) => entry.type === "JSXAttribute" && entry.name?.type === "JSXIdentifier" && entry.name.name === name,
+  )
+
+const expressionOf = (attributeNode) => {
+  const value = attributeNode?.value
+  if (!value) return null
+  return value.type === "JSXExpressionContainer" ? value.expression : value
+}
+
+const unwrapExpression = (node) => {
+  let current = node
+  while (["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "ChainExpression"].includes(current?.type)) {
+    current = current.expression
+  }
+  return current
+}
+
+const literalString = (node) => {
+  const value = unwrapExpression(node)
+  if (value?.type === "Literal" && typeof value.value === "string") return value.value
+  if (value?.type === "TemplateLiteral" && value.expressions.length === 0) return value.quasis[0]?.value?.cooked ?? null
+  return null
+}
+
+const defineContractCall = (node) => {
+  const value = unwrapExpression(node)
+  return value?.type === "CallExpression" && value.callee?.type === "Identifier" && value.callee.name === "defineContractComponent"
+    ? value
+    : null
+}
+
+const meaningfulChildren = (openingElement) => {
+  const children = openingElement.parent?.children || []
+  return children.filter((child) => {
+    if (child.type === "JSXText") return child.value.trim().length > 0
+    if (child.type === "JSXExpressionContainer") return child.expression?.type !== "JSXEmptyExpression"
+    return true
+  })
+}
+
+// -- GRAMMAR-1 -----------------------------------------------------------------------------------
+
+/** Product source consumes adapters; only adapter/contract owners may import Core grammar values. */
+export const noCoreGrammarValueImportOutsideAdapter = {
+  meta: {
+    type: "problem",
+    docs: { description: "Core grammar values are imported only by branch adapters and the grammar contract owner." },
+    schema: [],
+    messages: {
+      boundary:
+        "`{{source}}` is the Core grammar value lane. Product source must consume a typed branch/composition adapter; only components/branches and components/contracts/grammar may import these values.",
+    },
+  },
+  create(context) {
+    const filename = filenameOf(context)
+    if (!isProductSource(filename) || isBranchOwner(filename) || isGrammarContract(filename)) return {}
+    return {
+      ImportDeclaration(node) {
+        const source = String(node.source?.value || "")
+        if (!/^@starci\/grammar(?:\/|$)/.test(source)) return
+        const valueSpecifiers = (node.specifiers || []).filter(
+          (specifier) => node.importKind !== "type" && specifier.importKind !== "type",
+        )
+        if (valueSpecifiers.length > 0) context.report({ node, messageId: "boundary", data: { source } })
+      },
+    }
+  },
+}
+
+// -- GRAMMAR-2 -----------------------------------------------------------------------------------
+
+/** Surface branches are invoked through their contract/render lane, never as JSX containers. */
+export const surfaceBranchRequiresContractRender = {
+  meta: {
+    type: "problem",
+    docs: { description: "A surface branch requires contract + render and accepts no JSX children." },
+    schema: [],
+    messages: {
+      lane: "`{{component}}` is a grammar branch. Pass both `contract` and `render`; do not use a raw surface prop lane.",
+      children:
+        "`{{component}}` received pre-built JSX children. Describe the branch with `contract` + `render` so Tree can validate and own the composition.",
+    },
+  },
+  create(context) {
+    const filename = filenameOf(context)
+    if (!isProductSource(filename) || isBranchOwner(filename)) return {}
+    return {
+      JSXOpeningElement(node) {
+        const component = jsxName(node)
+        if (!component || !SURFACES.has(component)) return
+        if (!attribute(node, "contract") || !attribute(node, "render")) {
+          context.report({ node, messageId: "lane", data: { component } })
+        }
+        for (const child of meaningfulChildren(node)) {
+          context.report({ node: child, messageId: "children", data: { component } })
+        }
+      },
+    }
+  },
+}
+
+// -- GRAMMAR-3 -----------------------------------------------------------------------------------
+
+const propertyName = (node) => {
+  if (node?.key?.type === "Identifier") return node.key.name
+  if (node?.key?.type === "Literal" && typeof node.key.value === "string") return node.key.value
+  return "slot"
+}
+
+const forbiddenReactType = (node, seen = new Set()) => {
+  if (!node || typeof node !== "object" || seen.has(node)) return null
+  seen.add(node)
+  if (node.type === "TSTypeReference") {
+    const name = node.typeName?.type === "Identifier" ? node.typeName.name : null
+    if (name === "ReactNode" || name === "ReactElement") return name
+  }
+  if (
+    node.type === "TSQualifiedName" &&
+    node.left?.type === "Identifier" && node.left.name === "JSX" &&
+    node.right?.type === "Identifier" && node.right.name === "Element"
+  ) return "JSX.Element"
+  if (
+    node.type === "TSQualifiedName" &&
+    node.left?.type === "Identifier" && node.left.name === "React" &&
+    node.right?.type === "Identifier" && ["ReactNode", "ReactElement"].includes(node.right.name)
+  ) return `React.${node.right.name}`
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "parent" || key === "loc" || key === "range" || key === "tokens" || key === "comments") continue
+    if (Array.isArray(value)) {
+      for (const entry of value) {
+        const found = forbiddenReactType(entry, seen)
+        if (found) return found
+      }
+    } else {
+      const found = forbiddenReactType(value, seen)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+/** Component APIs cannot carry already-rendered React values across the grammar boundary. */
+export const noReactnodeEscapeSlot = {
+  meta: {
+    type: "problem",
+    docs: { description: "Product component slots carry typed data/components, never ReactNode or JSX.Element." },
+    schema: [],
+    messages: {
+      escape:
+        "`{{slot}}` exposes `{{type}}`, an already-built rendering escape hatch. Pass typed data or a ComponentType through the canonical contract/render lane instead.",
+    },
+  },
+  create(context) {
+    const filename = filenameOf(context)
+    if (!isProductSource(filename) || isBranchOwner(filename) || isGrammarContract(filename)) return {}
+    return {
+      TSPropertySignature(node) {
+        const type = forbiddenReactType(node.typeAnnotation?.typeAnnotation)
+        if (type) context.report({ node, messageId: "escape", data: { slot: propertyName(node), type } })
+      },
+    }
+  },
+}
+
+const collectDefinitions = () => {
+  const definitions = new Map()
+  return {
+    definitions,
+    visitor: {
+      VariableDeclarator(node) {
+        if (node.id?.type === "Identifier" && node.init) definitions.set(node.id.name, unwrapExpression(node.init))
+      },
+    },
+  }
+}
+
+const resolvedDefineCall = (expression, definitions) => {
+  const direct = defineContractCall(expression)
+  if (direct) return direct
+  const value = unwrapExpression(expression)
+  return value?.type === "Identifier" ? defineContractCall(definitions.get(value.name)) : null
+}
+
+// -- GRAMMAR-4 -----------------------------------------------------------------------------------
+
+/** Runtime props require the ComponentType lane of defineContractComponent. */
+export const runtimeContractContentRequiresComponentType = {
+  meta: {
+    type: "problem",
+    docs: { description: "A surface with runtime props renders a named ComponentType contract." },
+    schema: [],
+    messages: {
+      component:
+        "This runtime surface binds content instead of a ComponentType. Define a named render component and pass it as the second argument to `defineContractComponent` before sending runtime `props`.",
+    },
+  },
+  create(context) {
+    const filename = filenameOf(context)
+    if (!isProductSource(filename) || isBranchOwner(filename)) return {}
+    const { definitions, visitor } = collectDefinitions()
+    const candidates = []
+    return {
+      ...visitor,
+      JSXOpeningElement(node) {
+        const component = jsxName(node)
+        if (!component || !SURFACES.has(component)) return
+        const runtimeInput = component === "SurfaceListCard"
+          ? attribute(node, "props")
+          : attribute(node, "contentProps")
+        if (!runtimeInput) return
+        candidates.push({ node, render: expressionOf(attribute(node, "render")) })
+      },
+      "Program:exit"() {
+        for (const candidate of candidates) {
+          const call = resolvedDefineCall(candidate.render, definitions)
+          if (!call) continue // an imported, already-typed contract is checked by TypeScript
+          const content = unwrapExpression(call.arguments[1])
+          if (content?.type !== "Identifier") context.report({ node: candidate.node, messageId: "component" })
+        }
+      },
+    }
+  },
+}
+
+// -- GRAMMAR-5 -----------------------------------------------------------------------------------
+
+/** A rendered contract cannot claim a different identity from its Tree/surface host. */
+export const treeContractRenderIdentity = {
+  meta: {
+    type: "problem",
+    docs: { description: "Tree/surface contract identity matches defineContractComponent identity." },
+    schema: [],
+    messages: {
+      mismatch:
+        "Host contract `{{host}}` does not match render contract `{{render}}`. One branch has one identity; use the same key in Tree/surface and defineContractComponent.",
+    },
+  },
+  create(context) {
+    const filename = filenameOf(context)
+    if (!isProductSource(filename)) return {}
+    const { definitions, visitor } = collectDefinitions()
+    const candidates = []
+    return {
+      ...visitor,
+      JSXOpeningElement(node) {
+        const component = jsxName(node)
+        if (!component || !TYPED_ROOTS.has(component)) return
+        const host = literalString(expressionOf(attribute(node, "contract")))
+        const render = expressionOf(attribute(node, "render"))
+        if (host && render) candidates.push({ node, host, render })
+      },
+      "Program:exit"() {
+        for (const candidate of candidates) {
+          const call = resolvedDefineCall(candidate.render, definitions)
+          const render = literalString(call?.arguments?.[0])
+          if (render && render !== candidate.host) {
+            context.report({ node: candidate.node, messageId: "mismatch", data: { host: candidate.host, render } })
+          }
+        }
+      },
+    }
+  },
+}
+
+// -- GRAMMAR-6 -----------------------------------------------------------------------------------
+
+const exportedFunction = (node) => {
+  if (node.type === "FunctionDeclaration") return node.parent?.type === "ExportNamedDeclaration" || node.parent?.type === "ExportDefaultDeclaration"
+  if (node.type !== "ArrowFunctionExpression" && node.type !== "FunctionExpression") return false
+  const declarator = node.parent
+  return declarator?.type === "VariableDeclarator" && declarator.parent?.parent?.type === "ExportNamedDeclaration"
+}
+
+const returnedValues = (node) => {
+  if (node.body?.type !== "BlockStatement") return [node.body]
+  return node.body.body.filter((statement) => statement.type === "ReturnStatement").map((statement) => statement.argument)
+}
+
+const untypedRoot = (node) => {
+  const value = unwrapExpression(node)
+  if (!value || value.type === "Literal" && value.value === null) return null
+  if (value.type === "ConditionalExpression") return untypedRoot(value.consequent) || untypedRoot(value.alternate)
+  if (value.type === "LogicalExpression") return untypedRoot(value.right)
+  if (value.type === "JSXFragment") return value
+  if (value.type !== "JSXElement") return null
+  const name = value.openingElement?.name
+  if (name?.type === "JSXIdentifier" && /^[A-Z]/.test(name.name)) return null
+  if (name?.type === "JSXMemberExpression") return null
+  return value
+}
+
+/** Exported block roots are typed compositions, not fragments or structural host elements. */
+export const blockRootIsTypedComposition = {
+  meta: {
+    type: "problem",
+    docs: { description: "An exported block starts at a typed composition boundary." },
+    schema: [],
+    messages: {
+      root:
+        "A block cannot own an anonymous fragment or structural host root. Start it with Tree or a named typed composition component whose contract owns the arrangement.",
+    },
+  },
+  create(context) {
+    const filename = filenameOf(context)
+    if (!isProductSource(filename) || !filename.includes("/components/blocks/")) return {}
+    const check = (node) => {
+      if (!exportedFunction(node)) return
+      for (const value of returnedValues(node)) {
+        const root = untypedRoot(value)
+        if (root) context.report({ node: root, messageId: "root" })
+      }
+    }
+    return {
+      ArrowFunctionExpression: check,
+      FunctionExpression: check,
+      FunctionDeclaration: check,
+    }
+  },
+}
+
+export const rules = {
+  "no-core-grammar-value-import-outside-adapter": noCoreGrammarValueImportOutsideAdapter,
+  "surface-branch-requires-contract-render": surfaceBranchRequiresContractRender,
+  "no-reactnode-escape-slot": noReactnodeEscapeSlot,
+  "runtime-contract-content-requires-component-type": runtimeContractContentRequiresComponentType,
+  "tree-contract-render-identity": treeContractRenderIdentity,
+  "block-root-is-typed-composition": blockRootIsTypedComposition,
+}
+
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
+
+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
+}
+
+/** Prove every newly created production probe receives every grammar-boundary rule strictly. */
+export const auditEffectiveConfigCoversNewFiles = (probes, expectedRules = Object.keys(rules).map((name) => `starci-fe/${name}`)) => {
+  const uncovered = []
+  for (const probe of probes || []) {
+    const config = probe?.config ?? {}
+    const missing = expectedRules.filter((name) => severityOf(config.rules?.[name]) !== 2)
+    if (missing.length > 0 || config.linterOptions?.noInlineConfig !== true) {
+      uncovered.push({ path: probe?.path ?? "<unknown>", missing, refusesInlineConfig: config.linterOptions?.noInlineConfig === true })
+    }
+  }
+  return { ok: (probes || []).length > 0 && uncovered.length === 0, uncovered }
+}
+
+const versionParts = (value) => {
+  const match = String(value || "").match(/^(\d+)\.(\d+)\.(\d+)/)
+  return match ? match.slice(1).map(Number) : null
+}
+
+/** Canon FE V2 is compatible only with the ComponentType/Tree grammar lane introduced in 0.2.0. */
+export const auditGrammarEslintVersionParity = ({ eslintVersion, grammarVersion } = {}) => {
+  const eslint = versionParts(eslintVersion)
+  const grammar = versionParts(grammarVersion)
+  const ok = Boolean(eslint && grammar && eslint[0] === 2 && (grammar[0] > 0 || grammar[1] >= 2))
+  return { ok, eslintVersion: eslintVersion ?? null, grammarVersion: grammarVersion ?? null, expected: "canon 2.x + grammar >=0.2.0" }
+}
+
+/** README headline counts are executable release metadata, not hand-kept prose. */
+export const auditRuleReadmeCountParity = ({ readme, publishedRules = rules, publishedLaws } = {}) => {
+  const match = String(readme || "").match(/\*\*(\d+) ESLint rules, from (\d+) laws/)
+  const actualRules = Object.keys(publishedRules || {}).length
+  const actualLaws = Number(publishedLaws)
+  const declaredRules = match ? Number(match[1]) : null
+  const declaredLaws = match ? Number(match[2]) : null
+  return {
+    ok: declaredRules === actualRules && declaredLaws === actualLaws,
+    declaredRules,
+    actualRules,
+    declaredLaws,
+    actualLaws,
+  }
+}
+
+/** A local Python MCP/Qdrant result is usable only when it proves one clean reference worktree. */
+export const auditReferenceReceiptPreflight = ({ reference, receipt } = {}) => {
+  const sourcePath = normalizePath(reference?.path)
+  const indexedPath = normalizePath(receipt?.sourcePath)
+  const commit = String(reference?.revision || "")
+  const revision = String(receipt?.revision || "")
+  const revisionMatches = revision.length >= 7 && commit.startsWith(revision)
+  const referenceRoot = sourcePath.includes("/.worktrees/references/")
+  const sourcePathMatches = referenceRoot && sourcePath === indexedPath
+  const clean = receipt?.dirty === false
+  const hasGeneration = typeof receipt?.generation === "string" && receipt.generation.length > 0
+  return {
+    ok: revisionMatches && sourcePathMatches && clean && hasGeneration,
+    revisionMatches,
+    referenceRoot,
+    sourcePathMatches,
+    clean,
+    hasGeneration,
+  }
+}
+
+export const audits = {
+  "effective-config-covers-new-files": auditEffectiveConfigCoversNewFiles,
+  "grammar-eslint-version-parity": auditGrammarEslintVersionParity,
+  "rule-readme-count-parity": auditRuleReadmeCountParity,
+  "reference-receipt-preflight": auditReferenceReceiptPreflight,
+}

package/index.mjs

@@ -14,7 +14,12 @@
  */
 import { recommended as commentsRecommended, rules as commentsRules } from "./comments.mjs"
 import { recommended as contractRecommended, rules as contractRules } from "./contract.mjs"
-import { recommended as fileLayoutRecommended, rules as fileLayoutRules } from "./file-layout.mjs"
+import { recommended as fileLayoutRecommended, rules as fileLayoutRules } from "./file-layout.mjs"
+import {
+  audits as grammarBoundaryAudits,
+  recommended as grammarBoundaryRecommended,
+  rules as grammarBoundaryRules,
+} from "./grammar-boundary.mjs"
 import { recommended as iconRecommended, rules as iconRules } from "./icon.mjs"
 import { recommended as landmarkRecommended, rules as landmarkRules } from "./landmark.mjs"
 import { recommended as loadingRecommended, rules as loadingRules } from "./loading.mjs"
@@ -42,7 +47,13 @@ import { recommended as vendorRecommended, rules as vendorRules } from "./vendor
 const CONTRIBUTIONS = [
   { law: "comments", rules: commentsRules, recommended: commentsRecommended },
   { law: "contract", rules: contractRules, recommended: contractRecommended },
-  { law: "file-layout", rules: fileLayoutRules, recommended: fileLayoutRecommended },
+  { law: "file-layout", rules: fileLayoutRules, recommended: fileLayoutRecommended },
+  {
+    law: "grammar-boundary",
+    rules: grammarBoundaryRules,
+    recommended: grammarBoundaryRecommended,
+    audits: grammarBoundaryAudits,
+  },
   { law: "icon", rules: iconRules, recommended: iconRecommended },
   { law: "landmark", rules: landmarkRules, recommended: landmarkRecommended },
   { law: "loading", rules: loadingRules, recommended: loadingRecommended },

package/package.json

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

package/the-split.mjs

@@ -73,8 +73,10 @@ export const connectedBlockHasPresentationalTwin = {
         "`{{block}}` reads the world, so it must import exact `{{twin}}` from `./component`. A single leaf, one tree, or no local state is not an exception.",
       bypass:
         "Connected `{{block}}` renders `<{{rendered}}>` directly. Resolve the world here, then render only `<{{twin}}>`; component.tsx owns the complete presentation.",
-      unused:
-        "Connected `{{block}}` imports `{{twin}}` but never renders it. Every connected render path must cross the pure twin.",
+      unused:
+        "Connected `{{block}}` imports `{{twin}}` but never renders it. Every connected render path must cross the pure twin.",
+      called:
+        "Connected `{{block}}` calls `{{twin}}(...)` as an ordinary function. Render `<{{twin}} />` so React owns the twin's hook lifecycle and every render keeps one stable component boundary.",
     },
   },
   create(context) {
@@ -82,8 +84,9 @@ export const connectedBlockHasPresentationalTwin = {
     if (!block) return {}
 
     const twin = `${block}Base`
-    const worldBindings = new Set()
-    const rendered = []
+    const worldBindings = new Set()
+    const rendered = []
+    const calledTwin = []
     let importsTwin = false
     let readsWorld = false
     let rendersTwin = false
@@ -98,9 +101,10 @@ export const connectedBlockHasPresentationalTwin = {
           if (imported && local && REACHES_FOR_THE_WORLD.test(imported)) worldBindings.add(local)
         }
       },
-      CallExpression(node) {
-        if (node.callee?.type !== "Identifier") return
-        if (worldBindings.has(node.callee.name) || REACHES_FOR_THE_WORLD.test(node.callee.name)) {
+      CallExpression(node) {
+        if (node.callee?.type !== "Identifier") return
+        if (node.callee.name === twin) calledTwin.push(node)
+        if (worldBindings.has(node.callee.name) || REACHES_FOR_THE_WORLD.test(node.callee.name)) {
           readsWorld = true
         }
       },
@@ -115,7 +119,7 @@ export const connectedBlockHasPresentationalTwin = {
           context.report({ node, messageId: "missing", data: { block, twin } })
           return
         }
-        for (const entry of rendered) {
+        for (const entry of rendered) {
           if (entry.name !== twin) {
             context.report({
               node: entry.node,
@@ -123,8 +127,11 @@ export const connectedBlockHasPresentationalTwin = {
               data: { block, rendered: entry.name, twin },
             })
           }
-        }
-        if (!rendersTwin) context.report({ node, messageId: "unused", data: { block, twin } })
+        }
+        for (const call of calledTwin) {
+          context.report({ node: call, messageId: "called", data: { block, twin } })
+        }
+        if (!rendersTwin) context.report({ node, messageId: "unused", data: { block, twin } })
       },
     }
   },