@starci/eslint-grammar-core 0.13.0 → 0.14.0

package/runtime/knowledge/hfs/rules.yaml

@@ -5664,3 +5664,26 @@ rules:
         source: owner
         quote: "The size of the buttons and controls is uneven; the teacher thinks height = 40px (h-10) should be fixed for every button, switch, input, tabs and so on, what do you think? (translated from Vietnamese)"
         ruling: "One 40px control height is the default of every standalone control (owner ruling control-height-40): Grammar draws it, an app omits size, sm is for a nested item or dense toolbar row, lg only for a landing hero call to action, and controls of one row share one size."
+  - id: R322
+    code: "FE_CHIP_LABEL_CASE"
+    law: "The label of a status chip (a StatusDot with text, a Badge) starts with an uppercase letter, so every chip of an app reads in one vocabulary."
+    kinds: [lint, codemod]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_CHIP_LABEL_CASE"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: chip-label-starts-uppercase}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
+    templateNa: "A template states no chip label; the words are the app's."
+    proves:
+      - packages/eslint/grammar-core/chip-label.spec.mjs
+    exemplifiedBy:
+      - {path: packages/eslint/grammar-core/chip-label.spec.mjs, editions: [lite, full], codes: [FE_CHIP_LABEL_CASE]}
+    witness:
+      - {path: packages/eslint/grammar-core/chip-label.spec.mjs, editions: [lite, full], codes: [FE_CHIP_LABEL_CASE]}
+    cases:
+      - id: case-1
+        date: "2026-10-27"
+        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."

package/app-shell.mjs

