@starci/hfs 4.7.33 → 4.7.35

package/runtime/scripts/lib/canon-binding-text.mjs

@@ -0,0 +1,129 @@
+// Canon release binding edits preserve authored profile text and update only the selected binding's identity.
+
+const KEY = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+function supportedBinding(value) {
+  const keys = typeof value === 'string' ? value.split('.') : [];
+  return (keys.length === 1 && keys[0] === 'canon') || (keys.length === 2 && keys[0] === 'familyCanons' && KEY.test(keys[1]));
+}
+
+function lineEntry(line, index) {
+  const text = line.slice(0, line.length - lineEnding(line).length);
+  if (!text.trim() || text.trimStart().startsWith('#')) return null;
+  let indent = 0;
+  while (text[indent] === ' ') indent++;
+  const colon = text.indexOf(':', indent);
+  const key = colon < 0 ? '' : text.slice(indent, colon);
+  if (!KEY.test(key)) return { index, indent };
+  let valueAt = colon + 1;
+  while (text[valueAt] === ' ' || text[valueAt] === '\t') valueAt++;
+  return { index, indent, key, prefix: text.slice(0, valueAt), value: text.slice(valueAt) };
+}
+
+function lineEnding(line) {
+  if (line.endsWith('\r\n')) return '\r\n';
+  return line.endsWith('\n') ? '\n' : '';
+}
+
+function linesOf(text) {
+  const lines = [];
+  let start = 0;
+  for (let index = 0; index < text.length; index++) {
+    if (text[index] !== '\n') continue;
+    lines.push(text.slice(start, index + 1));
+    start = index + 1;
+  }
+  if (start < text.length) lines.push(text.slice(start));
+  return lines;
+}
+
+function child(entries, parent, key, at) {
+  const nested = entries.filter(entry => entry.index > parent.start && entry.index < parent.end && entry.indent > parent.indent);
+  const directIndent = Math.min(...nested.map(entry => entry.indent));
+  const found = nested.filter(entry => entry.indent === directIndent && entry.key === key);
+  if (found.length !== 1) throw new Error(`${at}: expected one ${key} field, found ${found.length}`);
+  const entry = found[0];
+  const boundary = entries.find(candidate => candidate.index > entry.index && candidate.index < parent.end && candidate.indent <= entry.indent);
+  return { ...entry, start: entry.index, end: boundary?.index ?? parent.end };
+}
+
+function mapping(entries, parent, key, at) {
+  const node = child(entries, parent, key, at);
+  if (node.value.trim() && !node.value.trim().startsWith('#')) throw new Error(`${at}.${key}: expected a block mapping`);
+  return node;
+}
+
+function scalar(entries, parent, key, at) {
+  const node = child(entries, parent, key, at);
+  if (!node.value.trim() || node.value.trim().startsWith('#')) throw new Error(`${at}.${key}: expected a scalar value`);
+  return node;
+}
+
+function scalarParts(value) {
+  const quote = value[0] === "'" || value[0] === '"' ? value[0] : null;
+  let end = quote ? value.indexOf(quote, 1) : 0;
+  if (quote && end < 1) return null;
+  if (quote) end++;
+  else {
+    while (end < value.length && value[end].trim() && !['#', "'", '"'].includes(value[end])) end++;
+  }
+  if (!end) return null;
+  let tail = end;
+  while (value[tail] === ' ' || value[tail] === '\t') tail++;
+  if (tail < value.length && (tail === end || value[tail] !== '#')) return null;
+  return { value: quote ? value.slice(1, end - 1) : value.slice(0, end), suffix: value.slice(end) };
+}
+
+function packageValue(value) {
+  return scalarParts(value)?.value;
+}
+
+function replaceScalar(lines, node, value) {
+  const parts = scalarParts(node.value);
+  if (!parts) throw new Error(`Cannot replace malformed scalar ${node.key}`);
+  lines[node.index] = `${node.prefix}${value}${parts.suffix}${lineEnding(lines[node.index])}`;
+}
+
+function bindingNode(entries, root, row) {
+  const at = `profiles.${row.profile}.${row.binding}`;
+  let node = mapping(entries, root, 'profiles', 'document');
+  node = mapping(entries, node, row.profile, 'profiles');
+  for (const key of row.binding.split('.')) node = mapping(entries, node, key, at);
+  const declared = scalar(entries, node, 'package', at);
+  if (packageValue(declared.value) !== row.package) throw new Error(`${at}: package does not match ${row.package}`);
+  return { node, at };
+}
+
+/**
+ * Render release version and digest updates at their exact profile binding paths without reserializing authored YAML.
+ * Unrelated bytes, comments and newline style are preserved. Missing or duplicate mapping paths, unexpected packages,
+ * incomplete digest blocks and invalid replacement identities throw before any caller writes the returned text.
+ * @param {string} original - The authored code-pattern profile YAML.
+ * @param {Array<{profile: string, binding: string, package: string, to: {version: string, value: string, files: number}}>} rows - Exact canon or family binding identities to replace.
+ * @returns {string} Updated profile YAML; the input is returned unchanged when no rows are supplied.
+ */
+export function renderCanonBindingChanges(original, rows) {
+  if (typeof original !== 'string' || !Array.isArray(rows)) throw new Error('canon binding changes need YAML text and identity rows');
+  const lines = linesOf(original);
+  const entries = lines.map((line, index) => lineEntry(line, index)).filter(Boolean);
+  const root = { start: -1, end: lines.length, indent: -1 };
+  const selected = new Set();
+  for (const row of rows) {
+    if (!KEY.test(row?.profile ?? '') || !supportedBinding(row?.binding) || typeof row?.package !== 'string' || !row.package) throw new Error('canon binding changes need a supported profile, package and binding path');
+    const identity = `${row.profile}.${row.binding}`;
+    if (selected.has(identity)) throw new Error(`${identity}: duplicate binding change`);
+    selected.add(identity);
+    if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(row.to?.version ?? '') || !/^[a-f0-9]{64}$/i.test(row.to?.value ?? '')
+      || !Number.isSafeInteger(row.to?.files) || row.to.files < 1) throw new Error(`${identity}: invalid replacement version or digest`);
+    const { node, at } = bindingNode(entries, root, row);
+    const version = scalar(entries, node, 'version', at);
+    const digest = mapping(entries, node, 'contentDigest', at);
+    const value = scalar(entries, digest, 'value', `${at}.contentDigest`);
+    const files = scalar(entries, digest, 'files', `${at}.contentDigest`);
+    replaceScalar(lines, version, row.to.version);
+    // A hexadecimal digest can contain digits only; quoting preserves its string identity in YAML.
+    replaceScalar(lines, value, `'${row.to.value}'`);
+    replaceScalar(lines, files, row.to.files);
+  }
+  return lines.join('');
+}

