@starci/hfs 4.15.0 → 4.16.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.16.0 - 2026-10-31
+
+- Added: `starci app codemod spacing-roles [--execute] [--json] [--format json|markdown] [--out <file>]`: a dry run by default; plain flex column and row `div`s whose only spacing is one gap become `Stack` and `Cluster` bound from the file's Grammar import (gap-1 identity, gap-2 inline, gap-3 row, gap-4 section, gap-6 and gap-8 region, gap-8 marked for review); every other spacing utility is reported with its suggested role, and the report counts the utilities by family.
+- Changed: `starci app lint` reports an ESLint warning (a rule of the canon's counting cohort) with severity `warning`, counts them per rule (`counts.warning`, `counting`) and keeps them out of the verdict and the error threshold.
+- Changed: the canon pins name @starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.18.0, eslint-canon-fe 9.8.0, stylelint-canon 2.4.0 and hfs 4.16.0; R350 joins the bundled rule catalog.
+
 ## 4.15.0 - 2026-10-31
 
 - Added: R345 `FE_PANE_GRID_CHILD_NOT_PANE`, R346 `FE_PANE_CHILD_NOT_SECTION`, R347 `FE_PANE_SECTION_PADDING` and R348 `FE_PANE_GRID_FRAME` (eslint-grammar-core `pane-grid-children`, `pane-children`, `no-pane-section-padding`, `pane-grid-page`) and R349 `FE_HAND_BUILT_PANES` (eslint-canon-fe `no-hand-built-panes`) in the bundled rule catalog.

package/codemod/main.d.mts

@@ -0,0 +1,16 @@
+/** The codemods `starci app codemod` runs, by name. */
+export declare const CODEMODS: readonly string[];
+/** The arguments of `starci app codemod spacing-roles`: --execute, --json, --format and --out; any other is refused. */
+export declare function spacingRolesArguments(argv: readonly string[]): {
+    write: boolean;
+    format: 'json' | 'markdown';
+    out?: string;
+};
+/**
+ * CLI boundary of `starci app codemod <name>`. Dry run by default; --execute writes only the safe rewrites. A codemod
+ * that leaves a case for a person exits 1 with the complete report.
+ */
+export declare function codemodMain(argv: string[], io: {
+    cwd: string;
+    stdout: (text: string) => unknown;
+}): number;

package/codemod/main.mjs

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { codemodMain as buttonIntentMain } from './button-intent.mjs';
+import { migrateSpacingRoles, spacingRolesMarkdown } from './spacing-roles.mjs';
+/** The codemods `starci app codemod` runs, by name. */
+export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles']);
+/** The arguments of `starci app codemod spacing-roles`: --execute, --json, --format and --out; any other is refused. */
+export function spacingRolesArguments(argv) {
+    const options = { write: false, format: 'markdown' };
+    const args = argv.values();
+    for (const arg of args) {
+        const [flag, inline] = arg.split(/=(.*)/s);
+        if (flag === '--execute' || flag === '--json') {
+            if (inline !== undefined && !['true', 'false'].includes(inline))
+                throw new Error(`${flag} expects true or false`);
+            const value = inline === undefined || inline === 'true';
+            if (flag === '--execute')
+                options.write = value;
+            else if (value)
+                options.format = 'json';
+        }
+        else if (flag === '--format' || flag === '--out') {
+            const value = inline ?? args.next().value;
+            if (!value || value.startsWith('--'))
+                throw new Error(`${flag} needs a value`);
+            if (flag === '--out')
+                options.out = value;
+            else if (value === 'json' || value === 'markdown')
+                options.format = value;
+            else
+                throw new Error('--format accepts json or markdown');
+        }
+        else
+            throw new Error(`unknown codemod option ${arg}`);
+    }
+    return options;
+}
+/**
+ * CLI boundary of `starci app codemod <name>`. Dry run by default; --execute writes only the safe rewrites. A codemod
+ * that leaves a case for a person exits 1 with the complete report.
+ */
+export function codemodMain(argv, io) {
+    const [name, ...rest] = argv;
+    if (name === 'button-intent')
+        return buttonIntentMain(argv, io);
+    if (name !== 'spacing-roles')
+        throw new Error(`starci app codemod takes ${CODEMODS.join(' or ')}`);
+    const options = spacingRolesArguments(rest);
+    if (options.out && !/\.(?:json|md)$/i.test(options.out))
+        throw new Error('--out needs a .json or .md report file');
+    const report = migrateSpacingRoles({ root: path.resolve(io.cwd), write: options.write });
+    const output = options.format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : spacingRolesMarkdown(report);
+    if (options.out) {
+        const target = path.resolve(io.cwd, options.out);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, output);
+    }
+    io.stdout(output);
+    return report.findings.length ? 1 : 0;
+}

