@starci/eslint-grammar-core 0.13.0 → 0.15.0

package/dist/icon.js

@@ -0,0 +1,293 @@
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+/**
+ * The rules that hold `icon.md`.
+ *
+ * Both exist because of the same escape, found by hand rather than by a gate: one leaf imported a
+ * caret straight from the glyph library, at a size off both steps and a cut outside the two the
+ * icon leaf offers. Nothing reported it. The vendor rule that guards the component library names
+ * that library only, and the token rules that police the scale read SPACING utilities - gaps,
+ * insets, offsets - so a glyph size is outside every pattern they match.
+ *
+ * The lesson is worth stating where the next rule gets written: a rule that names one vendor
+ * protects one vendor, and a rule that scans one family of utilities protects that family. Neither
+ * generalises on its own, and the gap between them is exactly where a third step gets invented.
+ */
+import { attribute, isClassAttribute, staticText, tagName } from "@starci/eslint-canon-fe/lib/ast.mjs";
+import { canonicalPackages } from "@starci/eslint-canon-fe/lib/fe-stack.mjs";
+import { hfsOf } from "@starci/eslint-canon-fe/lib/hfs.mjs";
+import { fileOf, inSlot, isComponentFile, isProductSource, kindOfFile, roleOfFile } from "@starci/eslint-canon-fe/lib/scope.mjs";
+import { why } from "./lib/why.js";
+/** The one module allowed to name a glyph from a library: the entry of the leaf owner named `Icon`. */
+const ICON_LEAF = { kind: "leaves", owner: "Icon" };
+/** Repeated goal / metric cells are text-led in the reference: the entry of the composite owner named `LabelledProgressRow`. */
+const LABELLED_PROGRESS_ROW = { kind: "composites", owner: "LabelledProgressRow" };
+/**
+ * Package roots that ship glyphs.
+ *
+ * Matched as a PREFIX so a subpath cannot walk around it - the escape that started this was
+ * `@phosphor-icons/react/dist/ssr`, which an equality check on the package name does not see.
+ */
+const GLYPH_PACKAGES = [
+    "@phosphor-icons/",
+    "lucide-react",
+    "react-icons",
+    "@heroicons/",
+    "@tabler/icons",
+    "@fortawesome/",
+    "@mui/icons-material",
+    "@fluentui/react-icons",
+    "iconsax-react",
+    "react-feather",
+];
+/** Package-name signal for a glyph catalogue not yet listed explicitly. */
+const GLYPH_PACKAGE_NAME = /(?:icon|glyph|lucide|feather|tabler|fortawesome)/i;
+/** The two optical families of the heroicons family: the 24px outline heading cut and the 16px solid micro cut. */
+const GLYPH_CUTS = ["24/outline", "16/solid"];
+/**
+ * The closed glyph surface: each package of the one application icon set (fe-stack `icons`: upstream `@heroicons/react`,
+ * used first, and StarCi's custom-only `@starci/heroicons` for the glyphs it lacks) on each of the two cuts. Read from the
+ * catalog, so the set is named once.
+ */
+const glyphSurface = () => canonicalPackages("icons").flatMap((name) => GLYPH_CUTS.map((cut) => `${name}/${cut}`));
+/**
+ * True when the file is the entry (slot role `entry`) of the component owner named `owner` in the layer `kind`.
+ * The slot says which layer and which role; the owner's own folder name is the one fact it cannot say, so it is compared.
+ */
+const isEntryOf = (context, { kind, owner }) => isComponentFile(context) && kindOfFile(context) === kind && roleOfFile(context) === "entry" &&
+    hfsOf(context).relative(fileOf(context)).split("/").slice(-2)[0] === owner;
+/**
+ * True when this file owns glyphs: the icon leaf, which owns the meaning-to-glyph map, or the toast module (`fe.modules.toast`),
+ * whose region draws the status glyph of each toast and sits in the modules tier, below every component it could ask.
+ */
+const isIconLeafFile = (context) => isEntryOf(context, ICON_LEAF) || inSlot(context, "fe.modules.toast");
+/** True for the reusable repeated metric cell whose reference contains no decorative glyph. */
+const isLabelledProgressRowFile = (context) => isEntryOf(context, LABELLED_PROGRESS_ROW);
+/** True when an import source resolves into a glyph library, subpaths included. */
+const isGlyphImport = (source) => {
+    const value = typeof source === "string" ? source : "";
+    const isExternalPackage = value !== "" && !value.startsWith(".") && !value.startsWith("@/");
+    return GLYPH_PACKAGES.some((pkg) => value === pkg || value.startsWith(pkg)) ||
+        (isExternalPackage && GLYPH_PACKAGE_NAME.test(value));
+};
+/** A glyph size written as a fraction of a step, or as an arbitrary value. */
+const OFF_SCALE_GLYPH = /\bsize-(?:\d+\.\d+|\[[^\]]+\])/;
+// -- ICON-6 ----------------------------------------------------------------------------------------
+/** A glyph library is named in one file, and a caller asks for a MEANING instead. */
+export const noVendorIconOutsideIconLeaf = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Glyph libraries are imported only by the icon leaf." },
+        schema: [],
+        messages: {
+            vendor: "`{{source}}` is a glyph library, imported outside `{{leaf}}`. Reaching for it here decides three things at the call site - which library, which glyph, how big - and the next screen answers all three differently. Ask for the MEANING instead; if no meaning fits, add one to the icon leaf, which is where the answer is kept once.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context) || isIconLeafFile(context))
+            return {};
+        return {
+            ImportDeclaration(node) {
+                const source = node.source && node.source.value;
+                if (!isGlyphImport(source))
+                    return;
+                context.report({ node, messageId: "vendor", data: { source, leaf: `${ICON_LEAF.kind}/${ICON_LEAF.owner}/index.tsx` } });
+            },
+        };
+    },
+});
+// -- ICON-7 ----------------------------------------------------------------------------------------
+/**
+ * The icon leaf owns the map, but that ownership does not license a second glyph vocabulary: every glyph comes from the
+ * heroicons family on its two cuts. Phosphor, Iconify, Lucide and every other glyph catalogue are refused, including the
+ * ones no list can name in advance.
+ */
+export const heroiconsIsTheGlyphVendor = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Only the Heroicons heading and micro families (`@heroicons/react`, then `@starci/heroicons`) may supply product glyphs." },
+        schema: [],
+        messages: {
+            vendor: "`{{source}}` is outside StarCi's closed glyph surface ({{surface}}). Use upstream `@heroicons/react/24/outline` or `16/solid` when the icon exists; use the matching `@starci/heroicons` subpath only for a custom cut missing upstream, and add a missing glyph there. The StarCi package never re-exports upstream icons. Phosphor, Iconify and every other glyph catalogue are refused: two sets draw the same meaning with two strokes, two grids and two weights.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        return {
+            ImportDeclaration(node) {
+                const source = node.source && node.source.value;
+                const surface = glyphSurface();
+                if (!isGlyphImport(source) || surface.includes(String(source)))
+                    return;
+                context.report({ node, messageId: "vendor", data: { source, surface: surface.map((name) => `\`${name}\``).join(", ") } });
+            },
+        };
+    },
+});
+// -- ICON-1 ----------------------------------------------------------------------------------------
+/** A glyph takes one of the two steps; a fraction or an arbitrary value is a third. */
+export const noOffScaleGlyphSize = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A glyph is sized by one of the two steps, never by a fraction or an arbitrary value." },
+        schema: [],
+        messages: {
+            offScale: "`{{cls}}` is a glyph size off both steps. A third step is one nobody applies consistently - the author picks it for a reason true on their screen, and everyone after copies the nearest of three. Use the step the icon leaf offers, and if the case genuinely needs a size neither step gives, that is a change to the two steps rather than an exception here.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        const scan = (node, text) => {
+            if (!text)
+                return;
+            const hit = text.match(OFF_SCALE_GLYPH);
+            if (hit)
+                context.report({ node, messageId: "offScale", data: { cls: hit[0] } });
+        };
+        return {
+            JSXAttribute(node) {
+                if (!isClassAttribute(node))
+                    return;
+                scan(node, staticText(node.value));
+            },
+            VariableDeclarator(node) {
+                scan(node, staticText(node.init));
+            },
+        };
+    },
+});
+// -- ICON-1 (call site) ----------------------------------------------------------------------------
+/** A size utility on the class of a glyph: `size-5`, `w-4`, `h-6`, `min-w-4`. */
+const SIZE_UTILITY = /(?:^|\s)(?:size|w|h|min-w|min-h|max-w|max-h)-\S+/;
+/** The icon's size is its usage's: the call site passes the glyph and never a size class. */
+export const noIconSizeClass = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "A glyph component takes its size from its usage (the 20px leading step is size-5), never from a size class at the call site." },
+        schema: [],
+        messages: {
+            size: "`{{cls}}` sizes a glyph at the call site. The size of a glyph is its usage's (`Icon` and the Grammar components that draw one: 24px heading, 20px leading = size-5, 16px chip), so the app passes the glyph and no size class; a size written here is a third step nobody applies the same way twice.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context) || isIconLeafFile(context))
+            return {};
+        return {
+            JSXOpeningElement(node) {
+                const name = tagName(node);
+                if (name === null || !/Icon$/.test(name))
+                    return;
+                const hit = SIZE_UTILITY.exec(staticText(attribute(node, "className")?.value) ?? "");
+                if (hit)
+                    context.report({ node, messageId: "size", data: { cls: hit[0].trim() } });
+            },
+        };
+    },
+});
+// -- ICON-10 ---------------------------------------------------------------------------------------
+/** A repeated metric cell does not invent a feature glyph absent from the reference. */
+export const noDecorativeIconInMetricCell = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Repeated metric cells stay text-led unless the reference explicitly contains an icon." },
+        schema: [],
+        messages: {
+            decorative: "`LabelledProgressRow` is a repeated metric cell, not a feature entry. Its reference is text-led, so an `Icon` here invents emphasis and repeats glyph meanings across the grid. Keep the label and figure; reserve tiny glyphs for generic state or action semantics actually present in the reference.",
+        },
+    },
+    create(context) {
+        if (!isLabelledProgressRowFile(context))
+            return {};
+        return {
+            JSXOpeningElement(node) {
+                if (node.name?.type === "JSXIdentifier" && node.name.name === "Icon") {
+                    context.report({ node, messageId: "decorative" });
+                }
+            },
+        };
+    },
+});
+/** The immediately preceding JSDoc declares this exported component as a brand mark. */
+const declaresBrandMark = (sourceCode, node) => {
+    const comment = sourceCode.getCommentsBefore(node).at(-1);
+    return comment?.type === "Block" && comment.value.startsWith("*") &&
+        /(?:^|\n)\s*\*?\s*@brand-mark(?:\s|$)/.test(comment.value) &&
+        sourceCode.text.slice(comment.range[1], node.range[0]).trim() === "";
+};
+/** A marker belongs to the exported component itself, never to a sibling or an enclosing file. */
+const isDeclaredBrandMarkFunction = (sourceCode, node) => {
+    let declaration = node;
+    if (node.parent?.type === "VariableDeclarator") {
+        if (node.parent.init !== node || node.parent.id.type !== "Identifier")
+            return false;
+        declaration = node.parent.parent;
+        if (declaration.type !== "VariableDeclaration" || declaration.declarations.length !== 1)
+            return false;
+    }
+    const exported = declaration.parent;
+    if (exported?.type !== "ExportNamedDeclaration" && exported?.type !== "ExportDefaultDeclaration")
+        return false;
+    return declaresBrandMark(sourceCode, exported) || declaresBrandMark(sourceCode, declaration);
+};
+/** An SVG belongs to its nearest function; marking another component cannot license it. */
+const inDeclaredBrandMark = (sourceCode, node) => {
+    for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+        if (ancestor.type === "FunctionDeclaration" || ancestor.type === "FunctionExpression" || ancestor.type === "ArrowFunctionExpression") {
+            return isDeclaredBrandMarkFunction(sourceCode, ancestor);
+        }
+    }
+    return false;
+};
+/** Inline SVG belongs only to an explicitly declared brand mark in a leaf entry. */
+export const noInlineSvgOutsideBrandMarkLeaf = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "FE_ICON_INLINE_SVG: inline SVG is drawn only by an exported leaf entry component with a @brand-mark JSDoc declaration.", url: "knowledge/hfs/rules.yaml#R286" },
+        schema: [],
+        messages: {
+            inlineSvg: "FE_ICON_INLINE_SVG: inline `<svg>` draws a second glyph vocabulary. Use the Icon leaf for product glyphs. A brand mark may draw its own SVG only in a leaf entry whose exported component is immediately documented with `@brand-mark` in JSDoc.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        const sourceCode = context.sourceCode;
+        const isLeafEntry = isComponentFile(context) && kindOfFile(context) === "leaves" && roleOfFile(context) === "entry";
+        return {
+            JSXOpeningElement(node) {
+                if (node.name?.type !== "JSXIdentifier" || node.name.name !== "svg")
+                    return;
+                if (isLeafEntry && inDeclaredBrandMark(sourceCode, node))
+                    return;
+                context.report({ node, messageId: "inlineSvg" });
+            },
+        };
+    },
+});
+/** The finding code for the copy-and-glyph law's inline SVG enforcer. */
+Object.assign(why, {
+    "no-inline-svg-outside-brand-mark-leaf": {
+        code: "FE_ICON_INLINE_SVG",
+        en: "`<file>` draws an inline SVG outside an exported leaf entry component declared as a brand mark.",
+        fix: "Use the Icon leaf for product glyphs; declare an original brand mark with @brand-mark JSDoc on its exported leaf entry component.",
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "no-vendor-icon-outside-icon-leaf": noVendorIconOutsideIconLeaf,
+    "heroicons-is-the-glyph-vendor": heroiconsIsTheGlyphVendor,
+    "no-off-scale-glyph-size": noOffScaleGlyphSize,
+    "no-icon-size-class": noIconSizeClass,
+    "no-decorative-icon-in-metric-cell": noDecorativeIconInMetricCell,
+    "no-inline-svg-outside-brand-mark-leaf": noInlineSvgOutsideBrandMarkLeaf,
+};
+defineFamilyRules(rules, "knowledge/hfs/rules.yaml#R93");
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * A consuming repository's `eslint.config.mjs` stays the authority on what is actually switched on.
+ * Both rules are exact - a package prefix and a size pattern - so neither carries the false-positive
+ * risk that would justify adopting it at `warn`.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]));

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/** Core Grammar API rules, versioned with the Grammar family that owns their concrete vocabulary. */
+import type { ESLint, Linter, Rule } from "eslint";
+/** The Grammar families: `core`, and `offset-pop` through its own package entry. */
+export type GrammarFamilyId = "core" | "offset-pop";
+/** The FE slot view `loadHfs(import.meta.url)` gives, as the factory reads it. */
+export type GrammarHfsView = {
+    readonly repoRoot: string;
+    readonly profile: "fe";
+    /** The selected family id: `core` or `offset-pop`. */
+    readonly grammar: GrammarFamilyId;
+    readonly slotOf: (file: string) => string | null;
+};
+/** Each concrete Grammar law has one gathered owner. */
+export declare const lawOwners: readonly string[];
+/** Preserve declarations before gathering so duplicate rule names remain observable. */
+export declare const ruleDeclarations: readonly {
+    readonly law: string;
+    readonly name: string;
+}[];
+/** The law that owns each published rule ID. */
+export declare const ruleOwners: Readonly<Record<string, string>>;
+/** Every rule of the selected family contract. */
+export declare const rules: Readonly<Record<string, Rule.RuleModule>>;
+/** Every family rule runs at error, with no consumer override surface. */
+export declare const recommended: Readonly<Record<string, "error">>;
+/** The failure-code guidance of every rule. */
+export declare const why: Readonly<Record<string, {
+    readonly code: string;
+    readonly en: string;
+    readonly fix: string;
+}>>;
+/** The linter options of the universal canon: no inline configuration, no unused disable directive. */
+export declare const linterOptions: Readonly<Linter.LinterOptions>;
+declare const plugin: ESLint.Plugin;
+export default plugin;
+/**
+ * Add the complete selected-family contract to the universal front-end flat config.
+ * Offset Pop uses the inherited Common renderer contract through its own package entry.
+ * @param input - The selected FE slot view and family.
+ * @returns A typed source block with every family rule at error.
+ */
+export declare const coreGrammarConfig: (input: {
+    readonly hfs: GrammarHfsView;
+    readonly family?: GrammarFamilyId;
+}) => Linter.Config[];