@@ -1,208 +0,0 @@
-import { defineFamilyRules } from "./lib/rule-contract.mjs"
-/** FE-APP-SHELL-1..5: static app-frame and visible navbar composition from the UI canon. */
-import { isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs"
-import { grammarName, isBarControl, propOf, resolveLocal, semanticText, textProp } from "./lib/app-shell.mjs"
-import { appBarOpenings, isAppBar, isAppShell, isNavigationDrawer, ownsAppFrame } from "./lib/app-shell-scope.mjs"
-import { visitVisible } from "./lib/app-shell-visible.mjs"
-import { clusterAlternatives } from "./lib/app-shell-cluster.mjs"
-import { isCreateAction, menuHasCreate } from "./lib/app-shell-create.mjs"
-import { provesImportedBar, provesNavigationOpener } from "./lib/app-shell-owner.mjs"
-import { variableOf } from "@starci/eslint-canon-fe/lib/bindings.mjs"
-import { walk } from "@starci/eslint-canon-fe/lib/ast.mjs"
-
-const CANON = "knowledge/ui/composition/app-shell.yaml"
-const BOTTOM_TABS = /^(?:BottomNav|BottomNavigation|BottomTabBar|MobileBottomNav|MobileTabBar)$/
-const EXPECTED_CLUSTER = ["language:IconButton", "theme:Switch", "notifications:IconButton", "account:AvatarButton"]
-
-const meta = (code, description, messages) => ({
-  type: "problem",
-  docs: { description: `${code}: ${description}`, url: CANON },
-  schema: [],
-  messages,
-})
-
-/** Whether a slot is present; unknown spreads do not prove either presence or absence. */
-const slotPresence = (context, opening, name) => {
-  const prop = propOf(context, opening, name)
-  if (!prop.known) return null
-  const value = resolveLocal(context, prop.value)
-  if (value === null || value.type === "Literal" && (value.value == null || value.value === false)) return false
-  return !(value.type === "Identifier" && value.name === "undefined" && !variableOf(context, value)?.defs.length)
-}
-
-/** Resolve constants and require every possible conditional value to prove the slot contract. */
-const everyValue = (context, expression, proves, seen = new Set()) => {
-  const node = resolveLocal(context, expression)
-  if (!node || seen.has(node)) return false
-  if (node.type !== "ConditionalExpression") return proves(node)
-  const visited = new Set(seen).add(node)
-  return [node.consequent, node.alternate].every((branch) => everyValue(context, branch, proves, visited))
-}
-
-const hasMobileNavigation = (context, opening) => {
-  const drawerProp = propOf(context, opening, "navigationDrawer")
-  const drawer = drawerProp.known && everyValue(context, drawerProp.value, (value) => value.type === "ObjectExpression")
-  const opener = drawer || provesNavigationOpener(context, propOf(context, opening, "compactHeader").value)
-  const visibility = propOf(context, opening, "navigationVisibility")
-  const defaultsWide = opener && visibility.known && slotPresence(context, opening, "navigationVisibility") === false
-  if (!defaultsWide && (!visibility.known || !everyValue(context, visibility.value, (value) => value.type === "Literal" && value.value === "wide"))) return false
-  return opener
-}
-
-/** App-owned tab names count only in a frame owner or a shell's rendered slots. */
-const visibleFromShell = (context, target) => {
-  let visible = false
-  walk(context.sourceCode, context.sourceCode.ast, (node) => {
-    if (node.type !== "JSXOpeningElement" || !isAppShell(context, node)) return
-    const inspect = (opening) => { if (opening === target) visible = true }
-    for (const slot of ["header", "compactHeader", "navigation", "primary", "floatingLayer", "compactNavigation"]) visitVisible(context, propOf(context, node, slot).value, inspect)
-    for (const child of node.parent.children) visitVisible(context, child, inspect)
-  })
-  return visible
-}
-
-/** The app frame is the fixed-viewport Grammar shell; hand-written frame landmarks are rejected. */
-export const appShellFrame = {
-  meta: meta("FE_APP_SHELL_FRAME", "FE-APP-SHELL-1 uses WorkspaceShell viewport=fixed.", {
-    frame: "FE_APP_SHELL_FRAME: compose the app frame with WorkspaceShell viewport=\"fixed\"; navigation must resolve to navigationVisibility=\"wide\" and have navigationDrawer or a compactHeader with a left Drawer containing Sidebar presentation=\"drawer\". Grammar owns its header, navigation and independent scroll regions.",
-  }),
-  create(context) {
-    if (!isProductSource(context)) return {}
-    return { JSXOpeningElement(node) {
-      const shell = isAppShell(context, node)
-      const wrongViewport = shell && textProp(context, node, "viewport") !== "fixed"
-      const missingVisibility = shell && slotPresence(context, node, "navigation") !== false && !hasMobileNavigation(context, node)
-      const handFrame = ownsAppFrame(context, node) && (node.name.type === "JSXIdentifier" && ["header", "nav", "main"].includes(node.name.name) || isAppBar(context, node) && !appBarOpenings(context).has(node))
-      if (wrongViewport || missingVisibility || handFrame) {
-        context.report({ node, messageId: "frame" })
-      }
-    } }
-  },
-}
-
-/** Bottom navigation is not an alternative compact app-shell frame. */
-export const noShellBottomTabs = {
-  meta: meta("FE_APP_SHELL_BOTTOM_TABS", "FE-APP-SHELL-4 keeps mobile navigation in the sidebar drawer.", {
-    bottom: "FE_APP_SHELL_BOTTOM_TABS: the app shell uses a mobile subnav opener and Sidebar drawer. Remove bottom tab navigation and WorkspaceShell compactNavigation.",
-  }),
-  create(context) {
-    if (!isProductSource(context)) return {}
-    return { JSXOpeningElement(node) {
-      const name = grammarName(context, node)
-      const appTab = name === null && node.name.type === "JSXIdentifier" && BOTTOM_TABS.test(node.name.name) && (ownsAppFrame(context, node) || visibleFromShell(context, node))
-      const compact = name === "WorkspaceShell" && propOf(context, node, "compactNavigation")
-      const value = compact && resolveLocal(context, compact.value)
-      const absent = value?.type === "Identifier" && value.name === "undefined" && !variableOf(context, value)?.defs.length
-      if (BOTTOM_TABS.test(name ?? "") || appTab || compact && !absent && (!compact.known || compact.value !== null || compact.present)) context.report({ node, messageId: "bottom" })
-    } }
-  },
-}
-
-const visitBar = (context, node, visit) => {
-  const name = grammarName(context, node)
-  if (name === "WorkspaceShell" && isAppShell(context, node)) {
-    for (const slot of ["header", "compactHeader"]) visitVisible(context, propOf(context, node, slot).value, visit)
-  } else if (isAppBar(context, node)) {
-    visitVisible(context, node.parent, visit)
-  } else if (isNavigationDrawer(context, node)) {
-    visitVisible(context, propOf(context, node, "trigger").value, visit)
-  }
-}
-
-const delegatesImportedBar = (context, expression) => {
-  let imported = false
-  let controls = false
-  let unknown = false
-  visitVisible(context, expression, (opening, name) => {
-    if (isBarControl(context, opening, name)) controls = true
-    if (name !== null) return
-    const proof = provesImportedBar(context, opening)
-    if (proof === true) imported = true
-    if (proof === false) unknown = true
-  })
-  return imported && !controls && !unknown
-}
-
-/** Every visible control in a navbar band uses the shared control size. */
-export const navbarControlSize = {
-  meta: meta("FE_NAVBAR_CONTROL_SIZE", "FE-APP-SHELL-2 requires size=control on bar controls.", {
-    control: "FE_NAVBAR_CONTROL_SIZE: {{name}} in the navbar band needs size=\"control\" so every bar control shares Grammar's control height.",
-  }),
-  create(context) {
-    if (!isProductSource(context)) return {}
-    const reported = new Set()
-    return { JSXOpeningElement(node) {
-      visitBar(context, node, (control, name) => {
-        if (!isBarControl(context, control, name) || textProp(context, control, "size") === "control" || reported.has(control)) return
-        reported.add(control)
-        context.report({ node: control, messageId: "control", data: { name } })
-      })
-    } }
-  },
-}
-
-/** The right cluster is checked at the bar's actions composition, in visual source order. */
-export const navbarCluster = {
-  meta: meta("FE_NAVBAR_CLUSTER", "FE-APP-SHELL-3 fixes navbar action kinds and order.", {
-    cluster: "FE_NAVBAR_CLUSTER: navbar actions must be a tertiary Language IconButton in DropdownMenu, theme Switch, notification IconButton in Popover, account AvatarButton in DropdownMenu, in that order. Mobile retains notifications then account and moves language/theme into the drawer.",
-  }),
-  create(context) {
-    if (!isProductSource(context)) return {}
-    return { JSXOpeningElement(node) {
-      const name = grammarName(context, node)
-      if (!isAppShell(context, node) && !isAppBar(context, node)) return
-      const shellHeader = name === "WorkspaceShell"
-      const actions = propOf(context, node, shellHeader ? "header" : "actions")
-      const { alternatives, ownsBar } = clusterAlternatives(context, actions.value, shellHeader)
-      if (ownsBar) return
-      if (shellHeader && delegatesImportedBar(context, actions.value)) return
-      const desktop = EXPECTED_CLUSTER.join("|")
-      const mobile = EXPECTED_CLUSTER.slice(2).join("|")
-      const sequences = alternatives.map((sequence) => sequence.join("|"))
-      if (!sequences.includes(desktop) || sequences.some((sequence) => sequence !== desktop && sequence !== mobile)) context.report({ node, messageId: "cluster" })
-    } }
-  },
-}
-
-/** Creation belongs to its page, never to the global app bar. */
-export const noNavbarCreate = {
-  meta: meta("FE_NAVBAR_CREATE", "FE-APP-SHELL-5 keeps create actions on pages.", {
-    create: "FE_NAVBAR_CREATE: move this create action from the navbar to its page.",
-  }),
-  create(context) {
-    if (!isProductSource(context)) return {}
-    const reported = new Set()
-    const report = (node) => {
-      if (reported.has(node)) return
-      reported.add(node)
-      context.report({ node, messageId: "create" })
-    }
-    const inspect = (control, name) => {
-      if (name === "DropdownMenu" || name === "Popover") {
-        if (["entries", "items", "sections"].some((slot) => menuHasCreate(context, propOf(context, control, slot).value))) report(control)
-        visitVisible(context, propOf(context, control, "content").value, inspect)
-        for (const child of control.parent.children) visitVisible(context, child, inspect)
-      }
-      if (!isBarControl(context, control, name) || reported.has(control)) return
-      const text = `${semanticText(context, control)} ${control.parent.children.map((child) => context.sourceCode.getText(child)).join(" ")}`
-      if (isCreateAction(text)) report(control)
-    }
-    return { JSXOpeningElement(node) {
-      visitBar(context, node, inspect)
-    } }
-  },
-}
-
-/** Every app-shell enforcer is gathered into the ordinary FE lint and gate path. */
-export const rules = {
-  "app-shell-frame": appShellFrame,
-  "no-shell-bottom-tabs": noShellBottomTabs,
-  "navbar-control-size": navbarControlSize,
-  "navbar-cluster": navbarCluster,
-  "no-navbar-create": noNavbarCreate,
-}
-
-defineFamilyRules(rules, "knowledge/ui/composition/app-shell.yaml")
-
-/** Every rule is mandatory. */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))

