@starci/eslint-canon-fe 9.1.10 → 9.1.11

package/CHANGELOG.md

@@ -1,8 +1,12 @@
 # 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
 
-- Changed: bundled canon pins move with hfs 4.7.47 and the Grammar 0.12.14 family.
+- 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
 

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.10",
+  "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"
   }
 }

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -30,35 +30,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.12.14
+    version: 0.12.13
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.56
+    version: 3.4.55
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.1.10
+    version: 9.1.9
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-starci':
-    version: 0.12.14
+    version: 0.12.13
     group: starci
     install: registry
     side: fe
     source: packages/eslint/grammar-starci/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.12.14
+    version: 0.12.13
     group: starci
     install: registry
     side: fe
@@ -98,14 +98,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.47
+    version: 1.7.46
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.47
+    version: 4.7.46
     group: starci
     install: registry
     side: both