@starci/eslint-grammar-core 0.13.0 → 0.14.0

package/dist/lib/app-shell.js

@@ -0,0 +1,185 @@
+import { attributeValue, stringOf } from "@starci/eslint-canon-fe/lib/ast.mjs";
+import { functionOf, importOf, unwrap, variableOf } from "@starci/eslint-canon-fe/lib/bindings.mjs";
+import { isNode } from "./types.js";
+const GRAMMAR_SOURCE = /^@starci\/grammar(?:\/|$)/;
+/** Grammar controls whose visible hit target belongs to the navbar band's size contract. */
+const BAR_CONTROLS = new Set(["Button", "IconButton", "Switch", "AvatarButton", "PlainPressable", "IdentityLockup", "SearchField", "Input", "TextField", "Select", "TextAction"]);
+const BAR_WRAPPERS = new Set(["GrammarRoot", "WorkspaceShell", "TopBar", "NavigationFeatureNav", "Region", "PageContainer", "NavLandmark", "Form", "Fieldset", "Field", "ButtonGroup", "DropdownMenu", "Popover", "Drawer", "Tooltip"]);
+const ACTION_PROPS = ["onPress", "onClick", "onAction", "onValueChange", "onSelectionChange", "onSelectedChange", "onChange", "onInputChange"];
+const INTERACTION_PROPS = new Set(["label", "value", "defaultValue", "selectedKey", "selectedKeys", "selectionMode", "href", ...ACTION_PROPS]);
+/** The name of a plain (non-namespaced) JSX attribute; null for a namespaced one. */
+const attributeName = (entry) => (entry.name.type === "JSXIdentifier" ? entry.name.name : null);
+/** Bar policy also counts labelled/value/selection/action field owners, so an extra control cannot vanish from the cluster. */
+export const isBarControl = (context, opening, name) => {
+    if (name !== null && BAR_CONTROLS.has(name))
+        return true;
+    if (!name || !/^[A-Z]/.test(name) || BAR_WRAPPERS.has(name))
+        return false;
+    if (opening.attributes.some((entry) => {
+        if (entry.type !== "JSXAttribute")
+            return false;
+        const attribute = attributeName(entry);
+        return attribute !== null && INTERACTION_PROPS.has(attribute);
+    }))
+        return true;
+    return [...INTERACTION_PROPS].some((prop) => propOf(context, opening, prop).value !== null);
+};
+/** The identifier name of a member property, or undefined for any other kind of key. */
+const memberPropertyName = (property) => ("name" in property && typeof property.name === "string" ? property.name : undefined);
+/** A literal or constant's initializer, without type-only wrappers. */
+export const resolveLocal = (context, expression, seen = new Set()) => {
+    const node = expression && isNode(expression) ? unwrap(expression) : expression;
+    if (node?.type === "MemberExpression")
+        return resolveMember(context, node, seen);
+    if (node?.type === "CallExpression")
+        return resolveCall(context, node, seen);
+    if (node?.type !== "Identifier" && node?.type !== "JSXIdentifier" || seen.has(node))
+        return node;
+    const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable");
+    if (!definition || definition.parent?.kind !== "const")
+        return node;
+    seen.add(node);
+    return resolveLocal(context, initializerOf(definition.node, node), seen);
+};
+const resolveCall = (context, node, seen) => {
+    if (seen.has(node))
+        return node;
+    seen.add(node);
+    const fn = functionOf(context, realNode(resolveLocal(context, node.callee, seen)));
+    if (!fn)
+        return node;
+    if (fn.body.type !== "BlockStatement")
+        return resolveLocal(context, fn.body, seen);
+    if (fn.body.body.some((statement) => !["VariableDeclaration", "ReturnStatement"].includes(statement.type)))
+        return node;
+    const returned = fn.body.body.find((statement) => statement.type === "ReturnStatement");
+    return returned ? resolveLocal(context, returned.argument, seen) : node;
+};
+/** A resolved value as a parsed node; a synthesized member stands for no function or value of the tree. */
+export const realNode = (value) => (value && isNode(value) ? value : null);
+const resolveMember = (context, node, seen) => {
+    const key = node.computed ? stringOf(node.property) : memberPropertyName(node.property);
+    if (!key)
+        return node;
+    const property = objectValue(context, node.object, key, seen);
+    return property.known && property.value !== null ? resolveLocal(context, property.value, seen) : node;
+};
+const initializerOf = (declaration, node) => {
+    if (declaration.id.type === "ObjectPattern") {
+        const property = declaration.id.properties.find((entry) => entry.type === "Property" && entry.value.type === "Identifier" && entry.value.name === node.name);
+        if (!property || property.type !== "Property")
+            return node;
+        return { type: "MemberExpression", object: declaration.init, property: property.key, computed: property.computed };
+    }
+    return declaration.init;
+};
+/** The imported Grammar component's name; aliases and namespace imports keep their identity. */
+export const grammarName = (context, opening) => {
+    const name = opening.name;
+    if (name.type === "JSXIdentifier") {
+        const canonical = expressionName(context, name);
+        if (canonical)
+            return canonical;
+        return variableOf(context, name)?.defs.length ? null : name.name;
+    }
+    if (name.type !== "JSXMemberExpression" || name.object.type !== "JSXIdentifier")
+        return null;
+    return expressionName(context, { type: "MemberExpression", object: name.object, property: name.property, computed: false }) ?? null;
+};
+const expressionName = (context, expression) => {
+    const resolved = resolveLocal(context, expression);
+    if (resolved?.type === "MemberExpression") {
+        return namespaceName(context, resolved.object, resolved.computed ? stringOf(resolved.property) : memberPropertyName(resolved.property));
+    }
+    if (resolved?.type !== "Identifier" && resolved?.type !== "JSXIdentifier")
+        return null;
+    const imported = importOf(context, resolved);
+    return imported && GRAMMAR_SOURCE.test(imported.source) ? imported.imported : null;
+};
+const namespaceName = (context, expression, property) => {
+    const object = resolveLocal(context, expression);
+    if (object?.type !== "Identifier" && object?.type !== "JSXIdentifier")
+        return null;
+    const imported = importOf(context, object);
+    return imported && GRAMMAR_SOURCE.test(imported.source) ? property : null;
+};
+/** The value of a named property of an object expression: `known` is false when a spread or condition hides it. */
+const objectValue = (context, expression, name, seen = new Set()) => {
+    const node = resolveLocal(context, expression);
+    if (node?.type === "ConditionalExpression")
+        return conditionalObjectValue(context, node, name, seen);
+    if (node?.type !== "ObjectExpression" || seen.has(node))
+        return { known: false, value: null };
+    seen.add(node);
+    let result = { known: true, value: null };
+    for (const property of node.properties) {
+        if (property.type === "SpreadElement") {
+            const spread = objectValue(context, property.argument, name, seen);
+            if (!spread.known || spread.value !== null)
+                result = spread;
+        }
+        else if (!property.computed && propertyKeyText(property.key) === name) {
+            result = { known: true, value: property.value };
+        }
+    }
+    return result;
+};
+/** The text a property key spells: an identifier's name or a string literal's value; null for any other key. */
+export const propertyKeyText = (key) => {
+    if (key.type === "Identifier")
+        return key.name;
+    if (key.type === "Literal" && typeof key.value === "string")
+        return key.value;
+    return null;
+};
+const conditionalObjectValue = (context, node, name, seen) => {
+    if (seen.has(node))
+        return { known: false, value: null };
+    const visited = new Set(seen).add(node);
+    const values = [node.consequent, node.alternate].map((branch) => objectValue(context, branch, name, new Set(visited)));
+    return { known: values.every((value) => value.known && value.value === null), value: null };
+};
+/** The effective prop, respecting JSX spread order; unknown later spreads cannot prove a value. */
+export const propOf = (context, opening, name) => {
+    let result = { known: true, value: null };
+    for (const entry of opening.attributes) {
+        if (entry.type === "JSXSpreadAttribute") {
+            const spread = objectValue(context, entry.argument, name);
+            if (!spread.known || spread.value !== null)
+                result = spread;
+        }
+        else if (entry.name.name === name)
+            result = { known: true, value: attributeValue(entry), present: true };
+    }
+    return result;
+};
+/** A statically proven string prop, or null for missing/unknown values. */
+export const textProp = (context, opening, name) => {
+    const prop = propOf(context, opening, name);
+    return prop.known ? stringOf(realNode(resolveLocal(context, prop.value))) : null;
+};
+/** The source spelling is semantic evidence for an icon or action whose translated label is dynamic. */
+export const semanticText = (context, opening) => {
+    const values = ["source", "icon", "label", "aria-label", "id", ...ACTION_PROPS].map((name) => {
+        const prop = propOf(context, opening, name);
+        return prop.value ? context.sourceCode.getText(prop.value) : "";
+    });
+    return values.join(" ");
+};
+/** The right-cluster role and the Grammar kind that must draw it. */
+export const clusterRole = (context, opening, name) => {
+    if (name === "Switch")
+        return "theme";
+    if (name === "AvatarButton")
+        return "account";
+    const text = semanticText(context, opening);
+    if (/language|locale|translate/i.test(text))
+        return "language";
+    if (/notification|bell/i.test(text))
+        return "notifications";
+    if (/account|avatar|profile/i.test(text))
+        return "account";
+    if (/theme|darkmode|color.?mode/i.test(text))
+        return "theme";
+    return null;
+};