package/drawing.mjs

@@ -1,60 +0,0 @@
-/** StarCi per-slot status composition, governed by FE-RULE-OWNERSHIP. */
-import { pureHalf } from "@starci/eslint-canon-fe/lib/drawing-scope.mjs"
-import { defineFamilyRules } from "./lib/rule-contract.mjs"
-
-// -- DRAWING-4 ----------------------------------------------------------------------------------
-
-/** Flags that are a slot's data status. */
-const STATUS_FLAG = /^(?:isLoading|isError|isForbidden|isPending|isValidating|isEmpty)$/
-
-/** The name a test expression reads, if it is a status flag. */
-const statusFlagOf = (node) => {
-  if (!node) return null
-  if (node.type === "UnaryExpression") return statusFlagOf(node.argument)
-  if (node.type === "ChainExpression") return statusFlagOf(node.expression)
-  if (node.type === "Identifier" && STATUS_FLAG.test(node.name)) return node.name
-  if (node.type === "MemberExpression" && node.property?.type === "Identifier" && STATUS_FLAG.test(node.property.name)) {
-    return node.property.name
-  }
-  if (node.type === "LogicalExpression" || node.type === "BinaryExpression") return statusFlagOf(node.left) ?? statusFlagOf(node.right)
-  return null
-}
-
-/** A block's pure half never branches on a data status itself. */
-export const slotStatusThroughSlotView = {
-  meta: {
-    type: "problem",
-    docs: { description: "A block's pure half renders data status through `SlotView`, never its own branch." },
-    schema: [],
-    messages: {
-      branch:
-        "This branches on `{{flag}}` by hand. Every slot renders its status through `SlotView`, the one recipe: a second branch drifts from it and becomes one more variant somebody draws.",
-    },
-  },
-  create(context) {
-    if (pureHalf(context) !== "blocks") return {}
-    const check = (node, test) => {
-      const flag = statusFlagOf(test)
-      if (flag) context.report({ node, messageId: "branch", data: { flag } })
-    }
-    return {
-      ConditionalExpression(node) {
-        check(node, node.test)
-      },
-      IfStatement(node) {
-        check(node, node.test)
-      },
-      LogicalExpression(node) {
-        if (node.operator === "&&" && node.parent?.type === "JSXExpressionContainer") check(node, node.left)
-      },
-    }
-  },
-}
-
-/** The family status recipe retains its published rule ID. */
-export const rules = { "slot-status-through-slotview": slotStatusThroughSlotView }
-
-defineFamilyRules(rules, "knowledge/grammars/core/playbook.yaml#state-recipes")
-
-/** Every family composition rule is mandatory. */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))

