@starci/eslint-grammar-core 0.15.2 → 0.15.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.15.3 - 2026-10-28
+
+- Added: `starci-grammar/no-hand-rolled-page-header` (R323, `FE_PAGE_HEADER_HAND_ROLLED`): a `Breadcrumbs` followed by a `SectionHeader` among one parent's element children is a page head composed by hand; compose Grammar 0.15.3's `PageHeader`. Spec: `src/page-header.spec.ts`; docs: `docs/page-header.md`.
+- Changed: versioned together with Grammar 0.15.3; `@starci/eslint-canon-fe` 9.4.3 is the peer dependency; the bundled rule catalog carries R323, and the bundled canon pins follow release F (Grammar family 0.15.3, hfs 4.9.4, canon-fe 9.4.3, canon-be 3.6.3, ai-router 0.3.0).
+
 ## 0.15.2 - 2026-10-28
 
 - Changed: versioned together with Grammar 0.15.2; `@starci/eslint-canon-fe` 9.4.2 is the peer dependency, and the bundled canon pins follow release E (Grammar family 0.15.2, hfs 4.9.3, canon-fe 9.4.2, canon-be 3.6.2, ai-router 0.3.0) and pin no `starci-harness`. No rule changed.

package/README.md

@@ -19,7 +19,7 @@ Family helpers and the generated runtime closure belong to this package.
 
 The rule IDs remain stable when their namespace moves. Laws cover the fixed app shell and navbar,
 Grammar-owned structural elements, glyphs and icon sizes, destructive menu entries, status inks,
-chip labels that start uppercase, heading and token scales, vendor ownership and slot-status composition. Each rule's metadata cites
+chip labels that start uppercase, the page head composed by `PageHeader`, heading and token scales, vendor ownership and slot-status composition. Each rule's metadata cites
 its behavioral knowledge source and the governing ownership test. The R318 surface composition
 rules (nested control variants, panel-list alignment, layout-only CSS) stay in the universal canon.
 

package/dist/index.js

@@ -6,6 +6,7 @@ import { rules as drawingRules } from "./drawing.js";
 import { rules as grammarBoundaryRules } from "./grammar-boundary.js";
 import { rules as iconRules } from "./icon.js";
 import { rules as menuEntriesRules } from "./menu-entries.js";
+import { rules as pageHeaderRules } from "./page-header.js";
 import { rules as statusColorsRules } from "./status-colors.js";
 import { rules as tokensRules } from "./tokens.js";
 import { rules as typographyRules } from "./typography.js";
