@starci/hfs 4.7.34 → 4.7.36

package/runtime/scripts/lib/grammar-vendor-parity.mjs

@@ -8,143 +8,50 @@
 //
 // Two layers. The UNIVERSAL layer binds every Grammar built on HeroUI: use the HeroUI component for each role (no hand-rolled menu, list
 // box, dialog or switch: `role`), keep its anatomy and parts (`anatomy`, `undeclared`). The PER-GRAMMAR layer is what a Grammar declares in the
-// manifest (`grammars: [{id, paths, vendor: {name: heroui, parity}}]`, never inferred from its code): `strict` keeps HeroUI's default CSS and
+// source DNA (`paths`, `vendor: {name: heroui, parity}`, `arrangement`, never inferred from its CSS): `strict` keeps HeroUI's default CSS and
 // arrangement (`slot`, `style`, `default`, `stale`; the pinned overrides are the only deviations), `custom` may re-skin and re-arrange
 // (tokens, radius, padding, colour, where the indicator sits, separators, icon size) and is judged by the universal layer only.
 // Grammar StarCi is strict.
 //
 // A finding is red when
-//   anatomy    a wrapper renders a part the vendor does not have, omits a part the vendor requires, or omits the vendor's embedded
-//              divider (`Separator`) while it renders a `Section`;
+//   anatomy    a wrapper renders a part the vendor does not have, omits a part the vendor requires or a slot its row claims,
+//              or omits the vendor's embedded divider (`Separator`) while it renders a `Section`;
 //   undeclared a Grammar file wraps a HeroUI component its manifest row does not declare (or the row names a file that is gone);
 //   slot       Grammar CSS targets a vendor class or `data-slot` no override declares;
-//   style      (rows with `styleParity: true`) Grammar CSS restyles a paint family (padding, radius, colour, size, ...) of a vendor part
+//   style      Grammar CSS restyles a paint family (padding, radius, colour, size, ...) of any wrapped vendor part
 //              through a class or `data-grammar-*` stamp that wrapper puts on that part, and no override declares it (accessibility
 //              media - forced colors, the touch target floor - is not judged);
 //   default    a wrapper passes a vendor part a prop value other than the vendor default (the dot indicator in place of the check);
 //   role       a Grammar file hand-rolls an ARIA role HeroUI already has a component for (unless a pinned `role` override declares it);
 //   grammar    a Grammar file belongs to no declared Grammar, or a declaration is malformed;
 //   stale      an override nothing needs any more.
-// A StarCi canon decision that is not drift (the glyph size of the icon rule) is declared as a `canon` override: justified, pinned, and it
-// permits nothing. Family skins (`offset-pop`, `heritage`) are brand directions that re-skin HeroUI on purpose and are not judged; the
-// base look (`common`, `core`) is.
+// Arrangement choices (including glyph size) live in the family's DNA and never authorize vendor paint overrides.
+// Custom family skins keep the universal component/anatomy/role contract; strict families also keep vendor paint defaults.
 import { createHash } from 'node:crypto';
-import { cssRules, ruleFamilies, selectorAttributes, selectorClasses, subjectCompound } from './css-rules.mjs';
+import { cssRules, propertyFamily, repaintFamilies, selectorAttributes, selectorClasses, subjectCompound, utilityFamilies } from './css-rules.mjs';
 import { byCodeUnit } from './list.mjs';
+import { classTokens, heroTags, importAliases, roleFindings, stringLiterals } from './grammar-vendor-parity-jsx.mjs';
+export { heroTags, importAliases } from './grammar-vendor-parity-jsx.mjs';
 
 export const CODE = 'GRAMMAR_VENDOR_PARITY';
 export const WRAPPERS_SCHEMA = 'starci/vendor-heroui-wrappers@1';
 