package/runtime/scripts/lib/example-refs.mjs

@@ -51,7 +51,7 @@ export const REFERENCE_EXAMPLE_APP = 'full-app';
 
 /** The grammar css families a product repository may declare (`[data-grammar-family="<id>"]`); the
  *  runtime's own product maps to the core sheet. */
-export const GRAMMAR_FAMILIES = Object.freeze({ starci: 'core', nivo: 'nivo' });
+export const GRAMMAR_FAMILIES = Object.freeze({ starci: 'core', nivo: 'nivo', 'offset-pop': 'offset-pop' });
 
 /** A feature-folder segment that is only the product's own name - no useful leaf (display-names pathLabel). */
 export const PRODUCT_NAME_SEGMENT = /^(nivo|starci|mia)[-\w]*$/i;

package/runtime/scripts/lib/grammar-lint.mjs

@@ -0,0 +1,48 @@
+// Grammar-family lint selection reads the family catalog; an absent selection never chooses a family.
+import fs from 'node:fs';
+import { parseYamlCached } from './yaml-cached.mjs';
+
+const CATALOG_FILE = new URL('../../knowledge/grammars/index.yaml', import.meta.url);
+
+function selectedFamily(family) {
+  if (typeof family !== 'string' || !family.trim()) throw new Error('sides.fe.grammar must explicitly name the selected Grammar family');
+  const catalog = parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
+  const matches = (catalog.families ?? []).filter(entry => entry.id === family);
+  if (matches.length !== 1) throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
+  return { catalog, selected: matches[0] };
+}
+
+/** The explicitly selected authored family entry; callers share the catalog lookup rather than inferring a family. */
+export function grammarFamilyFor(family) {
+  return Object.freeze(selectedFamily(family).selected);
+}
+
+/** The declared family's lint contract, including an explicit null package when that family has no rules. */
+export function grammarLintFor(family) {
+  const { selected } = selectedFamily(family);
+  if (!selected.lint || !Object.hasOwn(selected.lint, 'package')) {
+    throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
+  }
+  const lint = selected.lint;
+  if (lint.package === null) return Object.freeze({ family, package: null });
+  if (typeof lint.package !== 'string' || !lint.package.startsWith('@starci/eslint-grammar-')
+    || typeof lint.factory !== 'string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(lint.factory)
+    || typeof lint.prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(lint.prefix)) {
+    throw new Error(`Grammar family ${family} has an invalid lint contract in knowledge/grammars/index.yaml`);
+  }
+  return Object.freeze({ family, package: lint.package, factory: lint.factory, prefix: lint.prefix });
+}
+
+/** The selected family's shared component/export contract, resolved through its catalog reference. */
+export function grammarContractFor(family) {
+  const { catalog, selected } = selectedFamily(family);
+  const owners = (catalog.families ?? []).filter(entry => entry.id === selected.contractRef);
+  const contract = owners.length === 1 ? owners[0].componentContract : null;
+  if (!contract || typeof contract.package !== 'string' || !contract.package
+    || typeof contract.entry !== 'string' || !contract.entry.startsWith(`${contract.package}/`)
+    || typeof contract.styleEntry !== 'string' || !contract.styleEntry.startsWith(`${contract.package}/`)
+    || !Array.isArray(contract.peers) || !contract.peers.every(peer => typeof peer === 'string' && peer.trim())) {
+    throw new Error(`Grammar family ${family} has no valid component contract in knowledge/grammars/index.yaml`);
+  }
+  return Object.freeze({ ...contract, peers: Object.freeze([...contract.peers]) });
+}

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