package/dist/lib/rule-contract.d.ts

@@ -0,0 +1,12 @@
+import type { Rule } from "eslint";
+import type { RuleDefinition } from "./types.ts";
+/** The ordered ownership test that governs every Grammar-specific lint rule. */
+export declare const RULE_OWNERSHIP = "knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP";
+/**
+ * A rule written against the typescript-eslint tree, as the ESLint rule module that publishes it. Every rule of this
+ * package is linted by `@typescript-eslint/parser` (`coreGrammarConfig` sets it), so the context it receives and the
+ * visitor it returns carry that parser's node types; this is the one place that states so to ESLint's declarations.
+ */
+export declare const defineRule: (definition: RuleDefinition) => Rule.RuleModule;
+/** Attach the governing ownership rule and the rule's behavioral source without changing enforcement. */
+export declare const defineFamilyRules: (rules: Readonly<Record<string, Rule.RuleModule>>, knowledge: string) => Readonly<Record<string, Rule.RuleModule>>;

package/dist/lib/rule-contract.js

@@ -0,0 +1,23 @@
+/** The ordered ownership test that governs every Grammar-specific lint rule. */
+export const RULE_OWNERSHIP = "knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP";
+/**
+ * A rule written against the typescript-eslint tree, as the ESLint rule module that publishes it. Every rule of this
+ * package is linted by `@typescript-eslint/parser` (`coreGrammarConfig` sets it), so the context it receives and the
+ * visitor it returns carry that parser's node types; this is the one place that states so to ESLint's declarations.
+ */
+export const defineRule = (definition) => ({
+    meta: definition.meta,
+    create: (context) => definition.create(context),
+});
+/** Attach the governing ownership rule and the rule's behavioral source without changing enforcement. */
+export const defineFamilyRules = (rules, knowledge) => {
+    for (const rule of Object.values(rules)) {
+        const meta = rule.meta;
+        if (meta === undefined)
+            throw new Error("A family rule declares its meta");
+        const source = meta.docs?.url ?? knowledge;
+        const docs = { ...meta.docs, url: source, knowledge: source, ownership: RULE_OWNERSHIP };
+        meta.docs = docs;
+    }
+    return rules;
+};