package/grammar-boundary.mjs

@@ -1,94 +0,0 @@
-import { defineFamilyRules } from "./lib/rule-contract.mjs"
-/**
- * The boundary between product code and `@starci/grammar`.
- *
- * Grammar is a business-neutral HeroUI-backed component package. Product code composes its components with ordinary React
- * children and typed props. A page's structure and text are made of those components, not of raw HTML: a raw `<section>`, `<p>`
- * or `<ul>` carries no density, no focus or landmark contract and no dark value from the design system, and the class names
- * written by hand to compensate are where a second visual language starts.
- *
- * Which tags are refused is decided by the package: a tag is in the list only when `@starci/grammar` exports a component that
- * renders it (`GRAMMAR_OWNERS` below, each entry verified against the package source by the twin test). A tag the grammar has no
- * component for (`div`, `br`, `aside`, `article`) is not refused: there is nothing to compose instead, and refusing it would
- * demand a workaround. When the grammar gains a component for one, the tag joins the list.
- *
- * WHERE IT APPLIES. App source that composes the grammar (slots `fe.feature`, `fe.components`, `fe.route`, `fe.hooks`) and any
- * workspace package except the `<family>-ui` package (`fe.package.ui`), whose components are the renderers and are the one place
- * a raw tag belongs. Spec files render raw HTML as a harness and are not judged. A file no slot owns is not judged either: the
- * rule refuses to guess a scope.
- */
-
-import { hfsOf } from "@starci/eslint-canon-fe/lib/hfs.mjs"
-
-/**
- * The intrinsic elements of page structure and text, each with the grammar components that render it.
- * Read against packages/grammar/src (`export const <Component>`); `grammar-boundary.spec.mjs` fails when one is not exported.
- */
-export const GRAMMAR_OWNERS = Object.freeze({
-  h1: "Heading", h2: "Heading", h3: "Heading", h4: "Heading", h5: "Heading", h6: "Heading",
-  p: "Text", span: "Text",
-  hr: "Divider",
-  label: "Label",
-  form: "Form",
-  fieldset: "Fieldset",
-  dl: "DescriptionList", dt: "DescriptionList", dd: "DescriptionList",
-  table: "DataTable", thead: "DataTable", tbody: "DataTable", tr: "DataTable", td: "DataTable", th: "DataTable",
-  ul: "List, SurfaceListCard or StaticStateRow", ol: "List, SurfaceListCard or StaticStateRow", li: "ListItem, SurfaceListCard or StaticStateRow",
-  header: "SectionHeader or TopBar",
-  footer: "Footer",
-  nav: "NavLandmark, Subnav, Breadcrumbs or NavigationFeatureNav",
-  section: "Region or SurfaceCard",
-  main: "WorkspaceShell",
-  figure: "MediaFrame", figcaption: "MediaFrame",
-})
-
-/** The slots of app source that compose the grammar: features, components, routes and hooks. */
-const APP_SLOTS = new Set(["fe.feature", "fe.components", "fe.route", "fe.hooks"])
-
-/** The slot of the package whose leaves ARE the renderers: the only place raw structural tags belong. */
-const RENDERER_SLOT = "fe.package.ui"
-
-/**
- * True for a file that composes the grammar: app source (`fe.feature`, `fe.components`, `fe.route`, `fe.hooks`) and any
- * workspace package but the `<family>-ui` package, whose components are the renderers.
- */
-const composesGrammar = (context, file) => {
-  const hfs = hfsOf(context)
-  const slot = hfs.slotOf(file)
-  if (slot === null || slot === RENDERER_SLOT) return false
-  return APP_SLOTS.has(slot) || hfs.tierOf(file) === "package"
-}
-
-/** No raw structural or text element in app source or in a package that composes the grammar. */
-export const noRawStructuralElement = {
-  meta: {
-    type: "problem",
-    docs: { description: "Page structure and text are grammar components, not raw `div`-family HTML; only `fe.package.ui` renderers draw raw tags." },
-    schema: [],
-    messages: {
-      raw:
-        "A raw `<{{tag}}>`. Page structure and text are composed from the grammar (`@starci/grammar`, or the repository's `<family>-ui` package): use {{owner}}. A raw tag brings none of the design system's density, landmark and state contract, and the class names written to make up for it start a second visual language. If the grammar cannot express this structure, add the component to the grammar or the ui package rather than drawing it here.",
-    },
-  },
-  create(context) {
-    const file = context.filename || context.getFilename()
-    if (!composesGrammar(context, file)) return {}
-    return {
-      JSXOpeningElement(node) {
-        if (node.name.type !== "JSXIdentifier") return
-        const owner = Object.hasOwn(GRAMMAR_OWNERS, node.name.name) ? GRAMMAR_OWNERS[node.name.name] : null
-        if (owner !== null) context.report({ node, messageId: "raw", data: { tag: node.name.name, owner: `\`${owner}\`` } })
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "no-raw-structural-element": noRawStructuralElement,
-}
-
-defineFamilyRules(rules, "knowledge/patterns/fe/ui.yaml#FE-UI")
-
-/** Every rule is an error. */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))