@@ -18,6 +19,7 @@ const CONTRIBUTIONS = [
     { law: "grammar-boundary", rules: grammarBoundaryRules },
     { law: "icon", rules: iconRules },
     { law: "menu-entries", rules: menuEntriesRules },
+    { law: "page-header", rules: pageHeaderRules },
     { law: "status-colors", rules: statusColorsRules },
     { law: "tokens", rules: tokensRules },
     { law: "typography", rules: typographyRules },

package/dist/lib/why.js

@@ -29,6 +29,11 @@ export const why = {
         en: "Raw `<tag>` in `<file>`. Page structure and text are composed from grammar components, not hand-written HTML.",
         fix: "Replace it with the matching grammar component (`Heading`, `Text`, `SurfaceCard`, ...); if grammar lacks it, add it to grammar or the ui package instead of drawing it in place.",
     },
+    "no-hand-rolled-page-header": {
+        code: "FE_PAGE_HEADER_HAND_ROLLED",
+        en: "A page head in `<file>` is a Breadcrumbs trail and a SectionHeader composed by hand.",
+        fix: "Compose Grammar PageHeader with breadcrumbs, title and the slots the head needs (description, meta, status, mark, actions, tabs).",
+    },
     "no-shell-bottom-tabs": {
         code: "FE_APP_SHELL_BOTTOM_TABS",
         en: "Bottom tab navigation replaces the required mobile sidebar drawer.",

package/dist/page-header.d.ts

@@ -0,0 +1,10 @@
+import type { Rule } from "eslint";
+import type { TSESTree } from "@typescript-eslint/types";
+/** The `SectionHeader` that follows a `Breadcrumbs` among the element children, or null. */
+export declare const handRolledHead: (children: readonly TSESTree.JSXChild[]) => TSESTree.JSXElement | null;
+/** A page head is Grammar's `PageHeader`, never a `Breadcrumbs` and a `SectionHeader` composed by hand. */
+export declare const noHandRolledPageHeader: Rule.RuleModule;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Record<string, Rule.RuleModule>;
+/** Every rule of this law is an error. */
+export declare const recommended: Record<string, "error">;

package/dist/page-header.js

@@ -0,0 +1,66 @@
+import { isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs";
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+/**
+ * The rule that holds the page header law (HFS R323, `FE_PAGE_HEADER_HAND_ROLLED`): a page is headed by Grammar's
+ * `PageHeader`. A page head composed by hand from a `Breadcrumbs` trail and a `SectionHeader` has no band, no top
+ * inset and no separator, and every page re-decides its spacing, so the heads of an app drift apart.
+ *
+ * WHAT IT READS. The children of one JSX element or fragment. A `Breadcrumbs` element followed, among the same parent's
+ * element children, by a `SectionHeader` element is the hand-rolled head: the trail and the heading of one page, which
+ * is exactly what `PageHeader` composes. A `Breadcrumbs` and a `SectionHeader` in different parents, a `SectionHeader`
+ * before the trail, or either alone are not judged: a region's `SectionHeader` under the page head stays legal.
+ */
+/** The element name of a JSX opening element (`SectionHeader`, or `Grammar.SectionHeader` as `SectionHeader`). */
+const elementName = (child) => {
+    if (child.type !== "JSXElement")
+        return null;
+    const name = child.openingElement.name;
+    if (name.type === "JSXIdentifier")
+        return name.name;
+    if (name.type === "JSXMemberExpression")
+        return name.property.name;
+    return null;
+};
+/** The `SectionHeader` that follows a `Breadcrumbs` among the element children, or null. */
+export const handRolledHead = (children) => {
+    let trail = false;
+    for (const child of children) {
+        const name = elementName(child);
+        if (name === "Breadcrumbs")
+            trail = true;
+        if (name === "SectionHeader" && trail && child.type === "JSXElement")
+            return child;
+    }
+    return null;
+};
+/** A page head is Grammar's `PageHeader`, never a `Breadcrumbs` and a `SectionHeader` composed by hand. */
+export const noHandRolledPageHeader = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R323: a page head is Grammar's PageHeader, never Breadcrumbs and SectionHeader composed by hand." },
+        schema: [],
+        messages: {
+            handRolled: "A `Breadcrumbs` trail followed by a `SectionHeader` is a page head composed by hand: it has no band, no top inset and no separator, and each page re-decides its spacing. Use Grammar's `PageHeader` with `breadcrumbs`, `title` and the slots the head needs (`description`, `meta`, `status`, `mark`, `actions`, `tabs`).",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        const judge = (children) => {
+            const header = handRolledHead(children);
+            if (header !== null)
+                context.report({ node: header, messageId: "handRolled" });
+        };
+        return {
+            JSXElement(element) { judge(element.children); },
+            JSXFragment(fragment) { judge(fragment.children); },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "no-hand-rolled-page-header": noHandRolledPageHeader,
+};
+defineFamilyRules(rules, "knowledge/hfs/rules.yaml#R323");
+/** Every rule of this law is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]));

package/docs/page-header.md

@@ -0,0 +1,34 @@
+# Page heads are PageHeader
+
+Law module: `page-header.ts`. Catalogue: R323 FE_PAGE_HEADER_HAND_ROLLED.
+
+A page is headed by Grammar's `PageHeader`: the trail, the page heading with its mark, status and summary, the page's commands and the page tabs, on a surface band whose content shares the page content's edges and which ends in its own full-width separator. A head composed by hand from `Breadcrumbs` and `SectionHeader` has no band, no top inset and no separator, and every page re-decides its spacing.
+
+Every rule below is an error in `coreGrammarConfig`; none can be switched off or suppressed inline.
+
+## `starci-grammar/no-hand-rolled-page-header`
+
+Among the element children of one JSX element or fragment, a `Breadcrumbs` element followed by a `SectionHeader` element is a finding, reported on the `SectionHeader`. A trail and a heading in different parents, a heading before the trail, and either alone are not judged, so a region's `SectionHeader` under the page head stays legal.
+
+**Invalid** (`src/components/blocks/ConnectionPage/component.tsx`)
+
+```tsx
+<div>
+  <Breadcrumbs label="Breadcrumb" items={trail} />
+  <SectionHeader title="Main account" level={1} action={<Button intent="neutral">Disconnect</Button>} />
+</div>
+```
+
+**Valid** (`src/components/blocks/ConnectionPage/component.tsx`)
+
+```tsx
+<PageHeader
+  breadcrumbs={{ label: "Breadcrumb", items: trail }}
+  title="Main account"
+  actions={<Button intent="neutral">Disconnect</Button>}
+/>
+```
+
+**Finding code:** `FE_PAGE_HEADER_HAND_ROLLED`
+
+Rule ownership: [FE-RULE-OWNERSHIP](../../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-grammar-core",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "description": "ESLint rules for the core Grammar's component, token and composition contracts.",
   "keywords": [
     "eslint",
@@ -41,7 +41,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@starci/eslint-canon-fe": "9.4.2",
+    "@starci/eslint-canon-fe": "9.4.3",
     "eslint": ">=9",
     "typescript": ">=5.9"
   },

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

@@ -31,35 +31,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.15.2
+    version: 0.15.3
     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.6.2
+    version: 3.6.3
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-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.4.2
+    version: 9.4.3
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-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-core':
-    version: 0.15.2
+    version: 0.15.3
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/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.15.2
+    version: 0.15.3
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.9.3
+    version: 4.9.4
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -5687,3 +5687,26 @@ rules:
         source: owner
         quote: "A chip label starts uppercase."
         ruling: "The label of a status chip starts with an uppercase letter (owner ruling chip-label-uppercase); StatusDot capitalises a text label it renders, and the lint refuses a lowercase literal label at its source."
+  - id: R323
+    code: "FE_PAGE_HEADER_HAND_ROLLED"
+    law: "A page is headed by Grammar's PageHeader; a Breadcrumbs trail followed by a SectionHeader in one parent is a page head composed by hand, with no band, no top inset and no separator."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PAGE_HEADER_HAND_ROLLED"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: no-hand-rolled-page-header}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
+    templateNa: "A template states no page head; the pages are the app's."
+    proves:
+      - packages/eslint-grammar-core/src/page-header.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/page-header.spec.ts, editions: [lite, full], codes: [FE_PAGE_HEADER_HAND_ROLLED]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/page-header.spec.ts, editions: [lite, full], codes: [FE_PAGE_HEADER_HAND_ROLLED]}
+    cases:
+      - id: case-1
+        date: "2026-10-28"
+        source: owner
+        quote: "Publish Grammar 0.15.3 with PageHeader now, then move all 18 pages to it before deploying. (translated from Vietnamese)"
+        ruling: "A page is headed by Grammar's PageHeader (owner ruling page-header-band): a surface band whose content shares the page content's edges and which ends in its own full-width separator, page tabs standing on it; the lint refuses a page head composed by hand from Breadcrumbs and SectionHeader."