@starci/eslint-canon-fe 9.1.10 → 9.1.12

package/CHANGELOG.md

@@ -1,8 +1,16 @@
 # Changelog
 
+## 9.1.12 - 2026-10-27
+
+- Changed: owner ruling two-grammars: the bundled Grammar catalog names the core family `core` and carries the one alias table (`familyAliases`: `starci`, `starci-core` -> `core`); the bundled grammar-lint resolver answers by the canonical id, so a front end with `sides.fe.grammar: core` resolves its component contract and lint family. The runtime copy is refreshed from starci-academy-backend/.claude 180193f12 (canon pins: the Grammar family 0.12.15, hfs 4.7.48). No rule changes.
+
+## 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 180193f12), 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.12",
   "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/grammars/index.yaml

@@ -66,6 +66,12 @@ topics:
     title: Heritage Grammar
     summary: |
       Generated snapshot of the Heritage family's parity declaration, arrangement, scoped tokens and Common renderers.
+# The one alias table of Grammar family ids (ruling two-grammars, 2026-10-27): `core` is the canonical id of the
+# legacy core grammar; the legacy catalog id `starci` and the DNA id `starci-core` are deprecated spellings that
+# resolve to it. Every reader resolves a selection through scripts/lib/grammar-lint.mjs, never through its own list.
+familyAliases:
+  starci: core
+  starci-core: core
 families:
   - id: heritage
     title: heritage
@@ -85,8 +91,8 @@ families:
       (`defineGrammarFamily`), not a family that ships a palette, so `authority`, `reusableStyle`,
       `productComposition` and `index` have nothing to name here. Universal semantics, renderer anatomy,
       state and accessibility remain owned by knowledge/ui.
-  - id: starci
-    title: starci
+  - id: core
+    title: core
     contractRef: common
     lint:
       package: '@starci/eslint-grammar-starci'

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

@@ -30,7 +30,7 @@ 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.15
     group: starci
     install: registry
     side: fe
@@ -51,14 +51,14 @@ pins:
     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.15
     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.15
     group: starci
     install: registry
     side: fe
@@ -105,7 +105,7 @@ pins:
     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.48
     group: starci
     install: registry
     side: both

package/runtime/scripts/lib/grammar-lint.mjs

@@ -4,33 +4,66 @@ import { parseYamlCached } from './yaml-cached.mjs';
 
 const CATALOG_FILE = new URL('../../knowledge/grammars/index.yaml', import.meta.url);
 
+function readCatalog() {
+  return parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
+}
+
+/** The catalog's one alias table: a deprecated id names exactly one canonical family and is never itself a family. */
+function aliasTarget(catalog, family) {
+  const aliases = catalog.familyAliases ?? {};
+  if (!Object.hasOwn(aliases, family)) return null;
+  const target = aliases[family];
+  if (typeof target !== 'string' || Object.hasOwn(aliases, target)
+    || (catalog.families ?? []).some(entry => entry.id === family)) {
+    throw new Error(`Grammar family alias ${family} in knowledge/grammars/index.yaml must name one canonical family`);
+  }
+  return target;
+}
+
 function selectedFamily(family) {
   if (typeof family !== 'string' || !family.trim()) throw new Error('sides.fe.grammar must explicitly name the selected Grammar family');
-  const catalog = parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
-  const matches = (catalog.families ?? []).filter(entry => entry.id === family);
+  const catalog = readCatalog();
+  const id = aliasTarget(catalog, family) ?? family;
+  const matches = (catalog.families ?? []).filter(entry => entry.id === id);
   if (matches.length !== 1) throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
   return { catalog, selected: matches[0] };
 }
 
+/**
+ * Resolve a selection to its canonical family id through the catalog's alias table.
+ * @param {string} family - The id an app or caller names (sides.fe.grammar).
+ * @returns {{ id: string, alias: string | null, note: string | null }} The canonical id; for a deprecated alias, the alias and a note naming the canonical id.
+ */
+export function resolveGrammarFamily(family) {
+  const { selected } = selectedFamily(family);
+  if (selected.id === family) return Object.freeze({ id: family, alias: null, note: null });
+  return Object.freeze({
+    id: selected.id,
+    alias: family,
+    note: `Grammar family id ${family} is a deprecated alias of ${selected.id}; write sides.fe.grammar: ${selected.id}`,
+  });
+}
+
 /** The explicitly selected authored family entry; callers share the catalog lookup rather than inferring a family. */
 export function grammarFamilyFor(family) {
   return Object.freeze(selectedFamily(family).selected);
 }
 
-/** The declared family's lint contract, including an explicit null package when that family has no rules. */
+/** The declared family's lint contract (keyed by the canonical id), including an explicit null package when that family has no rules. */
 export function grammarLintFor(family) {
   const { selected } = selectedFamily(family);
   if (!selected.lint || !Object.hasOwn(selected.lint, 'package')) {
     throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
   }
   const lint = selected.lint;
-  if (lint.package === null) return Object.freeze({ family, package: null });
+  const canonical = selected.id;
+  if (lint.package === null) return Object.freeze({ family: canonical, package: null });
   if (typeof lint.package !== 'string' || !lint.package.startsWith('@starci/eslint-grammar-')
     || typeof lint.factory !== 'string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(lint.factory)
     || typeof lint.prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(lint.prefix)) {
     throw new Error(`Grammar family ${family} has an invalid lint contract in knowledge/grammars/index.yaml`);
   }
-  return Object.freeze({ family, package: lint.package, factory: lint.factory, prefix: lint.prefix });
+  return Object.freeze({ family: canonical, package: lint.package, factory: lint.factory, prefix: lint.prefix });
 }
 
 /** The selected family's shared component/export contract, resolved through its catalog reference. */