package/dist/index.js

@@ -0,0 +1,73 @@
+import tsParser from "@typescript-eslint/parser";
+import { SOURCE_FILES, linterOptions as canonLinterOptions } from "@starci/eslint-canon-fe/lib/config.mjs";
+import { rules as appShellRules } from "./app-shell.js";
+import { rules as chipLabelRules } from "./chip-label.js";
+import { rules as drawingRules } from "./drawing.js";
+import { rules as grammarBoundaryRules } from "./grammar-boundary.js";
+import { rules as iconRules } from "./icon.js";
+import { rules as menuEntriesRules } from "./menu-entries.js";
+import { rules as statusColorsRules } from "./status-colors.js";
+import { rules as tokensRules } from "./tokens.js";
+import { rules as typographyRules } from "./typography.js";
+import { rules as vendorRules } from "./vendor-boundary.js";
+import { why as familyWhy } from "./lib/why.js";
+const CONTRIBUTIONS = [
+    { law: "app-shell", rules: appShellRules },
+    { law: "chip-label", rules: chipLabelRules },
+    { law: "drawing", rules: drawingRules },
+    { law: "grammar-boundary", rules: grammarBoundaryRules },
+    { law: "icon", rules: iconRules },
+    { law: "menu-entries", rules: menuEntriesRules },
+    { law: "status-colors", rules: statusColorsRules },
+    { law: "tokens", rules: tokensRules },
+    { law: "typography", rules: typographyRules },
+    { law: "vendor-boundary", rules: vendorRules },
+];
+/** Each concrete Grammar law has one gathered owner. */
+export const lawOwners = CONTRIBUTIONS.map(({ law }) => law);
+/** Preserve declarations before gathering so duplicate rule names remain observable. */
+export const ruleDeclarations = CONTRIBUTIONS.flatMap(({ law, rules }) => Object.keys(rules).map((name) => ({ law, name })));
+/** The law that owns each published rule ID. */
+export const ruleOwners = Object.fromEntries(ruleDeclarations.map(({ law, name }) => [name, law]));
+/** Every rule of the selected family contract. */
+export const rules = Object.fromEntries(CONTRIBUTIONS.flatMap(({ rules }) => Object.entries(rules)));
+/** Every family rule runs at error, with no consumer override surface. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]));
+/** The failure-code guidance of every rule. */
+export const why = familyWhy;
+/** The linter options of the universal canon: no inline configuration, no unused disable directive. */
+export const linterOptions = canonLinterOptions;
+const plugin = { meta: { name: "@starci/eslint-grammar-core" }, rules };
+export default plugin;
+/** The families this factory serves: core, and offset-pop through its own package entry. */
+const SERVED_FAMILIES = Object.freeze(["core", "offset-pop"]);
+/**
+ * Add the complete selected-family contract to the universal front-end flat config.
+ * Offset Pop uses the inherited Common renderer contract through its own package entry.
+ * @param input - The selected FE slot view and family.
+ * @returns A typed source block with every family rule at error.
+ */
+export const coreGrammarConfig = ({ hfs, family = "core" } = {}) => {
+    if (!hfs || typeof hfs.slotOf !== "function" || typeof hfs.repoRoot !== "string" || hfs.profile !== "fe") {
+        throw new Error("coreGrammarConfig needs the FE view from loadHfs(import.meta.url)");
+    }
+    if (!SERVED_FAMILIES.includes(family) || hfs.grammar !== family) {
+        throw new Error(`coreGrammarConfig family ${family} does not match the selected Grammar ${hfs.grammar}`);
+    }
+    const missing = Object.keys(rules).filter((name) => recommended[`starci-grammar/${name}`] !== "error");
+    if (missing.length)
+        throw new Error(`coreGrammarConfig requires every family rule at error: ${missing.join(", ")}`);
+    return [{
+            files: [...SOURCE_FILES],
+            languageOptions: {
+                parser: tsParser,
+                ecmaVersion: "latest",
+                sourceType: "module",
+                parserOptions: { projectService: true, tsconfigRootDir: hfs.repoRoot, ecmaFeatures: { jsx: true } },
+            },
+            linterOptions: { ...linterOptions },
+            plugins: { "starci-grammar": plugin },
+            settings: { starci: { hfs } },
+            rules: { ...recommended },
+        }];
+};