package/dist/lib/status-tones.generated.d.ts

@@ -0,0 +1,2 @@
+/** The status tones of the grammar: each has a solid pair and a soft pair (`--<tone>-soft`, `--<tone>-soft-foreground`). */
+export declare const STATUS_TONES: readonly string[];

package/dist/lib/status-tones.generated.js

@@ -0,0 +1,8 @@
+// Generated by packages/stylelint-canon/src/lib/write-vocabulary.ts from packages/grammar/src. Do not edit: run `npm run vocabulary` in packages/stylelint-canon.
+/** The status tones of the grammar: each has a solid pair and a soft pair (`--<tone>-soft`, `--<tone>-soft-foreground`). */
+export const STATUS_TONES = [
+    "success",
+    "warning",
+    "danger",
+    "info",
+];

package/dist/lib/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The AST and rule-context types this package's rules are written against.
+ *
+ * Every rule runs under `@typescript-eslint/parser` (`coreGrammarConfig` sets it), so the nodes it receives are the
+ * typescript-eslint tree (`TSESTree`: ESTree plus JSX and TypeScript nodes, each with its `parent`). ESLint's own
+ * declarations describe plain ESTree, so the rule context is restated here with the node type the parser produces.
+ */
+import type { AST, Rule, Scope } from "eslint";
+import type { TSESTree } from "@typescript-eslint/types";
+/** Any node of the typescript-eslint tree. */
+export type Node = TSESTree.Node;
+/** The function-shaped nodes the readers follow. */
+export type FunctionNode = TSESTree.FunctionDeclaration | TSESTree.FunctionExpression | TSESTree.ArrowFunctionExpression;
+/** An identifier-like name a scope lookup accepts. */
+export type NameNode = TSESTree.Identifier | TSESTree.JSXIdentifier;
+/** What the scope manager records for a declaration: only the definition kinds the readers inspect are named. */
+export type ScopeDefinition = {
+    readonly type: "Variable";
+    readonly node: TSESTree.VariableDeclarator;
+    readonly parent: TSESTree.VariableDeclaration;
+} | {
+    readonly type: "ImportBinding";
+    readonly node: TSESTree.ImportSpecifier | TSESTree.ImportDefaultSpecifier | TSESTree.ImportNamespaceSpecifier;
+    readonly parent: TSESTree.ImportDeclaration;
+} | {
+    readonly type: "FunctionName";
+    readonly node: TSESTree.FunctionDeclaration | TSESTree.FunctionExpression;
+    readonly parent: null;
+} | {
+    readonly type: "Parameter" | "ClassName" | "CatchClause" | "TSEnumName" | "TSModuleName" | "Type" | "ImportEqualsBinding" | "ImplicitGlobalVariable";
+    readonly node: Node;
+    readonly parent: Node | null;
+};
+/** A scope-manager variable: its name and where it is declared. */
+export interface ScopeVariable {
+    readonly name: string;
+    readonly defs: readonly ScopeDefinition[];
+}
+/** The source-code object of a linted (or independently parsed) file, with the parser's node type. */
+export interface SourceView {
+    readonly ast: AST.Program;
+    readonly text: string;
+    readonly visitorKeys: Readonly<Record<string, readonly string[] | undefined>>;
+    getText(node?: Node): string;
+    getScope(node: Node): Scope.Scope;
+    getCommentsBefore(node: Node): readonly SourceComment[];
+}
+/** A comment of the linted file: `Block` for `/* *\/`, `Line` for `//`. */
+export interface SourceComment {
+    readonly type: "Block" | "Line";
+    readonly value: string;
+    readonly range: readonly [number, number];
+}
+/** The parts of a rule context a reader needs; an independently parsed file offers exactly these. */
+export interface ReaderContext {
+    readonly filename: string;
+    readonly id?: string;
+    readonly settings: Rule.RuleContext["settings"];
+    readonly sourceCode: SourceView;
+    getFilename?(): string;
+}
+/** An independently parsed file: the reader context plus the typescript-eslint tree its parse produced. */
+export interface ParsedContext extends ReaderContext {
+    readonly program: TSESTree.Program;
+}
+/** A finding a rule reports. */
+export interface ReportDescriptor {
+    readonly node: Node;
+    readonly messageId: string;
+    readonly data?: Readonly<Record<string, unknown>>;
+    readonly fix?: (fixer: Rule.RuleFixer) => Rule.Fix | null;
+}
+/** The rule context of a rule that reports. */
+export interface Context extends ReaderContext {
+    getFilename(): string;
+    report(descriptor: ReportDescriptor): void;
+}
+/** The visitor of a rule: a handler per node type, each receiving that node type. */
+export type Listener = {
+    [K in Node["type"]]?: (node: Extract<Node, {
+        type: K;
+    }>) => void;
+};
+/** A rule whose `create` is written against the parser's node type. */
+export interface RuleDefinition {
+    readonly meta: Rule.RuleMetaData;
+    create(context: Context): Listener;
+}
+/**
+ * A member access the readers synthesize for a destructured binding (`const { A: B } = ns` reads as `ns.A`) or a JSX member
+ * name (`<ns.A />`): it has no source position and no parent, so it is not a node of the parsed tree.
+ */
+export interface SyntheticMember {
+    readonly type: "MemberExpression";
+    readonly object: Node | null;
+    readonly property: Node;
+    readonly computed: boolean;
+}
+/** What resolving a local expression yields: a real node, or a synthesized member access. */
+export type Resolved = Node | SyntheticMember;
+/** True for a node of the parsed tree; a synthesized member has no source range. */
+export declare const isNode: (value: Resolved) => value is Node;
+/** The opened slot manifest and resolver of an app or side folder (the runtime's `openHfs` result): what the layout loader reads. */
+export interface OpenedHfs {
+    readonly repo: {
+        readonly profile: string;
+        readonly side?: string | null;
+        readonly apps: readonly {
+            readonly name: string;
+            readonly kind: string;
+        }[];
+    };
+}

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+/** True for a node of the parsed tree; a synthesized member has no source range. */
+export const isNode = (value) => "range" in value;