package/codemod/spacing-roles.d.mts

@@ -0,0 +1,60 @@
+/** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** One rewrite of the report: a layout element whose classes were only a flex column or row and its gap. */
+export interface SpacingChange {
+    file: string;
+    line: number;
+    column: number;
+    from: string;
+    to: string;
+    review?: string;
+}
+/** One spacing utility the codemod leaves for a person, with the role it suggests when it has one. */
+export interface SpacingFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    utility: string;
+    suggestion: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod spacing-roles`). */
+export interface SpacingReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    /** Every spacing utility of the scanned source by family (gap, padding, margin, space), before the rewrite. */
+    counts: Record<string, number>;
+    changes: SpacingChange[];
+    findings: SpacingFinding[];
+}
+/** The role each Tailwind gap step names (the doctrine's mapping); `review` marks a step whose role a person confirms. */
+export declare const GAP_ROLES: Readonly<Record<string, {
+    role: string;
+    review?: string;
+}>>;
+/** The spacing utilities of one class string. */
+export declare const spacingUtilities: (text: string) => string[];
+/** Rewrite one source text: plain `div` flex columns and rows whose only spacing is one gap become Stack and Cluster. */
+export declare function transformSpacingRoles({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: SpacingChange[];
+    findings: SpacingFinding[];
+    counts: Record<string, number>;
+};
+/** Preview or apply the safe rewrites in one app's FE tree; every utility left is in the report with its suggested role. */
+export declare function migrateSpacingRoles({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): SpacingReport;
+/** Render the migration and the utilities left for a person as Markdown; JSON consumers read the same report object. */
+export declare function spacingRolesMarkdown(report: SpacingReport): string;
+export {};

package/codemod/spacing-roles.mjs

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { sourceLocation } from '../runtime/scripts/lib/ts-ast.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GRAMMAR = /^@starci\/grammar(?:\/(?:core|common|offset-pop))?$/;
+const GENERATED = new Set(['node_modules', '.next', '.turbo', 'dist', 'coverage', '.git']);
+const SPACING_UTILITY = /^-?(p|px|py|pt|pb|ps|pe|pl|pr|m|mx|my|mt|mb|ms|me|ml|mr|gap|gap-x|gap-y|space-x|space-y)-(.+)$/;
+/** The role each Tailwind gap step names (the doctrine's mapping); `review` marks a step whose role a person confirms. */
+export const GAP_ROLES = Object.freeze({
+    '1': { role: 'identity' },
+    '2': { role: 'inline' },
+    '3': { role: 'row' },
+    '4': { role: 'section' },
+    '6': { role: 'region' },
+    '8': { role: 'region', review: 'gap-8 and gap-6 both become region; confirm the two blocks are page regions with their own heading' },
+});
+/** Classes a Stack or Cluster already draws, so an element holding only these and one gap becomes the primitive. */
+const STACK_CLASSES = new Set(['flex', 'flex-col', 'min-w-0']);
+const CLUSTER_CLASSES = new Set(['flex', 'flex-row', 'flex-wrap', 'items-center', 'min-w-0']);
+const family = (utility) => {
+    const name = SPACING_UTILITY.exec(utility.replace(/^!|!$/g, ''))?.[1] ?? '';
+    return name.startsWith('gap') ? 'gap' : name.startsWith('space') ? 'space' : name.startsWith('p') ? 'padding' : 'margin';
+};
+/** The utility once its variants are dropped (`sm:gap-2` is `gap-2`); a variant marks a responsive or state choice. */
+const baseOf = (cls) => cls.slice(cls.lastIndexOf(':') + 1);
+/** The spacing utilities of one class string. */
+export const spacingUtilities = (text) => text.split(/\s+/).filter((cls) => SPACING_UTILITY.test(baseOf(cls).replace(/^!|!$/g, '')));
+/** What a person writes instead of one utility the codemod does not rewrite. */
+const suggestionFor = (utility) => {
+    const base = baseOf(utility);
+    const kind = family(base);
+    if (kind === 'gap' || kind === 'space') {
+        const step = /-(\d+)$/.exec(base)?.[1] ?? '';
+        const mapped = GAP_ROLES[step];
+        return mapped ? `gap="${mapped.role}" on a Stack or Cluster` : 'the role of the relation on a Stack, Cluster or Grid';
+    }
+    return kind === 'margin' ? "the parent's gap role" : 'the inset of the Grammar box that holds the content';
+};
+/** The Grammar import that binds Stack and Cluster in a file: the family specifier it already imports. */
+function grammarImport(ts, source) {
+    for (const node of source.statements) {
+        if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier) || !GRAMMAR.test(node.moduleSpecifier.text))
+            continue;
+        const bindings = node.importClause?.namedBindings;
+        if (bindings === undefined || !ts.isNamedImports(bindings) || node.importClause?.isTypeOnly)
+            continue;
+        return { specifier: node.moduleSpecifier.text, node, names: new Set(bindings.elements.map((element) => element.name.text)) };
+    }
+    return null;
+}
+/** The static class string of an element, or null when it is computed. */
+function classText(ts, attribute) {
+    const value = attribute?.initializer;
+    if (value === undefined)
+        return null;
+    if (ts.isStringLiteral(value))
+        return value.text;
+    if (ts.isJsxExpression(value) && value.expression !== undefined && ts.isStringLiteralLike(value.expression))
+        return value.expression.text;
+    return null;
+}
+/** The primitive and its props an element's classes ask for, or why it stays for a person. */
+function primitiveFor(classes) {
+    const gaps = classes.filter((cls) => /^gap-\d+$/.test(cls));
+    if (gaps.length !== 1)
+        return { reason: 'the element holds no single plain gap utility' };
+    const step = (gaps[0] ?? '').slice(4);
+    const mapped = GAP_ROLES[step];
+    if (mapped === undefined)
+        return { reason: `gap-${step} names no role; choose the relation` };
+    const rest = classes.filter((cls) => cls !== gaps[0]);
+    const review = mapped.review === undefined ? {} : { review: mapped.review };
+    if (rest.includes('flex-col') && rest.every((cls) => STACK_CLASSES.has(cls)))
+        return { tag: 'Stack', props: `gap="${mapped.role}"`, ...review };
+    if (rest.includes('flex') && !rest.includes('flex-col') && rest.every((cls) => CLUSTER_CLASSES.has(cls))) {
+        if (mapped.role === 'region')
+            return { reason: 'a cluster never holds regions; a region gap belongs to a Stack or a Grid' };
+        return { tag: 'Cluster', props: `gap="${mapped.role}"${rest.includes('flex-wrap') ? '' : ' wrap={false}'}`, ...review };
+    }
+    return { reason: 'the element carries layout classes a Stack or Cluster does not draw; move them to a Grammar API first' };
+}
+/** Rewrite one source text: plain `div` flex columns and rows whose only spacing is one gap become Stack and Cluster. */
+export function transformSpacingRoles({ ts, text, file = 'component.tsx' }) {
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : ts.ScriptKind.TSX);
+    const changes = [];
+    const findings = [];
+    const counts = {};
+    const edits = [];
+    const needed = new Set();
+    const imported = grammarImport(ts, source);
+    const leave = (node, utility, code, reason) => {
+        findings.push({ file, ...sourceLocation(source, node), code, utility, suggestion: suggestionFor(utility), reason });
+    };
+    const visitString = (node) => {
+        for (const utility of spacingUtilities(node.text)) {
+            counts[family(baseOf(utility))] = (counts[family(baseOf(utility))] ?? 0) + 1;
+            leave(node, utility, 'class-string', 'a class string outside a plain layout element; name the relation where it is used');
+        }
+    };
+    const visitElement = (opening, element) => {
+        const attributes = opening.attributes.properties;
+        const classAttribute = attributes.find((entry) => ts.isJsxAttribute(entry) && entry.name.getText(source) === 'className');
+        const text = classText(ts, classAttribute);
+        if (text === null)
+            return;
+        const utilities = spacingUtilities(text);
+        for (const utility of utilities)
+            counts[family(baseOf(utility))] = (counts[family(baseOf(utility))] ?? 0) + 1;
+        if (utilities.length === 0)
+            return;
+        const classes = text.split(/\s+/).filter(Boolean);
+        const others = attributes.filter((entry) => entry !== classAttribute && !(ts.isJsxAttribute(entry) && entry.name.getText(source) === 'key'));
+        const isDiv = opening.tagName.getText(source) === 'div';
+        const target = primitiveFor(classes);
+        const reason = !isDiv ? 'only a plain div becomes a layout primitive' : others.length > 0 ? 'the element carries props a layout primitive does not take' : imported === null ? 'the file imports no Grammar family to bind the primitive from' : 'reason' in target ? target.reason : null;
+        if (reason !== null || 'reason' in target) {
+            for (const utility of utilities)
+                leave(opening, utility, 'layout-element', reason ?? 'the element stays for a person');
+            return;
+        }
+        needed.add(target.tag);
+        const key = attributes.find((entry) => ts.isJsxAttribute(entry) && entry.name.getText(source) === 'key');
+        const props = `${target.tag} ${target.props}${key === undefined ? '' : ` ${key.getText(source)}`}`;
+        edits.push({ start: opening.getStart(source), end: opening.end, replacement: ts.isJsxSelfClosingElement(opening) ? `<${props} />` : `<${props}>` });
+        if (ts.isJsxElement(element))
+            edits.push({ start: element.closingElement.getStart(source), end: element.closingElement.end, replacement: `</${target.tag}>` });
+        changes.push({ file, ...sourceLocation(source, opening), from: text, to: `<${target.tag} ${target.props}>`, ...(target.review === undefined ? {} : { review: target.review }) });
+    };
+    const visit = (node) => {
+        if (ts.isJsxElement(node))
+            visitElement(node.openingElement, node);
+        else if (ts.isJsxSelfClosingElement(node))
+            visitElement(node, node);
+        else if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && !ts.isJsxAttribute(node.parent) && !ts.isImportDeclaration(node.parent) && !(ts.isJsxExpression(node.parent) && ts.isJsxAttribute(node.parent.parent)))
+            visitString(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (imported !== null) {
+        const missing = [...needed].filter((name) => !imported.names.has(name)).sort();
+        const bindings = imported.node.importClause?.namedBindings;
+        if (missing.length > 0 && bindings !== undefined && ts.isNamedImports(bindings)) {
+            const names = [...bindings.elements.map((element) => element.getText(source)), ...missing];
+            edits.push({ start: bindings.getStart(source), end: bindings.end, replacement: `{ ${names.join(', ')} }` });
+        }
+    }
+    let output = text;
+    for (const edit of edits.sort((first, second) => second.start - first.start))
+        output = output.slice(0, edit.start) + edit.replacement + output.slice(edit.end);
+    return { text: output, changes, findings, counts };
+}
+function sourceFiles(directory) {
+    return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const target = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return GENERATED.has(entry.name) ? [] : sourceFiles(target);
+        return entry.isFile() && /\.[jt]sx?$/i.test(entry.name) && !/\.(?:spec|test|d)\.[jt]sx?$/i.test(entry.name) ? [target] : [];
+    }).sort();
+}
+/** Preview or apply the safe rewrites in one app's FE tree; every utility left is in the report with its suggested role. */
+export function migrateSpacingRoles({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+    if (!ts)
+        throw new Error('spacing-roles needs TypeScript installed in the app or @starci/hfs development checkout');
+    const frontend = path.join(root, 'fe');
+    if (!fs.statSync(frontend, { throwIfNoEntry: false })?.isDirectory())
+        throw new Error('spacing-roles runs at an app root with a fe/ directory');
+    const report = { schema: 'starci/spacing-roles-codemod@1', root, write, filesScanned: 0, filesChanged: [], counts: {}, changes: [], findings: [] };
+    for (const target of sourceFiles(frontend)) {
+        const file = path.relative(root, target).split(path.sep).join('/');
+        const original = fs.readFileSync(target, 'utf8');
+        const result = transformSpacingRoles({ ts, text: original, file });
+        report.filesScanned += 1;
+        report.changes.push(...result.changes);
+        report.findings.push(...result.findings);
+        for (const [name, count] of Object.entries(result.counts))
+            report.counts[name] = (report.counts[name] ?? 0) + count;
+        if (result.text !== original) {
+            report.filesChanged.push(file);
+            if (write)
+                fs.writeFileSync(target, result.text);
+        }
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migration and the utilities left for a person as Markdown; JSON consumers read the same report object. */
+export function spacingRolesMarkdown(report) {
+    const counts = Object.entries(report.counts).sort().map(([name, count]) => `${name} ${count}`).join(', ') || 'none';
+    return ['# Spacing roles migration', '',
+        `${report.write ? 'Applied' : 'Dry run'}: ${report.changes.length} rewrites in ${report.filesChanged.length} files of ${report.filesScanned}; ${report.findings.length} utilities left for a person.`, '',
+        `Spacing utilities before: ${counts}.`, '',
+        '## Rewrites', '', '| Location | Classes | Becomes | Review |', '| --- | --- | --- | --- |',
+        ...report.changes.map((change) => `| ${cell(`${change.file}:${change.line}:${change.column}`)} | ${cell(change.from)} | ${cell(change.to)} | ${cell(change.review ?? '')} |`), '',
+        '## Left for a person', '', '| Location | Utility | Suggestion | Reason |', '| --- | --- | --- | --- |',
+        ...report.findings.map((finding) => `| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${cell(finding.utility)} | ${cell(finding.suggestion)} | ${cell(finding.reason)} |`), ''].join('\n');
+}

package/lint/run.mjs

@@ -168,7 +168,7 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null }) {
     return { results, ...(completed ? {} : { error: `${pkg} could not complete in ${path.basename(cwd)}/ (exit ${run.status}, signal ${run.signal ?? 'none'}): ${String(run.error?.message || run.stderr || run.stdout || '').trim().split('\n')[0]}` }) };
 }
 const eslintFindings = (results, appRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
-    engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: 'error',
+    engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: message.severity === 1 ? 'warning' : 'error',
     path: posix(path.relative(appRoot, result.filePath)), line: message.line ?? null, column: message.column ?? null, message: message.message,
 })));
 const stylelintFindings = (results, appRoot) => results.flatMap((result) => (result.warnings ?? []).map((warning) => ({
@@ -676,18 +676,27 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
         linterReport('eslint', raw.eslint, { root: repoRoot, sourceRoots, tracked }),
         linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked }),
     ]);
-    // Green under the threshold (gate-threshold.mjs): every finding is still reported, only the verdict changes.
-    const gate = gateVerdict(findings);
-    const report = { schema: LINT_SCHEMA, ok: gate.pass && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, ...(opts.side === undefined ? {} : { side: opts.side }), counts: { error: findings.length }, engines, errors, findings, gate };
+    // Green under the threshold (gate-threshold.mjs): every finding is still reported, only the verdict changes. A warning is a
+    // rule of the canon's counting cohort (eslint-canon-fe COUNTING): reported and counted per rule, never part of the verdict.
+    const failing = findings.filter((finding) => finding.severity !== 'warning');
+    const counting = {};
+    for (const finding of findings)
+        if (finding.severity === 'warning')
+            counting[finding.rule] = (counting[finding.rule] ?? 0) + 1;
+    const gate = gateVerdict(failing);
+    const report = { schema: LINT_SCHEMA, ok: gate.pass && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, ...(opts.side === undefined ? {} : { side: opts.side }), counts: { error: failing.length, warning: findings.length - failing.length }, counting, engines, errors, findings, gate };
     return { report, sonar, exit: errors.length ? 2 : gate.pass ? 0 : 1 };
 }
 export function printLintText(report, out) {
     for (const f of report.findings)
-        out(`${f.path ?? '-'}${f.line ? `:${f.line}${f.column ? `:${f.column}` : ''}` : ''}  ${f.engine}/${f.rule}  ${f.message}\n`);
+        out(`${f.path ?? '-'}${f.line ? `:${f.line}${f.column ? `:${f.column}` : ''}` : ''}  ${f.severity === 'warning' ? 'warn ' : ''}${f.engine}/${f.rule}  ${f.message}\n`);
     for (const e of report.errors)
         out(`ERROR ${e}\n`);
-    const per = Object.keys(report.engines).map((engine) => `${engine} ${report.findings.filter((f) => f.engine === engine).length}`).join(', ');
+    const per = Object.keys(report.engines).map((engine) => `${engine} ${report.findings.filter((f) => f.engine === engine && f.severity !== 'warning').length}`).join(', ');
     out(`\nstarci app lint: ${report.counts.error} finding${report.counts.error === 1 ? '' : 's'} (${per})${report.errors.length ? `, ${report.errors.length} tool error${report.errors.length === 1 ? '' : 's'}` : ''}\n`);
+    const counting = Object.entries((report.counting ?? {})).sort(([a], [b]) => a.localeCompare(b));
+    if (counting.length)
+        out(`counting (warn, not in the verdict): ${counting.map(([rule, count]) => `${rule} ${count}`).join(', ')}\n`);
     if (report.gate?.line)
         out(`${report.gate.line}\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.15.0",