-/** The sha256 of a pinned file's text, line endings normalised. */
-export const manifestDigest = (text) => createHash('sha256').update(String(text ?? '').replaceAll('\r\n', '\n')).digest('hex');
-
-const finding = (rule, file, line, message) => ({ code: CODE, rule, file, line, message: `${rule}: ${message}` });
-const lineOf = (text, index) => text.slice(0, index).split('\n').length;
-
-// ---------------------------------------------------------------------------
-// Reading JSX without a parser: the opening tags of the aliases a file imports from @heroui/react.
-// ---------------------------------------------------------------------------
-
-/** The index after the quoted string that starts at `start`. */
-function skipQuoted(text, start) {
-  const quote = text[start];
-  let index = start + 1;
-  while (index < text.length && text[index] !== quote) index += text[index] === '\\' ? 2 : 1;
-  return index + 1;
-}
-
-/** The index after the template literal that starts at `start`, `${...}` substitutions included. */
-function skipTemplate(text, start) {
-  let index = start + 1;
-  while (index < text.length && text[index] !== '`') {
-    if (text[index] === '\\') index += 2;
-    else if (text[index] === '$' && text[index + 1] === '{') index = skipBraces(text, index + 1);
-    else index += 1;
-  }
-  return index + 1;
-}
-
-/** The index after the balanced `{...}` that starts at `start`. */
-function skipBraces(text, start) {
-  let depth = 0;
-  let index = start;
-  while (index < text.length) {
-    const char = text[index];
-    if (char === '"' || char === "'") index = skipQuoted(text, index);
-    else if (char === '`') index = skipTemplate(text, index);
-    else {
-      if (char === '{') depth += 1;
-      if (char === '}') depth -= 1;
-      index += 1;
-      if (depth === 0 && char === '}') return index;
-    }
-  }
-  return index;
-}
-
-/** The index after the value (a string, a template or a braced expression) that starts at `start`. */
-function skipValue(text, start) {
-  const char = text[start];
-  if (char === '"' || char === "'") return skipQuoted(text, start);
-  if (char === '`') return skipTemplate(text, start);
-  return char === '{' ? skipBraces(text, start) : start + 1;
-}
-
-/** Attributes of the opening tag whose name ended at `from`: `{name, raw}` (a spread is named `...`). */
-function readAttributes(text, from) {
-  const attrs = [];
-  let index = from;
-  while (index < text.length) {
-    while (/\s/.test(text[index] ?? '')) index += 1;
-    if (text[index] === '>' || text.startsWith('/>', index)) break;
-    if (text[index] === '{') {
-      const end = skipBraces(text, index);
-      attrs.push({ name: '...', raw: text.slice(index + 1, end - 1) });
-      index = end;
-      continue;
-    }
-    const name = /^[\w:-]+/.exec(text.slice(index, index + 80))?.[0];
-    if (!name) break;
-    index += name.length;
-    if (text[index] !== '=') {
-      attrs.push({ name, raw: 'true' });
-      continue;
-    }
-    index += 1;
-    const end = skipValue(text, index);
-    const raw = text.slice(index, end);
-    attrs.push({ name, raw: raw.startsWith('{') ? raw.slice(1, -1) : raw });
-    index = end;
-  }
-  return attrs;
-}
-
-/** The opening tags of the given import aliases: `{alias, part, attrs, line}` (`part` is `Root` for the bare alias). */
-export function heroTags(text, aliases) {
-  if (!aliases.length) return [];
-  const pattern = new RegExp(String.raw`<(${aliases.join('|')})(?:\.(\w+))?(?=[\s/>])`, 'g');
-  return [...text.matchAll(pattern)].map((match) => ({
-    alias: match[1],
-    part: match[2] ?? 'Root',
-    attrs: readAttributes(text, match.index + match[0].length),
-    line: lineOf(text, match.index),
+/** Which measured roles name component contracts: ARIA widgets/windows or an exact public structural role API. */
+export function classifyRoleContracts({ carriers, publicApis, ariaRoles }) {
+  const apis = new Map(publicApis.filter((name) => ariaRoles.has(name.toLowerCase())).map((name) => [name.toLowerCase(), name]));
+  const all = new Map(carriers);
+  for (const [role] of apis) if (!all.has(role)) all.set(role, []);
+  return Object.fromEntries([...all].sort(([a], [b]) => byCodeUnit(a, b)).map(([role, contracts]) => {
+    const definition = ariaRoles.get(role);
+    const componentRole = definition?.superClass.some((chain) => chain.some((category) => ['widget', 'window', 'composite'].includes(category))) || apis.has(role);
+    return [role, { componentRole: Boolean(componentRole), contracts: [...new Set(contracts)].sort(byCodeUnit), ...(apis.has(role) ? { publicApi: apis.get(role) } : {}) }];
   }));
 }
 
-/** The string literals of an expression, without their quotes. */
-const stringLiterals = (raw) => (String(raw).match(/"[^"\n]*"|'[^'\n]*'|`[^`$]*`/g) ?? []).map((literal) => literal.slice(1, -1));
+/** The sha256 of a pinned file's text, line endings normalised. */
+export const manifestDigest = (text) => createHash('sha256').update(String(text ?? '').replaceAll('\r\n', '\n')).digest('hex');
 
-/** The class tokens an element carries: the literals of its className, with a bare constant resolved one level in the file. */
-function classTokens(text, attrs) {
-  const raw = attrs.find((attr) => attr.name === 'className')?.raw;
-  if (raw === undefined) return [];
-  const names = String(raw).match(/\b[A-Za-z_]\w*\b/g) ?? [];
-  const resolved = names.flatMap((name) => {
-    const declaration = new RegExp(String.raw`\bconst\s+${name}\s*=\s*([^\n]*(?:\n[^\n;]*)?)`).exec(text);
-    return declaration ? stringLiterals(declaration[1]) : [];
-  });
-  return [...stringLiterals(raw), ...resolved].flatMap((value) => value.split(/\s+/)).filter(Boolean);
-}
+const finding = (rule, file, line, message) => ({ code: CODE, rule, file, line, message: `${rule}: ${message}` });
 
 // ---------------------------------------------------------------------------
 // The judgment.
@@ -152,27 +59,13 @@ function classTokens(text, attrs) {
 
 /** Accessibility adaptations of the user's input or display (forced colours, contrast, the touch target floor) are not restyles of the vendor look. */
 const ACCESSIBILITY_MEDIA = /forced-colors|prefers-contrast|pointer:\s*coarse/;
-const OVERRIDE_KINDS = ['slot', 'style', 'default', 'role', 'canon'];
+const OVERRIDE_KINDS = ['slot', 'style', 'default', 'role'];
 const PARITY_MODES = ['strict', 'custom'];
-/** The ARIA roles HeroUI has a component for: a Grammar file that writes one by hand has hand-rolled that component. */
-const HEROUI_ROLES = new Set(['menu', 'menuitem', 'menuitemradio', 'menuitemcheckbox', 'listbox', 'option', 'combobox', 'dialog', 'alertdialog', 'tablist', 'tab', 'tabpanel', 'switch', 'slider', 'checkbox', 'radio', 'radiogroup']);
 const overrideKey = (kind, target) => `${kind}:${target}`;
 
-/** The vendor imports of a source: alias -> vendor component name. */
-export function importAliases(text) {
-  const aliases = new Map();
-  for (const match of text.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']@heroui\/react["']/g)) {
-    for (const entry of match[1].split(',').map((part) => part.trim()).filter(Boolean)) {
-      const found = /^(?!type\s)(\w+)(?:\s+as\s+(\w+))?$/.exec(entry);
-      if (found) aliases.set(found[2] ?? found[1], found[1]);
-    }
-  }
-  return aliases;
-}
-
 /**
  * The declared overrides as a ledger: `allowed(kind, target)` answers and remembers the use, so an override nothing needs is found stale.
- * A `canon` override records a StarCi canon decision that is not vendor drift (the glyph size of the icon rule) for the owner; it permits nothing.
+ * Arrangement belongs in DNA, so it cannot grant permission through the override ledger.
  */
 function declaredOverrides(wrappers) {
   const declared = new Map();
@@ -190,32 +83,55 @@ function declaredOverrides(wrappers) {
     return declared.has(key);
   };
   const stale = () => [...declared]
-    .filter(([key]) => !key.startsWith('canon:') && !used.has(key))
+    .filter(([key]) => !used.has(key))
     .map(([key, file]) => finding('stale', file, 0, `the override ${key} is declared but nothing needs it: remove it`));
   return { allowed, stale, problems };
 }
 
 /** The Grammar a file belongs to (the longest declared path prefix), or undefined. */
 const grammarOf = (file, grammars) => grammars
-  .flatMap((grammar) => (grammar.paths ?? []).filter((prefix) => file.startsWith(prefix)).map((prefix) => ({ grammar, length: prefix.length })))
+  .flatMap((grammar) => (Array.isArray(grammar.paths) ? grammar.paths : []).filter((prefix) => typeof prefix === 'string' && file.startsWith(prefix)).map((prefix) => ({ grammar, length: prefix.length })))
   .sort((a, b) => b.length - a.length)[0]?.grammar;
 
 /** The malformed Grammar declarations and the files that belong to no declared Grammar. */
 function grammarFindings(grammars, files) {
+  const validValue = (value) => typeof value === 'string' ? value.length > 0 : value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0 && Object.values(value).every(validValue);
+  const validPaths = (paths) => Array.isArray(paths) && paths.length > 0 && paths.every((prefix) => typeof prefix === 'string' && /^(?:[\w-]+\/)+$/.test(prefix));
   const found = grammars
-    .filter((grammar) => !grammar.id || !Array.isArray(grammar.paths) || grammar.vendor?.name !== 'heroui' || !PARITY_MODES.includes(grammar.vendor?.parity))
-    .map((grammar) => finding('grammar', 'knowledge/vendor/heroui/wrappers.yaml', 0, `the Grammar ${grammar.id ?? '?'} declares an id, its paths and vendor: {name: heroui, parity: ${PARITY_MODES.join(' | ')}}`));
-  return [...found, ...files.filter((file) => grammarOf(file, grammars) === undefined).map((file) => finding('grammar', file, 0, 'belongs to no declared Grammar: declare it in the grammars of the wrapper manifest'))];
+    .filter((grammar) => !grammar.id || !validPaths(grammar.paths) || grammar.vendor?.name !== 'heroui' || !PARITY_MODES.includes(grammar.vendor?.parity) || !['indicatorSide', 'separators', 'iconSize', 'density'].every((key) => validValue(grammar.arrangement?.[key])) || grammar.declarationError)
+    .map((grammar) => {
+      const error = grammar.declarationError ? ': ' + grammar.declarationError : '';
+      return finding('grammar', grammar.dnaFile ?? 'packages/grammar/src', 0, `the Grammar ${grammar.id ?? '?'} declares an id, its paths, vendor: {name: heroui, parity: ${PARITY_MODES.join(' | ')}} and arrangement: {indicatorSide, separators, iconSize, density} in its DNA${error}`);
+    });
+  return [...found, ...files.filter((file) => grammarOf(file, grammars) === undefined).map((file) => finding('grammar', file, 0, 'belongs to no declared Grammar: declare its owned paths, vendor parity and arrangement in its DNA'))];
 }
 
-/** The ARIA roles a file writes by hand in JSX (comments excluded) that HeroUI has a component for. */
-function roleFindings({ file, text, allowed }) {
-  const code = text.replaceAll(/\/\*[\s\S]*?\*\//g, (comment) => comment.replaceAll(/[^\n]/g, ' ')).replaceAll(/\/\/[^\n]*/g, '');
-  const roles = [...code.matchAll(/\srole=["']([a-z]+)["']/g)].map((match) => match[1]).filter((role) => HEROUI_ROLES.has(role));
-  return [...new Set(roles)].filter((role) => !allowed('role', `${file}:${role}`)).map((role) => finding('role', file, 0, `hand-rolls role="${role}", which HeroUI has a component for: use it (override target role:${file}:${role})`));
+/** The compound part that supplies a claimed vendor slot, including nested slots supplied by a structural ancestor. */
+function ownerOfSlot(reference, target) {
+  const parts = Object.entries(reference.parts);
+  if (!target.startsWith('.')) return parts.find(([, part]) => part.dataSlot === target)?.[0];
+  const cls = target.slice(1);
+  const slots = Object.entries(reference.anatomy.slots ?? {}).flatMap(([key, classes]) => {
+    const part = parts.map(([name]) => name).filter((name) => key.toLowerCase().endsWith(name.toLowerCase())).sort((a, b) => b.length - a.length)[0];
+    return part ? String(classes).split(/\s+/).map((name) => ({ cls: name, part })) : [];
+  });
+  // A List implementation may mention all its container's internal classes. The
+  // named compound ancestor (ListContainer) still has to be mounted to emit them.
+  const ancestor = slots.filter((slot) => cls === slot.cls || cls.startsWith(`${slot.cls}__`)).sort((a, b) => b.cls.length - a.cls.length)[0];
+  return ancestor?.part ?? parts.find(([, part]) => part.classes?.includes(cls))?.[0];
+}
+
+/** Slots claimed by the wrapper row need their vendor compound part, even when that part is optional in the vendor API. */
+function missingSlotFindings({ file, name, reference, row, rendered, delegates }) {
+  return (row.overrides ?? []).filter((entry) => entry?.kind === 'slot' && typeof entry.target === 'string').flatMap((entry) => {
+    const part = ownerOfSlot(reference, entry.target);
+    return part && !rendered.has(part) && !delegates.has(part)
+      ? [finding('anatomy', file, 1, `omits vendor slot ${entry.target} declared by its wrapper row: render ${name}.${part}, which supplies it (or delegate that part when the caller supplies it)`)]
+      : [];
+  });
 }
 
-/** The part findings of one wrapped component: parts that are not the vendor's, required parts left out, the divider between sections. */
+/** The part findings of one wrapped component: unknown parts, required parts or claimed slots left out, and section dividers. */
 function anatomyFindings({ file, name, reference, mine, row, tags, aliases }) {
   const found = [];
   for (const tag of mine) {
@@ -228,6 +144,7 @@ function anatomyFindings({ file, name, reference, mine, row, tags, aliases }) {
   for (const part of reference.anatomy.required.filter((candidate) => !rendered.has(candidate) && !delegates.has(candidate))) {
     found.push(finding('anatomy', file, 1, `omits ${name}.${part}, which HeroUI ${name} requires (render it, or declare it under delegates when the caller supplies it)`));
   }
+  found.push(...missingSlotFindings({ file, name, reference, row, rendered, delegates }));
   if (!rendered.has('Section')) return found;
   for (const embed of reference.anatomy.embeds.filter((entry) => entry.slot === 'separator')) {
     const separatorAliases = new Set([...aliases].filter(([, exported]) => exported === embed.component).map(([local]) => local));
@@ -275,16 +192,16 @@ function wrapperFindings({ file, text, row, references, byName, allowed, strict
 }
 
 /** The stamps (class tokens and `data-grammar-*` names) each wrapped vendor part carries: stamp -> [{name, part, dir, file}]. */
-function stampsOf(sources, rows, byName, references, strictOf) {
+function stampsOf(sources, rows, byName, references, grammarFor) {
   const stamps = new Map();
   const add = (key, entry) => stamps.set(key, [...(stamps.get(key) ?? []), entry]);
-  for (const { file, text } of sources.filter((source) => rows.get(source.file)?.styleParity && strictOf(source.file))) {
+  for (const { file, text } of sources.filter((source) => rows.has(source.file) && grammarFor(source.file)?.vendor?.parity === 'strict')) {
     const aliases = importAliases(text);
     for (const tag of heroTags(text, [...aliases.keys()])) {
       const name = aliases.get(tag.alias);
       const dir = byName.get(name);
       if (dir === undefined || !references[dir].parts[tag.part]) continue;
-      const entry = { name, part: tag.part, dir, file };
+      const entry = { name, part: tag.part, dir, file, family: grammarFor(file).id };
       classTokens(text, tag.attrs).forEach((token) => add(`.${token}`, entry));
       tag.attrs.filter((attr) => attr.name.startsWith('data-grammar-')).forEach((attr) => add(`[${attr.name}]`, entry));
     }
@@ -306,34 +223,65 @@ function slotFindings({ file, selector, vendor, allowed }) {
   return found;
 }
 
+/** The declarations and utilities that set one paint family, with their at-rule context intact. */
+function familyValue(rule, family) {
+  return {
+    apply: (rule.apply ?? []).filter((utility) => utilityFamilies(utility).includes(family)),
+    declarations: (rule.declarations ?? []).map((entry) => {
+      if (typeof entry !== 'string') return entry;
+      const colon = entry.indexOf(':');
+      return { property: entry.slice(0, colon).trim(), value: entry.slice(colon + 1).trim() };
+    }).filter((entry) => propertyFamily(entry.property) === family),
+    wraps: rule.wraps ?? [],
+  };
+}
+
+/** Measured vendor rules for this part and paint family; preserve state/variant selectors instead of guessing a cascade. */
+function vendorDefaults(reference, part, family) {
+  const declared = reference.parts[part];
+  const owns = (selector) => {
+    const subject = subjectCompound(selector);
+    return selectorClasses(subject).some((cls) => declared.classes?.includes(cls)) || selectorAttributes(subject).some((attribute) => attribute.name === 'data-slot' && attribute.value === declared.dataSlot);
+  };
+  return (reference.css.rules ?? []).flatMap((rule) => {
+    const selectors = rule.selectors.filter(owns);
+    const value = familyValue(rule, family);
+    return selectors.length && (value.apply.length || value.declarations.length) ? [{ file: rule.file, selectors, ...value }] : [];
+  });
+}
+
 /** The paint families Grammar CSS repaints on a vendor part through a stamp of the subject compound, as style findings. */
-function styleFindings({ file, selector, families, stamps, references, allowed }) {
+function styleFindings({ file, selector, families, stamps, references, allowed, rule, grammar }) {
   const found = [];
   const subject = subjectCompound(selector);
   const tokens = [...selectorClasses(subject).map((cls) => `.${cls}`), ...selectorAttributes(subject).map((attribute) => `[${attribute.name}]`)];
   for (const token of tokens) {
-    for (const entry of stamps.get(token) ?? []) {
+    for (const entry of (stamps.get(token) ?? []).filter((candidate) => candidate.family === grammar.id)) {
       const paints = references[entry.dir].parts[entry.part].paints;
       for (const family of families.filter((candidate) => paints.includes(candidate))) {
         const target = `${entry.name}.${entry.part}:${family}`;
-        if (!allowed('style', target)) found.push(finding('style', file, 0, `${selector} restyles ${family} of HeroUI ${entry.name}.${entry.part}, which the vendor decides (stamp ${token} on ${entry.file}; override target style:${target})`));
+        if (!allowed('style', target)) found.push({
+          ...finding('style', file, 0, `${selector} restyles ${family} of HeroUI ${entry.name}.${entry.part}, which the vendor decides (stamp ${token} on ${entry.file}; override target style:${target})`),
+          selector, part: `${entry.name}.${entry.part}`, property: family, wrapperRow: entry.file, family: grammar.id,
+          grammarValue: familyValue(rule, family), vendorDefault: vendorDefaults(references[entry.dir], entry.part, family),
+        });
       }
     }
   }
   return found;
 }
 
-function cssFindings({ styles, references, stamps, allowed, strictOf }) {
+function cssFindings({ styles, references, stamps, allowed, grammarFor }) {
   const vendor = {
     classes: new Set(Object.values(references).flatMap((reference) => reference.css.classes)),
     slots: new Set(Object.values(references).flatMap((reference) => reference.css.dataSlots)),
   };
   const found = [];
-  for (const { file, text } of styles.filter((sheet) => strictOf(sheet.file))) {
+  for (const { file, text } of styles.filter((sheet) => grammarFor(sheet.file)?.vendor?.parity === 'strict')) {
     for (const rule of cssRules(text)) {
-      const families = rule.wraps.some((wrap) => ACCESSIBILITY_MEDIA.test(wrap)) ? [] : ruleFamilies(rule);
+      const families = rule.wraps.some((wrap) => ACCESSIBILITY_MEDIA.test(wrap)) ? [] : repaintFamilies(rule);
       for (const selector of rule.selectors) {
-        found.push(...slotFindings({ file, selector, vendor, allowed }), ...(families.length ? styleFindings({ file, selector, families, stamps, references, allowed }) : []));
+        found.push(...slotFindings({ file, selector, vendor, allowed }), ...(families.length ? styleFindings({ file, selector, families, stamps, references, allowed, rule, grammar: grammarFor(file) }) : []));
       }
     }
   }
@@ -343,28 +291,33 @@ function cssFindings({ styles, references, stamps, allowed, strictOf }) {
 /**
  * Every GRAMMAR_VENDOR_PARITY finding.
  *   references  { <dir>: parsed vendor reference }
- *   manifest    the parsed wrapper manifest ({schema, wrappers: [{file, wraps, delegates, styleParity, overrides}]})
+ *   manifest    the parsed wrapper manifest ({schema, wrappers: [{file, wraps, delegates, overrides}]})
+ *   grammars    source DNA declarations ({id, paths, vendor, arrangement}), loaded separately from the manifest
  *   sources     [{file, text}] Grammar .ts/.tsx (stories excluded), file relative to packages/grammar/src
  *   styles      [{file, text}] every Grammar .css; a sheet is judged only when its Grammar declares `parity: strict`
  */
-export function parityFindings({ references, manifest, sources, styles }) {
+export function parityFindings({ references: vendorReferences, manifest, sources, styles, grammars = [] }) {
   if (manifest?.schema !== WRAPPERS_SCHEMA) return [finding('manifest', 'knowledge/vendor/heroui/wrappers.yaml', 0, `schema must be ${WRAPPERS_SCHEMA}`)];
   const wrappers = Array.isArray(manifest.wrappers) ? manifest.wrappers : [];
+  const roleReference = vendorReferences.roles;
+  if (roleReference?.schema !== 'starci/vendor-heroui-roles@1' || !roleReference.roles || typeof roleReference.roles !== 'object' || Array.isArray(roleReference.roles) || Object.keys(roleReference.roles).length === 0 || Object.values(roleReference.roles).some((entry) => !entry || typeof entry.componentRole !== 'boolean' || !Array.isArray(entry.contracts))) return [finding('reference', 'knowledge/vendor/heroui/roles.yaml', 0, 'the generated vendor role index is missing or malformed: regenerate the vendor reference')];
+  const references = Object.fromEntries(Object.entries(vendorReferences).filter(([, reference]) => reference.component));
   const byName = new Map(Object.entries(references).map(([dir, reference]) => [reference.component, dir]));
+  const vendorRoles = new Set(Object.entries(vendorReferences.roles?.roles ?? {}).filter(([, declaration]) => declaration.componentRole).map(([role]) => role));
   const rows = new Map(wrappers.map((row) => [row.file, row]));
   const known = new Set(sources.map((source) => source.file));
   const { allowed, stale, problems } = declaredOverrides(wrappers);
-  const grammars = Array.isArray(manifest.grammars) ? manifest.grammars : [];
-  const strictOf = (file) => grammarOf(file, grammars)?.vendor?.parity === 'strict';
+  const grammarFor = (file) => grammarOf(file, grammars);
+  const strictOf = (file) => grammarFor(file)?.vendor?.parity === 'strict';
   return [
     ...grammarFindings(grammars, [...sources, ...styles].map((source) => source.file)),
     ...wrappers.filter((row) => !known.has(row.file)).map((row) => finding('undeclared', row.file, 0, 'the manifest names a file that does not exist')),
     ...problems,
     ...sources.flatMap(({ file, text }) => [
       ...wrapperFindings({ file, text, row: rows.get(file), references, byName, allowed, strict: strictOf(file) }),
-      ...roleFindings({ file, text, allowed }),
+      ...roleFindings({ file, text, allowed, vendorRoles, roleDeclarations: roleReference.roles, finding }),
     ]),
-    ...cssFindings({ styles, references, stamps: stampsOf(sources, rows, byName, references, strictOf), allowed, strictOf }),
+    ...cssFindings({ styles, references, stamps: stampsOf(sources, rows, byName, references, grammarFor), allowed, grammarFor }),
     ...stale(),
   ];
 }

package/runtime/scripts/lib/numeric-match.mjs

@@ -0,0 +1,5 @@
+/** Read the first numeric capture of a matching recognizer; unmatched values have no number. */
+export function numericMatch(value, pattern) {
+  const match = pattern.exec(String(value ?? ''));
+  return match ? Number(match[1]) : null;
+}

package/runtime/scripts/lib/release-version.mjs

@@ -0,0 +1,119 @@
+// release-version.mjs - the one reading of a release version (owner ruling release-waves). A prerelease `<label>.N` opens the release
+// line N and `<label>.N.M` is the M-th release after it, a wave or a fix alike, so alpha.31 < alpha.31.1 < alpha.31.2 < alpha.32 in
+// SemVer order. The next release is derived from the highest one already released, never guessed. The legacy `<label>.N-fix.K` still
+// reads as release K after `<label>.N` and is never produced again. Pure: the callers read the tags and the registry.
+
+const NUMERIC = /^(?:0|[1-9]\d*)$/;
+const POSITIVE = /^[1-9]\d*$/;
+const IDENTIFIERS = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
+const LEGACY_FIX = '-fix.';
+
+/** {base, wave, legacy}: the release a version counts its waves from, and its wave M (0 for the release that opens the line). */
+export function waveOf(version) {
+  const text = String(version ?? '').split('+')[0];
+  const fix = text.lastIndexOf(LEGACY_FIX);
+  const legacyWave = fix > 0 ? text.slice(fix + LEGACY_FIX.length) : '';
+  if (POSITIVE.test(legacyWave)) return { base: text.slice(0, fix), wave: Number(legacyWave), legacy: true };
+  const ids = text.split('.');
+  const counted = ids.length > 3 && POSITIVE.test(ids.at(-1)) && (text.includes('-') ? NUMERIC.test(ids.at(-2)) : ids.length === 4);
+  return counted ? { base: ids.slice(0, -1).join('.'), wave: Number(ids.at(-1)), legacy: false } : { base: text, wave: 0, legacy: false };
+}
+
+/** Parsed SemVer identifiers {core, pre} of `version`; an unreadable version throws. */
+export function versionParts(version) {
+  const parts = typeof version === 'string' ? version.split('+') : [];
+  if (!parts.length || parts.length > 2 || (parts.length === 2 && !IDENTIFIERS.test(parts[1]))) throw new Error(`unreadable release version ${version}`);
+  const boundary = parts[0].indexOf('-');
+  const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
+  const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
+  if (core.length !== 3 || core.some((part) => !NUMERIC.test(part)) || (prerelease !== null && !IDENTIFIERS.test(prerelease))) throw new Error(`unreadable release version ${version}`);
+  const pre = prerelease?.split('.') ?? [];
+  if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
+  return { core: core.map(BigInt), pre };
+}
+
+const readable = (version) => {
+  try {
+    versionParts(version);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The SemVer spelling a version is ordered by: a legacy `-fix.K` orders as wave K of its line. */
+const ordered = (version) => {
+  const { base, wave, legacy } = waveOf(version);
+  return legacy ? `${base}.${wave}` : version;
+};
+
+const compareIdentifier = (a, b) => {
+  const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
+  if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
+  if (numericA !== numericB) return numericA ? -1 : 1;
+  return a < b ? -1 : Number(a > b);
+};
+
+/** SemVer precedence, numeric prerelease identifiers included; build metadata has no precedence. */
+export function compareVersions(a, b) {
+  const left = versionParts(ordered(a)), right = versionParts(ordered(b));
+  for (const i of left.core.keys()) {
+    if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
+  }
+  if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
+    if (left.pre[i] === undefined) return -1;
+    if (right.pre[i] === undefined) return 1;
+    const compared = compareIdentifier(left.pre[i], right.pre[i]);
+    if (compared) return compared;
+  }
+  return 0;
+}
+
+/** The release line of `version`: a prerelease's core and the identifiers before its first number (every alpha.N and alpha.N.M share one), a stable release's major and minor. */
+export function releaseLine(version) {
+  const { core, pre } = versionParts(ordered(version));
+  if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
+  const first = pre.findIndex((id) => /^\d+$/.test(id));
+  return `${core.join('.')}-${(first < 0 ? pre : pre.slice(0, first)).join('.')}`;
+}
+
+/** {family, line} of a release that opens a line (`<x.y.z>-<label>.N`), or null for any other shape. */
+function lineStart(base) {
+  if (!readable(base)) return null;
+  const { core, pre } = versionParts(base);
+  return pre.length === 2 && !/^\d+$/.test(pre[0]) && NUMERIC.test(pre[1]) ? { family: `${core.join('.')}-${pre[0]}`, line: Number(pre[1]) } : null;
+}
+
+/** The next wave after `version`: its base with M one past the highest wave of that base among `version` and `known`. */
+export function nextWave(version, known = []) {
+  const { base } = waveOf(version);
+  const waves = [version, ...known].map(waveOf).filter((entry) => entry.base === base).map((entry) => entry.wave);
+  return `${base}.${Math.max(0, ...waves) + 1}`;
+}
+
+/** What may follow the highest line-shaped release of `versions`: {highest, family, wave, line}, or null when none has that shape. */
+export function nextReleases(versions) {
+  const shaped = versions.filter((version) => readable(version) && lineStart(waveOf(version).base));
+  if (!shaped.length) return null;
+  const highest = shaped.reduce((top, version) => (compareVersions(version, top) > 0 ? version : top));
+  const { family, line } = lineStart(waveOf(highest).base);
+  return { highest, family, wave: nextWave(highest, shaped), line: `${family}.${line + 1}` };
+}
+
+/**
+ * Why `version` cannot be released after `released` (the versions already tagged), or null when it can: the next wave of the highest
+ * release, the first release of the next line, or a later release of another label or core. The legacy `-fix` form is always refused.
+ */
+export function releaseVersionRefusal(version, released) {
+  const next = nextReleases(released.filter((entry) => entry !== version));
+  const named = next ? `; the next release is ${next.wave} (the next wave or fix after ${next.highest}) or ${next.line} (the next line)` : '';
+  if (waveOf(version).legacy) return `${version} is the legacy -fix form, which is read and never released again${named}`;
+  if (!next || version === next.wave || version === next.line) return null;
+  if (!readable(version)) return `${version} is not a SemVer version${named}`;
+  if (lineStart(waveOf(version).base)?.family !== next.family && compareVersions(version, next.highest) > 0) return null;
+  return `${version} does not follow ${next.highest}${named}`;
+}
+
+/** The versions of the release tags `v<version>` in the output of `git tag --list`. */
+export const taggedVersions = (listing) => String(listing ?? '').split(/\r?\n/).map((name) => name.trim()).filter((name) => /^v\d/.test(name)).map((name) => name.slice(1));

package/runtime/scripts/lib/runtime-publication-tags.mjs

@@ -1,53 +1,10 @@
 // The release owner's dist-tag judgment and idempotent reconciliation, independent of npm processes.
-
-/** Parsed SemVer identifiers, used only to order registry releases and prevent tag rollback. */
-function versionParts(version) {
-  const identifiers = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
-  const parts = typeof version === 'string' ? version.split('+') : [];
-  if (!parts.length || parts.length > 2 || (parts.length === 2 && !identifiers.test(parts[1]))) throw new Error(`unreadable registry release version ${version}`);
-  const boundary = parts[0].indexOf('-');
-  const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
-  const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
-  if (core.length !== 3 || core.some((part) => !/^(0|[1-9]\d*)$/.test(part)) || (prerelease !== null && !identifiers.test(prerelease))) throw new Error(`unreadable registry release version ${version}`);
-  const pre = prerelease?.split('.') ?? [];
-  if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
-  return { core: core.map(BigInt), pre };
-}
-
-const compareIdentifier = (a, b) => {
-  const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
-  if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
-  if (numericA !== numericB) return numericA ? -1 : 1;
-  return a < b ? -1 : Number(a > b);
-};
-
-/** SemVer precedence, including numeric prerelease ordering; build metadata has no precedence. */
-function compareVersions(a, b) {
-  const left = versionParts(a), right = versionParts(b);
-  for (const i of left.core.keys()) {
-    if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
-  }
-  if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
-  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
-    if (left.pre[i] === undefined) return -1;
-    if (right.pre[i] === undefined) return 1;
-    const compared = compareIdentifier(left.pre[i], right.pre[i]);
-    if (compared) return compared;
-  }
-  return 0;
-}
-
-/** Numbered prereleases share their core and nonnumeric prefix; stable releases share major/minor. */
-const releaseLine = (version) => {
-  const { core, pre } = versionParts(version);
-  if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
-  const prefix = /^\d+$/.test(pre.at(-1)) ? pre.slice(0, -1) : pre;
-  return `${core.join('.')}-${prefix.join('.')}`;
-};
+import { compareVersions, releaseLine, versionParts } from './release-version.mjs';
 
 /**
  * Plan the release's declared tags from a complete registry read. Unknown reads and historical
- * releases fail closed; a newer tag on another release line is preserved rather than rolled back.
+ * releases fail closed (alpha.31.1 is behind alpha.31.2 and alpha.32 on the one alpha line); a newer
+ * tag on another release line is preserved rather than rolled back.
  * Returns serializable {tag, version, current, action} entries for the native dry-run plan.
  */
 export function runtimeTagPlan({ version, tags, state, uploadTag = null }) {