package/dist/lib/why.d.ts

@@ -0,0 +1,8 @@
+/** Failure-code guidance for the selected Grammar family contract. */
+/** One failure code with its explanation and the way to fix it. */
+export interface WhyEntry {
+    readonly code: string;
+    readonly en: string;
+    readonly fix: string;
+}
+export declare const why: Record<string, WhyEntry>;

package/dist/lib/why.js

@@ -0,0 +1,42 @@
+export const why = {
+    "app-shell-frame": {
+        code: "FE_APP_SHELL_FRAME",
+        en: "The app frame must use Grammar WorkspaceShell with its fixed viewport.",
+        fix: "Compose WorkspaceShell viewport=\"fixed\" and supply its header, navigation and primary slots.",
+    },
+    "chip-label-starts-uppercase": {
+        code: "FE_CHIP_LABEL_CASE",
+        en: "A StatusDot or Badge label in `<file>` starts with a lowercase letter.",
+        fix: "Start the label with an uppercase letter (`Running`, not `running`); the rule fixes a literal label in place.",
+    },
+    "navbar-cluster": {
+        code: "FE_NAVBAR_CLUSTER",
+        en: "Navbar action component kinds or order differ from the app-shell canon.",
+        fix: "Compose Language IconButton, theme Switch, notification IconButton and account AvatarButton in that order.",
+    },
+    "navbar-control-size": {
+        code: "FE_NAVBAR_CONTROL_SIZE",
+        en: "A navbar control does not use Grammar's shared control height.",
+        fix: "Set size=\"control\" on every visible bar control.",
+    },
+    "no-navbar-create": {
+        code: "FE_NAVBAR_CREATE",
+        en: "A create action is composed into the global navbar.",
+        fix: "Move the create action to the page that owns it.",
+    },
+    "no-raw-structural-element": {
+        code: "FE_NATIVE_FORM_CONTROL",
+        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-shell-bottom-tabs": {
+        code: "FE_APP_SHELL_BOTTOM_TABS",
+        en: "Bottom tab navigation replaces the required mobile sidebar drawer.",
+        fix: "Use WorkspaceShell navigationDrawer and Sidebar presentation=\"drawer\".",
+    },
+    "status-text-uses-soft-foreground": {
+        code: "FE_STYLE_TOKEN_ONLY",
+        en: "`<file>` paints text or an icon with a solid status tone (`<what>`, e.g. `text-success`). A solid tone is a background colour; used as a text colour it reads below 4.5:1 on the page background.",
+        fix: "Switch to the soft pair: `text-<tone>-soft-foreground` (with `bg-<tone>-soft` when it sits on a light surface); a solid tone is used only with `bg-<tone>` and `text-<tone>-foreground`.",
+    },
+};

