@starci/eslint-grammar-core 0.13.0 → 0.14.0

package/dist/status-colors.js

@@ -0,0 +1,143 @@
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+/**
+ * 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.ts`, 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.js";
+/** 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));
+    const family = match?.[1];
+    const tone = match?.[2];
+    return family !== undefined && tone !== undefined ? [{ token, family, tone }] : [];
+});
+/** 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 = defineRule({
+    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/dist/tokens.d.ts

@@ -0,0 +1,11 @@
+import type { Rule } from "eslint";
+/** A fractional step is off the ladder, not between two rungs. */
+export declare const noFractionalStep: Rule.RuleModule;
+/** Large text plus a heavy weight is a heading, and headings come from the component that owns both. */
+export declare const noHandRolledHeading: Rule.RuleModule;
+/** A class naming a token the theme never defines is a class that draws nothing. */
+export declare const noUnresolvedTokenClass: Rule.RuleModule;
+/** StarCi scale rules, bound to their knowledge owner. */
+export declare const rules: Record<string, Rule.RuleModule>;
+/** Every family scale rule is mandatory. */
+export declare const recommended: Record<string, "error">;

package/dist/tokens.js

@@ -0,0 +1,166 @@
+/** 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, defineRule } from "./lib/rule-contract.js";
+/**
+ * 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 = defineRule({
+    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 = defineRule({
+    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();
+/** The path template of a slot the manifest must declare. */
+const slotPath = (hfs, id) => {
+    const slot = hfs.slot(id);
+    if (slot === null)
+        throw new Error(`The slot manifest declares no slot ${id}`);
+    return slot.path;
+};
+const themeText = (context) => {
+    const hfs = hfsOf(context);
+    const app = classOf(context).bindings?.app;
+    if (app === undefined)
+        return null;
+    const candidates = [
+        join(slotPath(hfs, "fe.route").replace("<app>", app), "globals.css"),
+        slotPath(hfs, "fe.modules.brand").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) ?? null;
+};
+/** A class naming a token the theme never defines is a class that draws nothing. */
+export const noUnresolvedTokenClass = defineRule({
+    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;
+                    const name = match[1] ?? "";
+                    if (TAILWIND_OWN_NAMES.has(name))
+                        continue;
+                    const variable = family.variable(name);
+                    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/dist/typography.d.ts

@@ -0,0 +1,13 @@
+import type { Rule } from "eslint";
+/** A heading comes from the component that owns its tag and its size as one decision. */
+export declare const noHeadingTagOutsideHeadingComponent: Rule.RuleModule;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Record<string, Rule.RuleModule>;
+/**
+ * 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 declare const recommended: Record<string, "error">;

package/dist/typography.js

@@ -0,0 +1,72 @@
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+/**
+ * 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.ts`: 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 = defineRule({
+    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/dist/vendor-boundary.d.ts

@@ -0,0 +1,5 @@
+import type { Rule } from "eslint";
+/** Keep HeroUI mechanics inside leaves, branches, and styling-owner modules (the `styles` file of a component). */
+export declare const vendorPrimitiveHasNamedOwner: Rule.RuleModule;
+export declare const rules: Record<string, Rule.RuleModule>;
+export declare const recommended: Record<string, "error">;

package/dist/vendor-boundary.js

@@ -0,0 +1,25 @@
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+/**
+ * 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 = defineRule({
+    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"]));

package/docs/chip-label.md

@@ -0,0 +1,30 @@
+# Chip labels start uppercase
+
+Law module: `chip-label.ts`. Catalogue: R322 FE_CHIP_LABEL_CASE.
+
+A status chip (`StatusDot` with text, a `Badge`, dot or not) is a label read at a glance beside the thing it qualifies, so it starts with an uppercase letter in every language, Vietnamese included. StatusDot capitalises the text it renders; the rule holds the literal where the source writes it.
+
+Every rule below is an error in `coreGrammarConfig`; none can be switched off or suppressed inline.
+
+## `starci-grammar/chip-label-starts-uppercase`
+
+The children of a `StatusDot` or `Badge` that the source states literally (JSX text, a string literal, a template literal with no expression, and every branch of a conditional or logical expression made of them) do not start with a lowercase letter. The fix uppercases the first letter in place. Text the source cannot show (a translation call, a variable, a template with an expression), a label that starts with a digit or a symbol, and an uncased script are not judged.
+
+**Invalid** (`src/components/blocks/RunList/component.tsx`)
+
+```tsx
+<StatusDot tone="success">running</StatusDot>
+<Badge tone="warning" isDot>{"queued"}</Badge>
+```
+
+**Valid** (`src/components/blocks/RunList/component.tsx`)
+
+```tsx
+<StatusDot tone="success">Running</StatusDot>
+<Badge tone="warning" isDot>{t("status.queued")}</Badge>
+<Badge>3 failed</Badge>
+```
+
+**Finding code:** `FE_CHIP_LABEL_CASE`
+
+Rule ownership: [FE-RULE-OWNERSHIP](../../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).

package/docs/grammar-boundary.md

@@ -1,6 +1,6 @@
 # Grammar boundary
 
-Law module: `grammar-boundary.mjs`. Catalogue: R62 FE_NATIVE_FORM_CONTROL (the grammar owns the element).
+Law module: `grammar-boundary.ts`. Catalogue: R62 FE_NATIVE_FORM_CONTROL (the grammar owns the element).
 
 Page structure and text are composed from `@starci/grammar` (or the repository's `<family>-ui` package), not drawn as raw HTML.
 

package/docs/status-colors.md

@@ -1,8 +1,8 @@
 # Status colours: text and icons take the soft pair
 
-Law module: `status-colors.mjs`. Catalogue: R61 FE_STYLE_TOKEN_ONLY (the class-name half of the soft-pair contrast obligation; the brand layer's own contrast is `starci/status-contrast` of @starci/stylelint-canon).
+Law module: `status-colors.ts`. Catalogue: R61 FE_STYLE_TOKEN_ONLY (the class-name half of the soft-pair contrast obligation; the brand layer's own contrast is `starci/status-contrast` of @starci/stylelint-canon).
 
-A status tone has two faces. The solid tone (`--success`) is a fill, with `--success-foreground` ink on it. A status shown as text or as an icon takes the soft pair, the way a HeroUI flat Chip does: `--success-soft-foreground` ink, on `--success-soft` when it sits on a tint. The soft pair is what the brand layer is checked to make readable (3:1 on the tint and on the page); the solid tone reads 3.8:1 or worse on white, so as a text colour it fails. The tones are the grammar's status tones (`success`, `warning`, `danger`, `info`), read from `lib/status-tones.generated.mjs`, which is generated from the grammar with the stylelint vocabulary.
+A status tone has two faces. The solid tone (`--success`) is a fill, with `--success-foreground` ink on it. A status shown as text or as an icon takes the soft pair, the way a HeroUI flat Chip does: `--success-soft-foreground` ink, on `--success-soft` when it sits on a tint. The soft pair is what the brand layer is checked to make readable (3:1 on the tint and on the page); the solid tone reads 3.8:1 or worse on white, so as a text colour it fails. The tones are the grammar's status tones (`success`, `warning`, `danger`, `info`), read from `lib/status-tones.generated.ts`, which is generated from the grammar with the stylelint vocabulary.
 
 Every rule below is an error in `coreGrammarConfig`; none can be switched off or suppressed inline.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-grammar-core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "ESLint rules for the core Grammar's component, token and composition contracts.",
   "keywords": [
     "eslint",
@@ -23,20 +23,17 @@
   "private": false,
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "import": "./index.mjs"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
-  "main": "./index.mjs",
-  "types": "./index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "files": [
-    "LICENSE",
-    "*.mjs",
-    "*.d.ts",
-    "lib/*.mjs",
+    "dist",
     "runtime/**",
     "docs/*.md",
-    "!*.spec.mjs",
+    "LICENSE",
     "CHANGELOG.md",
     "README.md"
   ],
@@ -44,9 +41,9 @@
     "node": ">=22"
   },
   "peerDependencies": {
+    "@starci/eslint-canon-fe": "9.3.0",
     "eslint": ">=9",
-    "typescript": ">=5.9",
-    "@starci/eslint-canon-fe": "9.2.0"
+    "typescript": ">=5.9"
   },
   "dependencies": {
     "@typescript-eslint/parser": "^8.70.0"
@@ -55,12 +52,18 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test \"*.spec.mjs\""
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run typecheck && node --test \"src/**/*.spec.ts\""
   },
   "devDependencies": {
+    "@starci/eslint-canon-fe": "file:../eslint-canon-fe",
+    "@starci/tsconfig": "file:../tsconfig",
+    "@types/node": "24.19.2",
+    "@typescript-eslint/types": "^8.70.0",
     "eslint": "^9.18.0",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "typescript": "^6.0.3",
-    "@starci/eslint-canon-fe": "file:../eslint-canon-fe"
+    "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.13.0
+    version: 0.14.0
     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.57
+    version: 3.5.0
     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.2.0
+    version: 9.3.0
     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.13.0
+    version: 0.14.0
     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.13.0
+    version: 0.14.0
     group: starci
     install: registry
     side: fe
@@ -97,19 +97,20 @@ pins:
     side: be
     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
+  'starci-harness':
+    version: 1.1.0-alpha.1
     group: starci
     install: registry
     side: both
-    why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
+    source: cli/package.json
+    why: 'the one StarCi command line (bins starci and starci-harness): a product repository installs it for starci app, which it runs in-process through its exact @starci/hfs dependency, and its codegen loads starci-harness/input-bounds.'
   '@starci/hfs':
-    version: 4.8.0
+    version: 4.9.0
     group: starci
     install: registry
     side: both
     source: packages/hfs/package.json
-    why: 'the transitive app implementation used by @starci/cli; it carries the generated runtime slice read by starci app commands.'
+    why: 'the app implementation starci-harness runs for starci app; it carries the generated runtime slice read by starci app commands.'
   # --- tooling
   typescript:
     version: 5.9.3