@starci/eslint-grammar-core 0.13.0 → 0.15.0

package/status-colors.mjs

@@ -1,140 +0,0 @@
-import { defineFamilyRules } from "./lib/rule-contract.mjs"
-/**
- * The rule that holds `status-colors.md` (HFS R61 `FE_STYLE_TOKEN_ONLY`, the class-name half of the soft-pair contrast
- * obligation; the brand layer's own contrast belongs to `@starci/stylelint-canon` `starci/status-contrast`).
- *
- * A STATUS TONE HAS TWO FACES. The SOLID tone (`--success`) is a fill: a button, a bar, a badge dot's disc, with
- * `--success-foreground` ink on it. A status shown as TEXT or as an ICON uses the SOFT pair, the way a HeroUI flat Chip
- * does: `--success-soft-foreground` ink, on `--success-soft` when it sits on a tint. The brand layer is checked to
- * make that ink readable (3:1 on the tint and on the page); the solid tone is only the mid-luminance hue of the brand
- * and reads 3.8:1 or worse on white, so as a text colour it fails the contrast the soft pair was built to give.
- *
- * WHAT IT READS. Every static class string a component writes: the `className` / `class` attribute of an element (through
- * `cn()`, `clsx()`, conditionals, arrays, template text), and a string in a constant or in a `classes` entry. The tones
- * are the grammar's `STATUS_TONES` (`lib/status-tones.generated.mjs`, generated from the grammar with the stylelint
- * vocabulary), never a list typed here. A class is a finding when it paints text, an icon or a text decoration with a solid
- * tone (`text-success`, `fill-danger`, `stroke-warning`, `decoration-info`, with any variant and opacity).
- *
- * WHAT IT LEAVES ALONE: the soft pair (`text-success-soft-foreground`, `bg-success-soft`), a solid fill with its own ink
- * (`bg-success text-success-foreground`), a solid border, ring or outline (`border-danger`, `ring-warning`: a
- * boundary is not text), and a class that only shares a prefix (`text-successful`).
- */
-
-import { attributeValue } from "@starci/eslint-canon-fe/lib/ast.mjs"
-import { STATUS_TONES } from "./lib/status-tones.generated.mjs"
-
-/** The utility families that paint text, an icon or a text decoration. */
-const TEXT_PAINT = ["text", "fill", "stroke", "decoration"]
-
-/** `text-success`, `text-success/60`, `text-success-hover`, with an optional `!` and any variants before it. */
-const SOLID_TEXT = new RegExp(`^!?(${TEXT_PAINT.join("|")})-(${STATUS_TONES.join("|")})(?:-hover)?(?:/(?:\\d+|\\[[^\\]]*\\]))?$`)
-
-/** The class after its variants: `md:hover:text-success` and `[&>svg]:text-success` both end at `text-success`. */
-const utilityOf = (token) => {
-  let depth = 0
-  let cut = -1
-  for (let i = 0; i < token.length; i += 1) {
-    if (token[i] === "[") depth += 1
-    else if (token[i] === "]") depth -= 1
-    else if (token[i] === ":" && depth === 0) cut = i
-  }
-  return token.slice(cut + 1)
-}
-
-/** Every solid-tone text class in one class string, as `{ token, family, tone }`. */
-export const solidTextClasses = (text) =>
-  text
-    .split(/\s+/)
-    .filter(Boolean)
-    .flatMap((token) => {
-      const match = SOLID_TEXT.exec(utilityOf(token))
-      return match ? [{ token, family: match[1], tone: match[2] }] : []
-    })
-
-/** The string nodes inside an expression that builds a class string: literals, template text, keys, and everything a call, array or condition carries. */
-function* stringNodes(node) {
-  if (!node || typeof node.type !== "string") return
-  switch (node.type) {
-    case "Literal":
-      if (typeof node.value === "string") yield { node, text: node.value }
-      return
-    case "TemplateLiteral":
-      yield { node, text: node.quasis.map((quasi) => quasi.value.cooked ?? "").join(" ") }
-      return
-    case "JSXExpressionContainer":
-      yield* stringNodes(node.expression)
-      return
-    case "ConditionalExpression":
-      yield* stringNodes(node.consequent)
-      yield* stringNodes(node.alternate)
-      return
-    case "LogicalExpression":
-      yield* stringNodes(node.left)
-      yield* stringNodes(node.right)
-      return
-    case "TSAsExpression":
-    case "TSSatisfiesExpression":
-    case "TSNonNullExpression":
-      yield* stringNodes(node.expression)
-      return
-    case "ArrayExpression":
-      for (const element of node.elements) yield* stringNodes(element)
-      return
-    case "CallExpression":
-      for (const argument of node.arguments) yield* stringNodes(argument)
-      return
-    case "ObjectExpression":
-      for (const property of node.properties) {
-        if (property.type !== "Property") continue
-        if (!property.computed && property.key.type === "Literal") yield* stringNodes(property.key)
-        yield* stringNodes(property.value)
-      }
-      return
-    default:
-  }
-}
-
-/** Text or an icon painted with a solid status tone is not readable at the contrast the soft pair was built for. */
-export const statusTextUsesSoftForeground = {
-  meta: {
-    type: "problem",
-    docs: { description: "Status text and icons take the soft foreground of the tone, never the solid tone." },
-    schema: [],
-    messages: {
-      solid:
-        "`{{token}}` paints text or an icon with the solid `{{tone}}` tone, which is a fill and reads under 4.5:1 on the page (3.8:1 on white for a mid-luminance brand). A status shown as text or an icon takes the soft pair: `{{family}}-{{tone}}-soft-foreground`, on `bg-{{tone}}-soft` when it sits on a tint. The solid tone is for a fill with `text-{{tone}}-foreground` on it.",
-    },
-  },
-  create(context) {
-    // A `classes` entry inside a constant is reached twice (as part of the constant, and as the entry): one finding per string.
-    const seen = new Set()
-    const check = (root) => {
-      for (const { node, text } of stringNodes(root)) {
-        if (seen.has(node)) continue
-        seen.add(node)
-        for (const { token, family, tone } of solidTextClasses(text)) context.report({ node, messageId: "solid", data: { token, family, tone } })
-      }
-    }
-    return {
-      JSXAttribute(node) {
-        if (node.name.type === "JSXIdentifier" && (node.name.name === "className" || node.name.name === "class")) check(attributeValue(node))
-      },
-      VariableDeclarator(node) {
-        check(node.init)
-      },
-      Property(node) {
-        if (!node.computed && node.key.type === "Identifier" && node.key.name === "classes") check(node.value)
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "status-text-uses-soft-foreground": statusTextUsesSoftForeground,
-}
-
-defineFamilyRules(rules, "knowledge/hfs/rules.yaml#R61")
-
-/** Every rule of this law is an error. */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))

package/tokens.mjs

@@ -1,164 +0,0 @@
-/** StarCi scale and theme-token choices; ownership follows FE-RULE-OWNERSHIP. */
-import { existsSync, readFileSync } from "node:fs"
-import { join } from "node:path"
-import { classTextVisitors } from "@starci/eslint-canon-fe/lib/class-text.mjs"
-import { hfsOf } from "@starci/eslint-canon-fe/lib/hfs.mjs"
-import { classOf, isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs"
-import { defineFamilyRules } from "./lib/rule-contract.mjs"
-
-/**
- * A fractional step, in any family that measures.
- *
- * The rungs are whole and unevenly spaced, so half of one is not "between two rungs" - it is off
- * the ladder, and it will match nothing else on any screen.
- */
-const FRACTIONAL =
-  /\b(?:gap|gap-x|gap-y|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|space-x|space-y|inset|top|bottom|left|right|size|w|h)-\d+\.\d+\b/
-
-/** Large text. Paired with a heavy weight it is a heading, whatever element carries it. */
-const LARGE_TEXT = /\btext-(?:xl|2xl|3xl|4xl|5xl)\b/
-
-/** A heavy weight. */
-const HEAVY_WEIGHT = /\bfont-(?:bold|extrabold|black)\b/
-
-/** A fractional step is off the ladder, not between two rungs. */
-export const noFractionalStep = {
-  meta: {
-    type: "problem",
-    docs: { description: "A measurement takes a whole rung; a fractional step is off the scale." },
-    schema: [],
-    messages: {
-      fractional:
-        "`{{cls}}` is half a rung. The scale is whole steps, unevenly spaced, so this is not between two rungs - it is off the ladder, and it will match nothing else on any screen. Use the nearest rung; there is no case where the right answer is half of one.",
-    },
-  },
-  create(context) {
-    return classTextVisitors(context, (node, text) => {
-      if (!text) return
-      const hit = text.match(FRACTIONAL)
-      if (hit) context.report({ node, messageId: "fractional", data: { cls: hit[0] } })
-    })
-  },
-}
-
-/** Large text plus a heavy weight is a heading, and headings come from the component that owns both. */
-export const noHandRolledHeading = {
-  meta: {
-    type: "problem",
-    docs: { description: "A heading comes from the heading component, not from raw type classes." },
-    schema: [],
-    messages: {
-      heading:
-        "Large text and a heavy weight together are a heading, whatever element carries them - and assembled here it is a heading nothing else knows about: the outline a screen reader builds does not contain it, and it stays behind the day the type scale changes. Render the heading component, which owns the tag and the size as one decision.",
-    },
-  },
-  create(context) {
-    return classTextVisitors(context, (node, text) => {
-      if (!text) return
-      if (LARGE_TEXT.test(text) && HEAVY_WEIGHT.test(text)) {
-        context.report({ node, messageId: "heading" })
-      }
-    })
-  },
-}
-
-/**
- * The class families whose names are PROMISES about a theme token, and the variable each needs.
- *
- * Tailwind resolves `max-w-app-lg` by looking for `--container-app-lg`. Nothing warns when that
- * variable does not exist: the class is emitted, the element gets no width, and the type system
- * is satisfied because the name IS in the union. That is the failure this rule exists for - a
- * class can be typesafe and mean nothing at the same time, and the union is exactly what makes
- * it look settled.
- *
- * Only families whose token name is DERIVABLE from the class name are listed. A colour or a
- * spacing step resolves through Tailwind's own scale as well as the theme, so a rule guessing at
- * those would report classes that work.
- */
-/**
- * Names Tailwind resolves ITSELF, which therefore promise nothing about this theme.
- *
- * `min-h-screen` is the viewport, not a variable; so are `full`, `fit`, `auto` and the viewport
- * units. Reported as unresolved tokens they would send an author to define `--min-height-screen`,
- * which is a variable nothing reads - the rule would have invented work and broken a working class.
- * Measured on both repositories the first time this ran: two findings, both wrong, both this list.
- */
-const TAILWIND_OWN_NAMES = new Set([
-  "screen", "full", "fit", "auto", "none", "min", "max", "prose",
-  "dvh", "svh", "lvh", "dvw", "svw", "lvw", "px",
-])
-const TOKEN_CLASS_FAMILIES = [
-  { pattern: /^max-w-app-([a-z0-9]+)$/, variable: (name) => `--container-app-${name}` },
-  { pattern: /^max-h-([a-z][a-z0-9-]*)$/, variable: (name) => `--max-height-${name}` },
-  { pattern: /^min-h-([a-z][a-z0-9-]*)$/, variable: (name) => `--min-height-${name}` },
-]
-
-/**
- * The stylesheets an app declares its theme in: the route slot's `globals.css` (`fe.route`, named by its `allows`) and the brand slot's
- * `brand.css` (`fe.modules.brand`), both with `<app>` filled from the linted file's slot. Null when the file belongs to no app
- * (a shared package has no theme of its own).
- */
-/** Every theme read once per lint run. */
-const themeCache = new Map()
-const themeText = (context) => {
-  const hfs = hfsOf(context)
-  const app = classOf(context).bindings?.app
-  if (app === undefined) return null
-  const candidates = [
-    join(hfs.slot("fe.route").path.replace("<app>", app), "globals.css"),
-    hfs.slot("fe.modules.brand").path.replace("<app>", app),
-  ].map((relative) => join(hfs.repoRoot, relative))
-  const key = candidates.join("|")
-  if (!themeCache.has(key)) {
-    const found = candidates.filter((candidate) => existsSync(candidate)).map((candidate) => readFileSync(candidate, "utf8"))
-    themeCache.set(key, found.length > 0 ? found.join("\n") : null)
-  }
-  return themeCache.get(key)
-}
-
-/** A class naming a token the theme never defines is a class that draws nothing. */
-export const noUnresolvedTokenClass = {
-  meta: {
-    type: "problem",
-    docs: { description: "A class naming a theme token resolves only when the theme defines it." },
-    schema: [],
-    messages: {
-      unresolved:
-        "`{{value}}` reads as a token this theme defines, and `{{variable}}` is defined nowhere in it. Tailwind emits the class, the element gets nothing, and both the union and the compiler stay happy - which is why this is the one dead class no type can catch. Define `{{variable}}` in the stylesheet, or name a token that exists.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context)) return {}
-    const theme = themeText(context)
-    // A reader that cannot find the stylesheet stays quiet rather than calling every token dead.
-    if (theme === null) return {}
-    // The visitor hands (node, text) in that order; reversing them here is how a rule reports the
-    // node as its message and the message as its node, and neither complains.
-    const check = (node, value) => {
-      for (const raw of String(value).split(/\s+/)) {
-        const bare = raw.replace(/^[a-z-]+:/, "").replace(/^!/, "")
-        for (const family of TOKEN_CLASS_FAMILIES) {
-          const match = family.pattern.exec(bare)
-          if (match === null) continue
-          if (TAILWIND_OWN_NAMES.has(match[1])) continue
-          const variable = family.variable(match[1])
-          if (theme.includes(variable)) continue
-          context.report({ node, messageId: "unresolved", data: { value: bare, variable } })
-        }
-      }
-    }
-    return classTextVisitors(context, check)
-  },
-}
-
-/** StarCi scale rules, bound to their knowledge owner. */
-export const rules = {
-  "no-fractional-step": noFractionalStep,
-  "no-hand-rolled-heading": noHandRolledHeading,
-  "no-unresolved-token-class": noUnresolvedTokenClass,
-}
-
-defineFamilyRules(rules, "knowledge/hfs/rules.yaml#R61")
-
-/** Every family scale rule is mandatory. */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))

package/typography.mjs

@@ -1,81 +0,0 @@
-import { defineFamilyRules } from "./lib/rule-contract.mjs"
-/**
- * The rule that holds `typography.md`.
- *
- * MOST OF THIS LAW IS A UNION, and what is left is one shape a type cannot see: a heading TAG
- * written by hand. The level union stops a fifth step being asked for; nothing in the type system
- * notices an `<h2>` in a file that never mentions the heading component at all.
- *
- * The rule's own twin lives in `tokens.mjs`: that one catches a heading assembled out of a large
- * size and a heavy weight on some other element. Between them they cover both ways a heading gets
- * hand-rolled - with the right tag and the wrong look, or the right look and no tag.
- */
-
-import { classOf, inSlot, isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs"
-
-/** The one owner that writes the heading tag: the component named `Heading` in the leaves layer of an app (slot `fe.components`; the owner name is the one name this rule keeps). */
-const isHeadingComponent = (context) => {
-  const owner = classOf(context)
-  return inSlot(context, "fe.components") && owner.kind === "leaves" && owner.bindings?.name === "Heading"
-}
-
-/** The tags a document outline is built from. */
-const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"])
-
-/** The deepest level the component draws; below this a page has nested too far. */
-const DEEPEST_LEVEL = 4
-
-/** Intrinsic (lowercase) tag name, or null for a component. */
-const tagName = (opening) => {
-  const name = opening && opening.name
-  if (!name || name.type !== "JSXIdentifier") return null
-  return name.name === name.name.toLowerCase() ? name.name : null
-}
-
-// -- TYPESET-1 · TYPESET-2 -------------------------------------------------------------------------------
-
-/** A heading comes from the component that owns its tag and its size as one decision. */
-export const noHeadingTagOutsideHeadingComponent = {
-  meta: {
-    type: "problem",
-    docs: { description: "Heading tags are written by the heading component, from a level." },
-    schema: [],
-    messages: {
-      tag:
-        "`<{{tag}}>` written here throws away the two facts the heading component exists to keep together: the tag a screen reader builds the document outline from, and the size a reader sees. Set separately they drift, and a screen's third-largest text becomes its first heading. Render the heading component with a level of {{level}}; one prop decides both, so they cannot disagree.",
-      tooDeep:
-        "`<{{tag}}>` is deeper than the scale goes: levels stop at {{deepest}}, because a fifth means the page has nested further than a reader can hold. That is a structure problem wearing a styling problem's clothes - flatten the section, then render the title with a level the scale has.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context) || isHeadingComponent(context)) return {}
-    return {
-      JSXOpeningElement(node) {
-        const tag = tagName(node)
-        if (!tag || !HEADING_TAGS.has(tag)) return
-        const level = Number(tag.slice(1))
-        if (level > DEEPEST_LEVEL) {
-          context.report({ node, messageId: "tooDeep", data: { tag, deepest: DEEPEST_LEVEL } })
-          return
-        }
-        context.report({ node, messageId: "tag", data: { tag, level } })
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "no-heading-tag-outside-heading-component": noHeadingTagOutsideHeadingComponent,
-}
-
-defineFamilyRules(rules, "knowledge/ui/presentation/font.yaml")
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * Exact: a tag name in a file that is not the component that owns it. A repository adopting this
- * with history should expect the deeper levels to report a structure problem rather than a styling
- * one, and those take longer to fix than the message suggests.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))

package/vendor-boundary.mjs

@@ -1,29 +0,0 @@
-import { defineFamilyRules } from "./lib/rule-contract.mjs"
-/**
- * Vendor ownership rules for the traditional React component hierarchy.
- *
- * Vendor primitives stay behind named leaves or mechanics branches. This boundary is deliberately
- * independent of product composition protocols; ordinary React children and props remain valid.
- */
-
-import { isComponentFile, kindOfFile, roleOfFile } from "@starci/eslint-canon-fe/lib/scope.mjs"
-
-/** The layers that may hold vendor mechanics: leaves and branches. */
-const MECHANICS_LAYERS = new Set(["leaves", "branches"])
-
-/** Keep HeroUI mechanics inside leaves, branches, and styling-owner modules (the `styles` file of a component). */
-export const vendorPrimitiveHasNamedOwner = {
-  meta: { type: "problem", docs: { description: "HeroUI primitives have a named component or styling owner." }, schema: [], messages: { owner: "Import HeroUI primitives from a named leaf, mechanics branch, or colocated classNames module." } },
-  create(context) {
-    if (!isComponentFile(context) || MECHANICS_LAYERS.has(kindOfFile(context)) || roleOfFile(context) === "styles") return {}
-    return { ImportDeclaration(node) { if (String(node.source.value) === "@heroui/react") context.report({ node, messageId: "owner" }) } }
-  },
-}
-
-export const rules = {
-  "vendor-primitive-has-named-owner": vendorPrimitiveHasNamedOwner,
-}
-
-defineFamilyRules(rules, "knowledge/hfs/rules.yaml#R93")
-
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))