package/dist/menu-entries.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The menu entries a product hands to Grammar's `DropdownMenu`.
+ *
+ * HeroUI colours a destructive menu item through its `danger` variant, which Grammar exposes as `tone: "danger"`. An entry the app
+ * forgets to tone reads like any other command: sign out and delete sit beside "Settings" in the same ink, and the one click that
+ * cannot be taken back gets no mark. The decision is the entry's meaning, so it is checked where the entry is written: an entry whose
+ * id or label says it signs out, deletes, removes, leaves or revokes carries `tone: "danger"`.
+ *
+ * The terms are this canon's own list, English and Vietnamese. They are compared as whole words after the text is lower-cased, split
+ * at `-`, `_` and camelCase, and stripped of diacritics (the Vietnamese for "sign out" with its tone marks is `dang xuat`), so `signOut`, `sign-out`,
+ * `Sign out` and the tone-marked Vietnamese spelling are one term.
+ *
+ * WHERE IT LOOKS. A menu entry is an object literal in the `entries` attribute of a `DropdownMenu`, or in a declaration typed as
+ * `DropdownMenuEntry`, `DropdownMenuItem` or `DropdownMenuSection` (an array of them too), including the `items` of a section and the
+ * `submenu` of an item. Anything it cannot see through (a spread, a call) it leaves alone: the rule refuses to guess.
+ */
+import type { Rule } from "eslint";
+/** The text lower-cased, split at separators and camelCase, with diacritics stripped. */
+export declare const normalizeText: (text: string) => string;
+/** True when the id or label text names a destructive command. */
+export declare const isDestructiveText: (text: string) => boolean;
+/** A destructive menu entry carries `tone: "danger"`. */
+export declare const destructiveMenuEntryNeedsDangerTone: Rule.RuleModule;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Record<string, Rule.RuleModule>;
+/** Every rule is an error. */
+export declare const recommended: Record<string, "error">;