package/dist/lib/app-shell-cluster.d.ts

@@ -0,0 +1,6 @@
+import type { ReaderContext, Resolved } from "./types.js";
+/** Every reachable branch yields its own sequence; shell headers select the narrowest right-hand group. */
+export declare const clusterAlternatives: (context: ReaderContext, expression: Resolved | null | undefined, shellHeader: boolean) => {
+    alternatives: string[][];
+    ownsBar: boolean;
+};

package/dist/lib/app-shell-cluster.js

@@ -0,0 +1,75 @@
+import { clusterRole, grammarName, isBarControl, propOf, textProp } from "./app-shell.js";
+import { visitVisible } from "./app-shell-visible.js";
+/** The disclosure component each cluster role's trigger must sit in. */
+const EXPECTED_DISCLOSURE = { language: "DropdownMenu", notifications: "Popover", account: "DropdownMenu" };
+const controlsOf = (context, expression, choices, shellHeader = false) => {
+    const controls = [];
+    const branches = [];
+    let ownsBar = false;
+    visitVisible(context, expression, (opening, name, ancestors) => {
+        if (shellHeader && name !== null && ["TopBar", "NavigationFeatureNav"].includes(name)) {
+            ownsBar = true;
+            return false;
+        }
+        if (!isBarControl(context, opening, name))
+            return;
+        const role = clusterRole(context, opening, name);
+        controls.push(controlSignature(context, opening, name, role, ancestors));
+        return false;
+    }, new Set(), (node) => {
+        if (!choices.has(node))
+            branches.push(node);
+        return choices.get(node) ?? "consequent";
+    });
+    return { controls, branches, ownsBar };
+};
+const controlSignature = (context, opening, name, role, ancestors) => {
+    const signature = `${role ?? "unknown"}:${name}`;
+    const expected = role === null ? undefined : EXPECTED_DISCLOSURE[role];
+    const disclosure = [...ancestors].reverse().map((ancestor) => grammarName(context, ancestor)).find((parent) => parent === "DropdownMenu" || parent === "Popover");
+    if (expected && disclosure !== expected)
+        return `${signature}:wrong-disclosure`;
+    if (role === "language") {
+        const variant = propOf(context, opening, "variant");
+        if (!variant.known || variant.value !== null && textProp(context, opening, "variant") !== "tertiary")
+            return `${signature}:wrong-variant`;
+    }
+    return signature;
+};
+const rightGroup = (context, expression, choices) => {
+    let group = null;
+    let count = Number.POSITIVE_INFINITY;
+    const roles = controlsOf(context, expression, choices).controls.filter((role) => !role.startsWith("unknown:"));
+    visitVisible(context, expression, (opening, name) => {
+        if (isBarControl(context, opening, name))
+            return false;
+        const result = controlsOf(context, opening.parent, choices);
+        const known = result.controls.filter((role) => !role.startsWith("unknown:"));
+        if (roles.length > 0 && known.length === roles.length && roles.every((role) => known.includes(role)) && result.controls.length < count) {
+            group = opening.parent;
+            count = result.controls.length;
+        }
+        return undefined;
+    }, new Set(), (node) => choices.get(node) ?? "consequent");
+    return group ?? expression;
+};
+/** Every reachable branch yields its own sequence; shell headers select the narrowest right-hand group. */
+export const clusterAlternatives = (context, expression, shellHeader) => {
+    const pending = [new Map()];
+    const alternatives = [];
+    for (let choices = pending.pop(); choices; choices = pending.pop()) {
+        const initial = controlsOf(context, expression, choices, shellHeader);
+        if (initial.ownsBar)
+            return { alternatives: [], ownsBar: true };
+        const group = shellHeader ? rightGroup(context, expression, choices) : expression;
+        const result = controlsOf(context, group, choices);
+        const current = choices;
+        const unknown = [...initial.branches, ...result.branches].find((node) => !current.has(node));
+        if (unknown) {
+            pending.push(new Map([...choices, [unknown, "alternate"]]), new Map([...choices, [unknown, "consequent"]]));
+        }
+        else
+            alternatives.push(result.controls);
+    }
+    return { alternatives, ownsBar: false };
+};

