@starci/eslint-canon-fe 9.1.9 → 9.1.11

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 9.1.11 - 2026-10-27
+
+- Changed: licensed MIT (was UNLICENSED); the package metadata names the repository, homepage and bugs so npm can attach provenance. No rule or behaviour changed.
+
+## 9.1.10 - 2026-10-27
+
+- Added: starci-fe/no-grammar-shim (R321 FE_GRAMMAR_SHIM): an app never re-exports a Grammar export under its own name (`export { X } from`, `export * from`, or an imported binding exported again); the Grammar defect a shim would hide is reported to the Grammar.
+
 ## 9.1.9 - 2026-10-26
 
 - Added: starci-fe/control-height (R320 FE_CONTROL_HEIGHT), selection-fill-no-check and no-grammar-internal-selector.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) StarCi contributors
+Copyright (c) 2026 starci183
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,7 @@
 # @starci/eslint-canon-fe
 
 Universal front-end laws for TypeScript and Next.js applications, classified by
-[FE-RULE-OWNERSHIP](../../../knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP).
+FE-RULE-OWNERSHIP (the StarCi runtime's `contexts/code/fe/index.yaml`).
 The canon owns composition, data and effect boundaries, translations, accessibility, source
 structure, typed contracts, token discipline and check integrity across Grammar families.
 
@@ -46,3 +46,11 @@ dialog, counts mutually exclusive render paths separately and reserves commit fo
 decision rather than repeated collection items.
 
 Regression specs belong to this package. Application front ends and Grammar libraries have no specs.
+
+## The runtime copy
+
+`runtime/` holds the StarCi runtime files the rules import (the slot manifest and view, the project graph and the
+architecture machine it runs, the Sonar syntax rules), byte for byte at their runtime paths. In this repository it is a
+committed snapshot taken from the legacy runtime (starci-academy-backend/.claude at 7424b89ca), where
+`scripts/hfs/sync-runtime.mjs` generates it; refresh it by running that generator there and copying
+`packages/eslint/fe/runtime/` over this folder. Nothing in this package edits it.

package/docs/button-intent.md

@@ -1,6 +1,6 @@
 # Button intent (CTA-6)
 
-Owner: knowledge/ui/composition/cta.yaml
+Owner: contexts/ui/composition/cta.yaml
 
 App `Button` and `IconButton` commands declare `intent`. Grammar derives their variant from that intent and its placement context. These laws apply to every Grammar family in both app editions; aliases and namespace imports retain the same obligations.
 

package/docs/grammar-shim.md

@@ -0,0 +1,25 @@
+# Grammar shims (R321)
+
+Law module: `grammar-shim.mjs`. HFS rule: R321. Knowledge: `contexts/code/fe/ui.md` FE-UI-1 (the app makes no visual choice; the Grammar owns every visual element) and the Grammar follow-up C-7 in `contexts/decisions/open-grammar.md`.
+
+An app imports a Grammar component where it renders it. It never hands one on from an app path under its own name: such a shim makes one app green while the defect it works around (a missing `"use client"`, a wrong prop, a broken export) stays in the Grammar for every other app. The defect is reported to the Grammar instead; an op files `blocked` naming the package, the component and the error.
+
+| Rule | Finding code | Required behavior |
+| --- | --- | --- |
+| `starci-fe/no-grammar-shim` | `FE_GRAMMAR_SHIM` | No `export { X } from "@starci/grammar..."`, no `export * from "@starci/grammar..."`, and no re-export of a binding imported from the Grammar (`export { X }`, `export const Y = X`, `export const Y = G.X`, `export default X`). Rendering an imported component, wrapping it in an app component and type-only re-exports are allowed. Source inside the `@starci/grammar` package itself is out of scope. |
+
+Invalid:
+
+```tsx
+"use client"
+
+export { SurfaceCard } from "@starci/grammar/common"
+```
+
+Valid:
+
+```tsx
+import { SurfaceCard } from "@starci/grammar/common"
+
+export const Panel = ({ children }: PanelProps) => <SurfaceCard>{children}</SurfaceCard>
+```

package/grammar-shim.mjs

@@ -0,0 +1,123 @@
+/**
+ * The rule that holds `grammar-shim.md` (HFS R321, `FE_GRAMMAR_SHIM`).
+ *
+ * An app never re-exports a Grammar export under its own name. A shim, a file whose job is to hand a Grammar component
+ * on from an app path (often behind a directive the Grammar forgot), makes the app green while the defect stays in the
+ * Grammar for every other app; the defect is reported to the Grammar instead. Importing a Grammar component to render
+ * it, wrapping it in an app component and type-only re-exports are not shims. Source inside the Grammar package itself
+ * is out of scope: its entries re-export its components by design.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { unwrap, variableOf } from "./lib/bindings.mjs"
+
+/** Every published entry of the Grammar package, the root and each subpath. */
+const GRAMMAR_SOURCE = /^@starci\/grammar(?:\/|$)/
+/** The Grammar package's own manifest name; its source re-exports by design. */
+const GRAMMAR_PACKAGE = "@starci/grammar"
+
+/** The manifest name of the package owning each directory, read once per directory. */
+const packageNames = new Map()
+
+/** The `name` of the nearest `package.json` that declares one, or null at the filesystem root. */
+const packageNameOf = (directory) => {
+  if (packageNames.has(directory)) return packageNames.get(directory)
+  const parent = dirname(directory)
+  const manifest = resolve(directory, "package.json")
+  let name = null
+  if (existsSync(manifest)) {
+    try {
+      const declared = JSON.parse(readFileSync(manifest, "utf8")).name
+      if (typeof declared === "string") name = declared
+    } catch {
+      name = null
+    }
+  }
+  if (name === null && parent !== directory) name = packageNameOf(parent)
+  packageNames.set(directory, name)
+  return name
+}
+
+/** True for a type-only import or export, declaration-wide or per specifier; a type is no component to shim. */
+const typeOnly = (...nodes) => nodes.some((node) => node.importKind === "type" || node.exportKind === "type")
+
+/** The Grammar import an identifier binds, `{ source, name }`, or null for a local, foreign or type-only binding. */
+const grammarImportOf = (context, identifier) => {
+  const definition = variableOf(context, identifier)?.defs.find((entry) => entry.type === "ImportBinding")
+  if (!definition) return null
+  const source = String(definition.parent.source.value)
+  if (!GRAMMAR_SOURCE.test(source) || typeOnly(definition.parent, definition.node)) return null
+  const specifier = definition.node
+  const name = specifier.type === "ImportSpecifier" ? specifier.imported.name ?? String(specifier.imported.value) : identifier.name
+  return { source, name }
+}
+
+/** The Grammar import an exported value is exactly (`X`, `G.X`), or null for anything computed or wrapped. */
+const grammarValueOf = (context, expression) => {
+  let node = unwrap(expression)
+  const path = []
+  while (node?.type === "MemberExpression" && !node.computed && node.property.type === "Identifier") {
+    path.unshift(node.property.name)
+    node = unwrap(node.object)
+  }
+  if (node?.type !== "Identifier") return null
+  const imported = grammarImportOf(context, node)
+  if (imported === null) return null
+  return path.length === 0 ? imported : { source: imported.source, name: path.join(".") }
+}
+
+/** The name an export specifier spells, identifier or string literal. */
+const spelled = (node) => node.name ?? String(node.value)
+
+const grammarShim = {
+  meta: {
+    type: "problem",
+    docs: { description: "R321: an app never re-exports a Grammar export under its own name; a Grammar defect is reported to the Grammar, not shimmed in the app." },
+    schema: [],
+    messages: {
+      FE_GRAMMAR_SHIM: "FE_GRAMMAR_SHIM: this file re-exports {{name}} of {{source}} under the app's own name. A defect in a Grammar component belongs to the Grammar: report it (the op files `blocked` naming the package, the component and the error), never shim it in the app; import the component from {{source}} where it is rendered.",
+    },
+  },
+  create(context) {
+    const filename = resolve(context.cwd, context.physicalFilename)
+    if (packageNameOf(dirname(filename)) === GRAMMAR_PACKAGE) return {}
+    const report = (node, name, source) => context.report({ node, messageId: "FE_GRAMMAR_SHIM", data: { name: name === null ? "every export" : `\`${name}\``, source } })
+    return {
+      ExportAllDeclaration(node) {
+        const source = String(node.source.value)
+        if (!GRAMMAR_SOURCE.test(source) || typeOnly(node)) return
+        report(node, node.exported ? spelled(node.exported) : null, source)
+      },
+      ExportNamedDeclaration(node) {
+        if (typeOnly(node)) return
+        if (node.source) {
+          const source = String(node.source.value)
+          if (!GRAMMAR_SOURCE.test(source)) return
+          for (const specifier of node.specifiers) {
+            if (!typeOnly(specifier)) report(specifier, spelled(specifier.local), source)
+          }
+          return
+        }
+        for (const specifier of node.specifiers) {
+          const imported = typeOnly(specifier) || specifier.local.type !== "Identifier" ? null : grammarImportOf(context, specifier.local)
+          if (imported) report(specifier, imported.name, imported.source)
+        }
+        if (node.declaration?.type !== "VariableDeclaration") return
+        for (const declarator of node.declaration.declarations) {
+          const imported = declarator.init ? grammarValueOf(context, declarator.init) : null
+          if (imported) report(declarator, imported.name, imported.source)
+        }
+      },
+      ExportDefaultDeclaration(node) {
+        const imported = grammarValueOf(context, node.declaration)
+        if (imported) report(node, imported.name, imported.source)
+      },
+    }
+  },
+}
+
+/** The one rule of the law. */
+export const rules = { "no-grammar-shim": grammarShim }
+
+/** The rule reaches consumers at error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/index.mjs

@@ -21,6 +21,7 @@ import { recommended as envOwnerRecommended, rules as envOwnerRules } from "./en
 import { recommended as feStackRecommended, rules as feStackRules } from "./fe-stack.mjs"
 import { recommended as fileLayoutRecommended, rules as fileLayoutRules } from "./file-layout.mjs"
 import { recommended as formattingRecommended, rules as formattingRules } from "./formatting.mjs"
+import { recommended as grammarShimRecommended, rules as grammarShimRules } from "./grammar-shim.mjs"
 import { recommended as hooksFolderRecommended, rules as hooksFolderRules } from "./hooks-folder.mjs"
 import { recommended as hygieneRecommended, rules as hygieneRules } from "./hygiene.mjs"
 import { recommended as landmarkRecommended, rules as landmarkRules } from "./landmark.mjs"
@@ -65,6 +66,7 @@ const CONTRIBUTIONS = [
   { law: "fe-stack", rules: feStackRules, recommended: feStackRecommended },
   { law: "file-layout", rules: fileLayoutRules, recommended: fileLayoutRecommended },
   { law: "formatting", rules: formattingRules, recommended: formattingRecommended },
+  { law: "grammar-shim", rules: grammarShimRules, recommended: grammarShimRecommended },
   { law: "hooks-folder", rules: hooksFolderRules, recommended: hooksFolderRecommended },
   { law: "hygiene", rules: hygieneRules, recommended: hygieneRecommended },
   { law: "landmark", rules: landmarkRules, recommended: landmarkRecommended },

package/lib/config.mjs

@@ -98,7 +98,7 @@ export const SLOT_FREE_RULES = Object.freeze([
   "no-native-anchor", "no-inline-parameter-type", "no-hand-rolled-polling", "no-copy-in-call", "no-alert", "no-failure-collapse",
   "outcome-kinds-exhaustive", "no-await-in-loop", "prefer-code-point", "prefer-string-raw", "no-nested-conditional", "no-void-operator", "no-unused-import",
   "prefer-export-from", "no-unused-prop-types", "media-has-caption", "max-params",
-  "nested-control-variant", "no-list-panel-padding", "no-app-surface-paint", "divider-full-bleed", "control-height", "selection-fill-no-check",
+  "nested-control-variant", "no-list-panel-padding", "no-app-surface-paint", "divider-full-bleed", "control-height", "selection-fill-no-check", "no-grammar-shim",
   "button-intent-required", "button-no-variant", "destructive-confirm-in-dialog", "single-commit-per-render", "no-commit-in-collection-item",
 ])
 

package/lib/why.mjs

@@ -44,6 +44,11 @@ export const why = {
     en: "`<file>` picks a larger control size or mixes control sizes in one row.",
     fix: "Omit size so Grammar draws the one 40px control height; use sm only for every control of an item or dense toolbar row, and lg only for a landing hero call to action.",
   },
+  "no-grammar-shim": {
+    code: "FE_GRAMMAR_SHIM",
+    en: "`<file>` re-exports a Grammar component under the app's own name.",
+    fix: "Delete the shim and import the component from the Grammar where it is rendered; report the Grammar defect the shim worked around (the op files blocked) so the Grammar fixes it.",
+  },
   "button-no-variant": {
     code: "FE_BUTTON_NO_VARIANT",
     en: "`<file>` chooses a Button or IconButton variant directly.",

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.1.9",
+  "version": "9.1.11",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",
+  "author": "starci183",
+  "homepage": "https://github.com/starci183/starci-harness/tree/main/packages/eslint-canon-fe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starci183/starci-harness.git",
+    "directory": "packages/eslint-canon-fe"
+  },
+  "bugs": {
+    "url": "https://github.com/starci183/starci-harness/issues"
+  },
   "private": false,
   "exports": {
     ".": "./index.mjs",
@@ -33,8 +43,6 @@
     "access": "public"
   },
   "scripts": {
-    "prepack": "node ../../hfs/prep-runtime.mjs",
-    "pretest": "node ../../hfs/prep-runtime.mjs",
     "test": "node --test \"*.spec.mjs\""
   },
   "keywords": [
@@ -48,5 +56,10 @@
     "@typescript-eslint/parser": "^8.70.0",
     "eslint-plugin-sonarjs": "4.2.1",
     "eslint-plugin-unicorn": "65.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.18.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "typescript": "^6.0.3"
   }
 }