package/dist/menu-entries.js

@@ -0,0 +1,142 @@
+/**
+ * The menu entries a product hands to Grammar's `DropdownMenu`.
+ *
+ * HeroUI colours a destructive menu item through its `danger` variant, which Grammar exposes as `tone: "danger"`. An entry the app
+ * forgets to tone reads like any other command: sign out and delete sit beside "Settings" in the same ink, and the one click that
+ * cannot be taken back gets no mark. The decision is the entry's meaning, so it is checked where the entry is written: an entry whose
+ * id or label says it signs out, deletes, removes, leaves or revokes carries `tone: "danger"`.
+ *
+ * The terms are this canon's own list, English and Vietnamese. They are compared as whole words after the text is lower-cased, split
+ * at `-`, `_` and camelCase, and stripped of diacritics (the Vietnamese for "sign out" with its tone marks is `dang xuat`), so `signOut`, `sign-out`,
+ * `Sign out` and the tone-marked Vietnamese spelling are one term.
+ *
+ * WHERE IT LOOKS. A menu entry is an object literal in the `entries` attribute of a `DropdownMenu`, or in a declaration typed as
+ * `DropdownMenuEntry`, `DropdownMenuItem` or `DropdownMenuSection` (an array of them too), including the `items` of a section and the
+ * `submenu` of an item. Anything it cannot see through (a spread, a call) it leaves alone: the rule refuses to guess.
+ */
+import { propertyKeyText, resolveLocal } from "./lib/app-shell.js";
+import { stringOf } from "@starci/eslint-canon-fe/lib/ast.mjs";
+import { isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs";
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+import { isNode } from "./lib/types.js";
+/** The English terms of a destructive entry. */
+const DESTRUCTIVE_TERMS_EN = Object.freeze([
+    "sign out", "log out", "logout", "signout",
+    "delete", "remove", "erase", "destroy", "discard", "purge",
+    "leave workspace", "leave team", "leave group", "leave organization", "leave project", "leave channel", "leave course", "revoke", "deactivate", "disconnect", "unlink", "unsubscribe", "terminate",
+    "close account", "cancel subscription", "cancel plan",
+]);
+/** The Vietnamese terms, written without diacritics (the text is compared after the diacritics are stripped). */
+const DESTRUCTIVE_TERMS_VI = Object.freeze([
+    "dang xuat", "xoa", "xoa bo", "go bo", "loai bo", "roi khoi", "roi nhom", "thu hoi",
+    "vo hieu hoa", "ngat ket noi", "huy dang ky", "huy goi", "cham dut", "dong tai khoan",
+]);
+/** A destructive term as a whole word or phrase of the normalized text. */
+const DESTRUCTIVE_PATTERN = new RegExp(String.raw `(?:^|\s)(?:${[...DESTRUCTIVE_TERMS_EN, ...DESTRUCTIVE_TERMS_VI].map((term) => term.replaceAll(" ", String.raw `\s+`)).join("|")})(?=\s|$)`);
+/** The text lower-cased, split at separators and camelCase, with diacritics stripped. */
+export const normalizeText = (text) => text
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replaceAll(/[-_./:]+/g, " ")
+    .toLowerCase()
+    .replaceAll("\u0111", "d")
+    .normalize("NFD")
+    .replaceAll(/\p{M}+/gu, "")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+/** True when the id or label text names a destructive command. */
+export const isDestructiveText = (text) => DESTRUCTIVE_PATTERN.test(normalizeText(text));
+const MENU_TYPES = new Set(["DropdownMenuEntry", "DropdownMenuItem", "DropdownMenuSection"]);
+/** The value node of the property called `name` in an object literal, or null. */
+const propertyValue = (object, name) => object.properties.find((entry) => entry.type === "Property" && !entry.computed && propertyKeyText(entry.key) === name)?.value ?? null;
+/** The element type of an array type (`T[]`, `readonly T[]`, `ReadonlyArray<T>`), else the type itself. */
+const elementTypeOf = (type) => {
+    if (type.type === "TSTypeOperator")
+        return type.typeAnnotation ? elementTypeOf(type.typeAnnotation) : type;
+    if (type.type === "TSArrayType")
+        return type.elementType;
+    const isArrayName = type.type === "TSTypeReference" && type.typeName.type === "Identifier" && (type.typeName.name === "ReadonlyArray" || type.typeName.name === "Array");
+    return isArrayName ? type.typeArguments?.params[0] ?? type : type;
+};
+/** True when the type annotation names a menu entry type or an array of one. */
+const isMenuType = (annotation) => {
+    const type = annotation?.typeAnnotation;
+    if (!type)
+        return false;
+    const element = elementTypeOf(type);
+    return element.type === "TSTypeReference" && element.typeName.type === "Identifier" && MENU_TYPES.has(element.typeName.name);
+};
+/** Every possible value must prove danger; an unresolved value cannot mark a destructive action. */
+const provesDangerTone = (context, expression, seen = new Set()) => {
+    const node = resolveLocal(context, expression);
+    if (!node || seen.has(node))
+        return false;
+    if (node.type !== "ConditionalExpression")
+        return isNode(node) && stringOf(node) === "danger";
+    const visited = new Set(seen).add(node);
+    return [node.consequent, node.alternate].every((branch) => provesDangerTone(context, branch, visited));
+};
+/** Report an entry (an object literal), then walk the `items` of a section and the `submenu` of an item. */
+function visitEntries(context, node, report) {
+    if (!node)
+        return;
+    if (node.type === "ArrayExpression") {
+        for (const element of node.elements)
+            visitEntries(context, element, report);
+        return;
+    }
+    if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") {
+        visitEntries(context, node.expression, report);
+        return;
+    }
+    if (node.type !== "ObjectExpression")
+        return;
+    const kind = stringOf(propertyValue(node, "kind"));
+    if (kind === "section") {
+        visitEntries(context, propertyValue(node, "items"), report);
+        return;
+    }
+    const text = [stringOf(propertyValue(node, "id")), stringOf(propertyValue(node, "label"))].filter((value) => value !== null);
+    const tone = propertyValue(node, "tone");
+    const toned = provesDangerTone(context, tone);
+    const destructive = text.find(isDestructiveText);
+    if (!toned && destructive !== undefined)
+        report(node, destructive);
+    visitEntries(context, propertyValue(node, "submenu"), report);
+}
+/** A destructive menu entry carries `tone: "danger"`. */
+export const destructiveMenuEntryNeedsDangerTone = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A menu entry whose id or label signs out, deletes, removes, leaves or revokes carries `tone: \"danger\"`." },
+        schema: [],
+        messages: {
+            tone: "The menu entry `{{text}}` is destructive but has no `tone: \"danger\"`. HeroUI colours the label and glyph of a danger item so the one click that cannot be taken back is marked; without the tone it reads like \"Settings\". Add `tone: \"danger\"` to the entry.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        const report = (node, text) => context.report({ node, messageId: "tone", data: { text } });
+        return {
+            JSXAttribute(node) {
+                if (node.name.type !== "JSXIdentifier" || node.name.name !== "entries")
+                    return;
+                const element = node.parent?.name;
+                if (element?.type !== "JSXIdentifier" || element.name !== "DropdownMenu")
+                    return;
+                visitEntries(context, node.value?.type === "JSXExpressionContainer" ? node.value.expression : null, report);
+            },
+            VariableDeclarator(node) {
+                if (isMenuType(node.id.typeAnnotation))
+                    visitEntries(context, node.init, report);
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "destructive-menu-entry-needs-danger-tone": destructiveMenuEntryNeedsDangerTone,
+};
+defineFamilyRules(rules, "knowledge/hfs/rules.yaml#R93");
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]));

package/dist/status-colors.d.ts

@@ -0,0 +1,13 @@
+import type { Rule } from "eslint";
+/** Every solid-tone text class in one class string, as `{ token, family, tone }`. */
+export declare const solidTextClasses: (text: string) => {
+    token: string;
+    family: string;
+    tone: string;
+}[];
+/** Text or an icon painted with a solid status tone is not readable at the contrast the soft pair was built for. */
+export declare const statusTextUsesSoftForeground: 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">;