package/dist/lib/app-shell-create.d.ts

@@ -0,0 +1,5 @@
+import type { ReaderContext, Resolved } from "./types.js";
+/** Literal create labels and conventional create handlers are executable static evidence. */
+export declare const isCreateAction: (text: string) => boolean;
+/** Follow static item/section arrays; inspect labels and handlers where a menu action is declared. */
+export declare const menuHasCreate: (context: ReaderContext, expression: Resolved | null | undefined, seen?: Set<Resolved>) => boolean;

package/dist/lib/app-shell-create.js

@@ -0,0 +1,37 @@
+/** Static create-action semantics in a bar's controls and its attached menu declarations. */
+import { fileURLToPath } from "node:url";
+import { phrasesOf } from "../../runtime/scripts/lib/source-phrases.mjs";
+import { escapeRegExp } from "../../runtime/scripts/lib/regex.mjs";
+import { propertyKeyText, resolveLocal } from "./app-shell.js";
+import { isNode } from "./types.js";
+const runtimeRoot = fileURLToPath(new URL("../../runtime/", import.meta.url));
+const localizedLabels = phrasesOf("appShell.product", runtimeRoot);
+if (localizedLabels.length === 0)
+    throw new Error("The FE canon's app-shell create-action phrase catalog is missing: regenerate the runtime bundle.");
+const localizedCreate = localizedLabels.map((label) => escapeRegExp(label).replace(/\s+/g, String.raw `\s*`)).join("|");
+const CREATE_WORDS = new RegExp(String.raw `\bcreate\b|\bnew\s+(?:item|record|project|task)|${localizedCreate}`, "i");
+/** Literal create labels and conventional create handlers are executable static evidence. */
+export const isCreateAction = (text) => CREATE_WORDS.test(text.normalize("NFC")) || /\bcreate[A-Z]|\bnew[A-Z]|\bonCreate|\bhandleCreate/.test(text);
+const ACTION_FIELDS = new Set(["id", "key", "label", "title", "textValue", "onAction", "onPress", "onClick", "action"]);
+/** Follow static item/section arrays; inspect labels and handlers where a menu action is declared. */
+export const menuHasCreate = (context, expression, seen = new Set()) => {
+    const node = resolveLocal(context, expression);
+    if (!node || seen.has(node))
+        return false;
+    seen.add(node);
+    if (node.type === "SpreadElement")
+        return menuHasCreate(context, node.argument, seen);
+    if (node.type === "ArrayExpression")
+        return node.elements.some((item) => menuHasCreate(context, item, seen));
+    if (node.type !== "ObjectExpression")
+        return false;
+    return node.properties.some((property) => {
+        if (property.type === "SpreadElement")
+            return menuHasCreate(context, property.argument, seen);
+        const name = propertyKeyText(property.key);
+        const value = resolveLocal(context, property.value);
+        if (name !== null && ACTION_FIELDS.has(name) && value && isNode(value) && isCreateAction(context.sourceCode.getText(value)))
+            return true;
+        return menuHasCreate(context, property.value, seen);
+    });
+};

package/dist/lib/app-shell-owner-source.d.ts

@@ -0,0 +1,11 @@
+import type { TSESTree } from "@typescript-eslint/types";
+import type { Node, ParsedContext, ReaderContext } from "./types.js";
+/** An exported value together with the parsed file that holds it. */
+export interface Owner {
+    readonly context: ParsedContext;
+    readonly value: Node;
+}
+/** An imported JSX owner, or null when its implementation cannot be proved from owned source. */
+export declare const importedHeader: (context: ReaderContext, opening: TSESTree.JSXOpeningElement) => Owner | null;
+/** The per-repository proof cache shares the same lifetime as parsed header source. */
+export declare const headerProofs: (context: ReaderContext) => Map<string, boolean>;