@starci/hfs 4.7.35 → 4.7.37

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

@@ -8,32 +8,30 @@
 //
 // 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 { expressionStrings, heroTags, importAliases, jsxTags, vendorRenderRoots } from './grammar-vendor-source.mjs';
-
-export { heroTags, importAliases } from './grammar-vendor-source.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';
@@ -55,34 +53,19 @@ export const manifestDigest = (text) => createHash('sha256').update(String(text
 
 const finding = (rule, file, line, message) => ({ code: CODE, rule, file, line, message: `${rule}: ${message}` });
 
-/** 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 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);
-}
-
 // ---------------------------------------------------------------------------
 // The judgment.
 // ---------------------------------------------------------------------------
 
 /** 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'];
 const overrideKey = (kind, target) => `${kind}:${target}`;
 
 /**
  * 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();
@@ -100,38 +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 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})`));
+/** 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];
 }
 
-/** The part findings of one wrapped component: parts that are not the vendor's, required parts left out, the divider between sections. */
+/** 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: 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) {
@@ -144,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));
@@ -191,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));
     }
@@ -222,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) }) : []));
       }
     }
   }
@@ -259,11 +291,12 @@ 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: vendorReferences, 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;
@@ -274,17 +307,17 @@ export function parityFindings({ references: vendorReferences, manifest, sources
   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, vendorRoles, roleDeclarations: roleReference.roles }),
+      ...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/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 }) {

package/src/main.mjs

@@ -91,13 +91,15 @@ import { dbMigrateMain } from '../db/migrate.mjs';
 import { dbPostCutoverMain } from '../db/post-cutover.mjs';
 import { dbDumpMain } from '../db/dump.mjs';
 import { dbResetMain } from '../db/reset.mjs';
+import { codemodMain } from '../codemod/button-intent.mjs';
 
-export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene', 'coverage']);
+export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene', 'coverage', 'codemod']);
 const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [options] [--cwd <dir>]
 starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
+starci app codemod button-intent [--write] [--format json|markdown] [--report <file.json|file.md>] [--cwd <dir>]
 starci app sync (--check | --write) [--cwd <dir>]
 starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--db-types] [--wiring] [--coverage-from <lcov>]
 starci app db baseline [--stamp <version>] [--local] [--apply] [--cwd <dir>]
@@ -431,7 +433,7 @@ async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr
   return run(argv, { cwd, out, err });
 }
 
-const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain], ['coverage', async (argv, io) => (await import('../coverage/cli.mjs')).coverageMain(argv, io)]]);
+const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain], ['coverage', async (argv, io) => (await import('../coverage/cli.mjs')).coverageMain(argv, io)], ['codemod', codemodMain]]);
 const PARSED_VERBS = new Map([['check', checkMain], ['emit', emitMain], ['new', newMain], ['add', addMain], ['scaffold', scaffoldMain], ['explain', explainMain]]);
 
 function dispatchMain(verb, argv, io) {

package/sync/hygiene.mjs

@@ -58,7 +58,7 @@ export function hygieneFindings(files, ignored) {
     if (file.startsWith(WORK) && ignored.has(file)) {
       findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
     }
-    if (file.startsWith(STACKS) && !file.endsWith('.enc') && !file.endsWith('.env.example')) {
+    if (file.startsWith(STACKS) && !file.endsWith('.enc') && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
       if (file.includes('/secrets/')) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
       else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to .starcistacks/<env>/secrets/<slug>.enc' });
     }

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.spec.ts

@@ -167,8 +167,8 @@ describe("JsonLogger outside a correlation scope", () => {
         logger.warn("cart.slow")
 
         expect(written.map((entry) => entry.line)).toEqual([
-            `${JSON.stringify({ level: "info", event: "cart.opened", time: "2026-05-06T07:08:09.000Z", correlationId: "00000000-0000-4000-8000-000000000001" })}\n`,
-            `${JSON.stringify({ level: "warn", event: "cart.slow", time: "2026-05-06T07:08:09.000Z", correlationId: "00000000-0000-4000-8000-000000000001" })}\n`,
+            `${JSON.stringify({ correlationId: "00000000-0000-4000-8000-000000000001", level: "info", event: "cart.opened", time: "2026-05-06T07:08:09.000Z" })}\n`,
+            `${JSON.stringify({ correlationId: "00000000-0000-4000-8000-000000000001", level: "warn", event: "cart.slow", time: "2026-05-06T07:08:09.000Z" })}\n`,
         ])
     })
 })

package/templates/fe/common/site-shell.tsx.partial

@@ -1,6 +1,7 @@
 export const SiteShell = (props: SiteShellProps) => (
     <GrammarRoot className={siteShellClassNames.frame}>
         <WorkspaceShell
+            viewport="flow"
             primaryLabel={props.brand}
             header={<TopBar brand={<TextAction href={props.homeHref}>{props.brand}</TextAction>} />}
             primary={<PageContainer measure="reading">{props.children}</PageContainer>}