+  "version": "4.16.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,42 +31,42 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.17.0
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.11.0
+    version: 3.11.1
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.7.0
+    version: 9.8.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.17.0
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.17.0
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.3.0
+    version: 2.4.0
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.15.0
+    version: 4.16.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -6184,3 +6184,27 @@ rules:
         source: owner
         quote: "sao trang lan agent có gap 1 khoảng trên vậy??? … phải dính vào chứ"
         ruling: "A multi-pane frame is the Grammar's PaneGrid, never columns and a vertical Divider composed by hand inside a card."
+  - id: R350
+    code: "FE_SPACING_UTILITY"
+    law: "Every spacing value is the Grammar's, on its one scale 0 4 8 12 24 32: an app names the relation between the blocks it places through a role prop (Stack and Cluster gap identity, inline, row, section or region; Grid kind cards, form or main-rail; PaneSection; Page) and writes no padding, margin, gap or space utility and no arbitrary spacing value in a class string; a Grammar stylesheet writes no spacing length off the scale and no fluid spacing value."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_SPACING_UTILITY", "FE_SPACING_OFF_SCALE"]
+    enforcers:
+      - {kind: eslint-fe, id: no-spacing-utility}
+      - {kind: stylelint, id: spacing-scale}
+    editions: [lite, full]
+    docs: [contexts/ui/presentation.md]
+    templateNa: "A template's own layout is moved onto the role props by starci app codemod spacing-roles; the rule counts at warn for one cohort."
+    proves:
+      - {path: packages/eslint-canon-fe/src/spacing.spec.ts, editions: [lite, full], codes: [FE_SPACING_UTILITY]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/spacing.spec.ts, editions: [lite, full], codes: [FE_SPACING_UTILITY]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/spacing.spec.ts, editions: [lite, full], codes: [FE_SPACING_UTILITY]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "hay full 3 bỏ 4 đi!!! thầy nghĩ nên v"
+        ruling: "One spacing scale with no 16; every container holds its content 12 in, and an app names relations through role props, never spacing utilities."

package/src/main.mjs

@@ -129,7 +129,7 @@ import { BOOLEAN as CI_BOOLEAN, COMMANDS as CI_COMMANDS } from '../ci/cli.mjs';
 import { LOCAL_FLAGS as CI_LOCAL_FLAGS } from '../ci/local.mjs';
 import { USAGE as COVERAGE_USAGE } from '../coverage/cli.mjs';
 import { SYNC_USAGE } from '../sync/cli.mjs';
-import { codemodMain } from '../codemod/button-intent.mjs';
+import { codemodMain } from '../codemod/main.mjs';
 /** A value flag as parse stores it: the string given, else undefined. */
 const valueFlag = (opts, flag) => { const given = opts[flag]; return typeof given === 'string' ? given : undefined; };
 /** A boolean flag as parse stores it: true when given, else undefined. */
@@ -192,7 +192,7 @@ const DATABASE_USAGE = [['new', '<kebab-name>', DB_NEW_FLAGS], ['baseline', '',
 const VERB_USAGE = {
     ...Object.fromEntries(Object.entries(PARSED).map(([verb, spec]) => [verb, spec.forms.map((form) => line(`starci app ${verb}`, form.operands, specUsage(form.only ?? (form.flags === undefined ? spec : { value: form.flags })), spec.edition && form.edition !== false ? flagUsage('--edition', { value: true }) : ''))])),
     lint: ['starci app lint [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--full] [--full] [--json] [--out <file>]'],
-    codemod: ['starci app codemod button-intent [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]'],
+    codemod: ['starci app codemod button-intent [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]', 'starci app codemod spacing-roles [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]'],
     upgrade: ['starci app upgrade [--execute]'],
     sync: [SYNC_USAGE.sync],
     world: ['starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--edition full|lite]'],