@@ -31,105 +31,29 @@
 import { createHash } from 'node:crypto';
 import { cssRules, ruleFamilies, selectorAttributes, selectorClasses, subjectCompound } from './css-rules.mjs';
 import { byCodeUnit } from './list.mjs';
+import { expressionStrings, heroTags, importAliases, jsxTags, vendorRenderRoots } from './grammar-vendor-source.mjs';
+
+export { heroTags, importAliases } from './grammar-vendor-source.mjs';
 
 export const CODE = 'GRAMMAR_VENDOR_PARITY';
 export const WRAPPERS_SCHEMA = 'starci/vendor-heroui-wrappers@1';
 
+/** 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 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),
-  }));
-}
 
 /** The string literals of an expression, without their quotes. */
 const stringLiterals = (raw) => (String(raw).match(/"[^"\n]*"|'[^'\n]*'|`[^`$]*`/g) ?? []).map((literal) => literal.slice(1, -1));
@@ -154,22 +78,8 @@ function classTokens(text, attrs) {
 const ACCESSIBILITY_MEDIA = /forced-colors|prefers-contrast|pointer:\s*coarse/;
 const OVERRIDE_KINDS = ['slot', 'style', 'default', 'role', 'canon'];
 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.
@@ -208,10 +118,16 @@ function grammarFindings(grammars, files) {
   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'))];
 }
 
-/** 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));
+/** The JSX roles a file writes by hand that the measured vendor references expose. */
+function roleFindings({ file, text, allowed, vendorRoles, roleDeclarations }) {
+  const vendorAliases = importAliases(text);
+  const vendorRenders = vendorRenderRoots(text, vendorAliases, roleDeclarations);
+  const vendorOwnsRole = (tag, role) => {
+    const owner = vendorAliases.get(tag.alias);
+    const declaration = roleDeclarations[role];
+    return owner !== undefined && (declaration?.contracts.includes(`${owner}.${tag.part}`) || (tag.part === 'Root' && declaration?.publicApi === owner));
+  };
+  const roles = jsxTags(text).flatMap((tag) => tag.attrs.filter((attr) => attr.name === 'role').flatMap((attr) => expressionStrings(text, attr.raw)).filter((role) => !vendorOwnsRole(tag, role) && !vendorRenders.some((root) => tag.index === root.index && root.roles.includes(role)))).filter((role) => vendorRoles.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})`));
 }
 
@@ -347,10 +263,14 @@ function cssFindings({ styles, references, stamps, allowed, strictOf }) {
  *   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 }) {
   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);
@@ -362,7 +282,7 @@ export function parityFindings({ references, manifest, sources, styles }) {
     ...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 }),
     ]),
     ...cssFindings({ styles, references, stamps: stampsOf(sources, rows, byName, references, strictOf), allowed, strictOf }),
     ...stale(),