@starci/hfs 4.16.5 → 4.17.2

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## Unreleased
+
+## 4.17.2 - 2026-11-02
+
+- Changed: bundled pins follow Grammar 0.21.2 with disabled tab items and its coherent canon cohort; existing runtime checks are unchanged.
+
+## 4.17.1 - 2026-11-02
+
+- Fixed: unit provider contracts recognize the real Nest `Optional()` injection decorator through direct, aliased and namespace imports; TypeScript optional parameters and unrelated decorator names still require their providers.
+- Fixed: cross-file `label-in-grid` judges the nearest peer-card layout (`Grid kind="cards"`), matching the existing one-file rule. Dated week regions keep their day headings; labelled peer tiles still fail, with generic regression coverage for both semantic week layouts and nested layout ownership. Bundled R356 knowledge names the same owner.
+
+## 4.17.0 - 2026-11-02
+
+- Fixed: the architecture machine run on an app root that has its own tsconfig threw "Cannot destructure property 'lines'" out of `checkClones`: the app resolver has no rule parameters, so the clone threshold (`ruleParams.common.duplicateBlock`, shared by every profile) is read from a side. Spec `architecture-clones-app-root`.
+- Changed: the bundled playbooks, rule catalog, failure codes and draw script name the one card (`SurfaceCard kind="list"`, `kind="accordion"`) and Page's header slot; no SurfaceListCard, SurfaceAccordionCard or SectionHeader remains in `runtime`.
+- Removed: `NavigationFeatureNav` from the surface names and the bundled Core playbook (the component is gone; `TopBar` takes `subnavigation`).
+- Changed: the bundled rule catalog words the laws of R348, R351, R352 and R355 for the one card (no SurfaceListCard, SectionHeader or PageHeader).
+- Changed: the status owners of the scaffold follow the flag-union `DataSlot` (`isLoading`, `isError`, `isForbidden`, `isEmpty`; `items` only on the ready member; `isValidating` beside data) and gain `slotOfReads` and `useSlotOfReads`; `isSkeleton` is `isLoading` in every template.
+- Added: the codemod `loading-states` (`starci app codemod loading-states [--execute] [--json]`) for the grammar loading law: `isSkeleton` becomes `isLoading` on every Grammar element (and on an `isSkeleton` key inside a Grammar attribute, such as a breadcrumb item), `loadingRows` and a bubble skeleton's `rows` go, and an object literal in a `DataSlot` position loses its `items: undefined` (`SLOT_LITERAL_FLAGS`: `{ isLoading: true }`, `{ isError: true }`, `{ isForbidden: true }`, or `{ isEmpty: true }`); reported for a person: `LOADING_NAME_CONFLICT`, `IS_SKELETON_KEY`, `LOADING_CONTENT`, `SLOT_ITEMS_ACCESS`, `SLOT_LITERAL`, `HAND_SKELETON`, `SWR_DEFAULT_ARRAY`, `PLACEHOLDER_OBJECT`, `VALIDATING_AS_LOADING` and `FOREIGN_SLOT_STATUS`.
+- Added: `tiers.grammar` in `knowledge/hfs/slots.yaml` (leaf, branch, composite, frame: a tier imports nothing above it) and the machine check `FE_GRAMMAR_TIER_DIRECTION` / `FE_GRAMMAR_TIER_STAMP` over a component library (`src/core/<tier>/<Name>/`): an import that climbs, a type-only one and one through a shared module included, and a `data-tier` stamp that is not the folder. `checkComponentLayers` runs the layer order over a component tree no hfs slot judges.
+- Added: the codemod `tier-binding` (`starci app codemod tier-binding [--execute] [--json]`) for the grammar's tier binding: a child that became a prop (`Tooltip` `trigger`, `Disclosure`, `DragItem` and `MessageBubble` `body`, `MediaFrame` `media`, `Field` `control`, `Quote` `text`) moves into it, and `TAKES_NO_CHILDREN`, `LABEL_NOT_TEXT`, `CLASS_NAME_REMOVED`, `TOOLTIP_DISABLED_TRIGGER` and `CHILD_NOT_TEXT` are reported for a person.
+- Changed: the scaffold follows the binding. `SlotView` takes a `render` function (not `children`), the `branch` unit takes a `body` slot, and `SiteShell`, which hosts the page, is a frame (`components/frames/SiteShell`, `packages/<project>-ui/src/frames/SiteShell`).
+- Added: the render graph of the architecture machine (`render-graph.mts`: which component draws which, and where each places `children` and slot props) and two checks built on it: `surface-nesting` (R356, `FE_SURFACE_NESTING`: a card in a card, in `Pane surface` or in an overlay; a `DataTable` in a card; a `PaneGrid` outside `Page chrome="panes"`; a `Section` or `Heading` holding one card; a labelled card repeated in a `Grid`) and `render-prop-across-server` (R361, `FE_RENDER_PROP_ACROSS_SERVER`).
+- Added: catalog entries R356 to R359, R361 and R367; every rule of `rules.yaml` names a doc.
+- Changed: `starci app codemod` usage is derived from `CODEMODS`, so a new codemod cannot be missing from it. The bundle manifests of eslint-canon-be and eslint-grammar-core take `knowledge/hfs/rules.yaml` from hfs (it was a hand-kept copy that drifted), and the new architecture files are listed.
+- Removed: failure code `FE_BUTTON_NO_VARIANT`.
+
+- Added: the codemod `page-navigation` (`starci app codemod page-navigation [--execute] [--json]`) for the grammar's page and navigation cuts: `PrimaryRailLayout` to `Grid kind="main-rail"` and `FormGrid` to `Grid kind="form"` (a `className` or a spread blocks the rewrite), and every use of `PageHeader`, `PageContainer`, `Breadcrumbs`, `FillViewport`, `Rail`, `NavigationFeatureNav`, `Subnav` and `BottomNav` is reported with a code and the way to `Page`, `Grid` or `TopBar`.
+- Changed: `starci app add layout` draws `Grid kind="main-rail"` and `starci app add overlay --form` a `Grid kind="form"`; R323 to R325 law text follows (the page parts are not exports).
+
+- Added: the codemod `section-frame` (`starci app codemod section-frame [--execute] [--json]`) for the sections of the grammar: `Region` with a `SectionHeader` first in it, and a `SectionHeader` leading a plain wrapper, become one `Section`; `Region label` becomes `Section title` (reported, since the heading is new); `CollectionItem`, `ItemActions` and `ToolbarActions` become fragments; `Text weight` becomes `isStrong`. Reported for a person: `List`, `ListItem`, `LeadingNumber`, `Label`, a head with an eyebrow, a context-intro or rank 1, the removed `Text` values, and a strong block `Text` that heads a group (`TEXT_HEADING_FAKE`).
+
+- hfs: codemod `surface-card-kinds` (`starci app codemod surface-card-kinds`).
+- Added: the `frames` component tier for apps (grammar audit 2026-11, decision 9): slot `fe.components` layers are `blocks, frames, composites, branches, leaves`, the architecture machine and the world check know it, and `starci app add frame <name>` writes one. The grammar package folders are `leaf`, `branch`, `composite` and `frame`.
+- Added: the codemod `small-renames` (`starci app codemod small-renames [--execute] [--json]`) for the grammar's small cuts: `ChatBubble` to `MessageBubble`, `StatusDot` with text and `ConnectionStatus` to `Badge isDot`, `CloseButton` to `IconButton intent="dismiss"`, `TextAction href` to `Link`, `SurfaceCopyGroup` to `Stack`, the removed `variant`, `size="control"`, `isError` and `OtpInput` props, and `FlowGraph layout="orbit"` to `BubbleMap`; what a person decides is reported, not rewritten.
+
 ## 4.16.5 - 2026-11-01
 
 - Added: R354 `FE_HEADING_ABOVE_CARD` (eslint-canon-fe `no-heading-above-card`).
@@ -313,7 +349,6 @@ Breaking for lite apps (rulings lite-official-postgres-image and lite-queue-bull
 - Fixed: `starci app db baseline` judges the archive (`db/migrations/archive/`) as frozen history (R257): an archived file needs only its leading 14-digit stamp and an underscore, so a retired chain's snake_case names, impossible times (`20261014300000`) and shared stamps no longer refuse the cutover. The active chain keeps R213 in full (`<ts14>_<kebab>.sql` with a valid UTC stamp); R213 and R332 set no upper bound, so an active stamp after now is no breach. A file both active and archived is refused by name. The new version sorts after every archived and active file, and the baseline header names the last valid stamp, the boundary R257 judges.
 - Fixed: a refusal over the migration chain lists every offender as `<file>: <reason> (<rule>)`, all at once: a misnamed or invalid-time active file (`db baseline`, `db restamp`, `db plan`), and for `db baseline` the `--stamp` boundary file, the committed-history findings (R257), the queue and cron findings (R258) and each active migration a schema-only dump cannot rebuild. Spec: `src/hfs-database-baseline.spec.mjs`.
 
-
 ## 4.10.1 - 2026-10-29
 
 - Changed: the bundled slot manifest 3.10.0 adds the lite slot `be.platform.database.entities`, the entity registry (slot fields `role: entity-registry` and `importedBy`, validated by the manifest shape); the bundled architecture machine reads it (`architecture/entity-registry.mjs`): `tier-direction` (R26 `BE_TIER_DIRECTION`) admits the registry's import of a domain or platform capability's `index.ts` that binds only that capability's `<c>Entities`, and `owner-export-bypass` (R30 `ARCH_OWNER_EXPORT_BYPASS`) admits a direct import of the registry from the files `importedBy` names (`apps/*/src/compose/*.ts`, `apps/*/src/app.module.ts`, `src/tests/world/**`); every other import of either shape stays refused, and full has no registry; the bundled canon pins name hfs 4.10.1, eslint-canon-be 3.7.1, eslint-canon-fe 9.5.1 and the Grammar family 0.15.12; the lite skeleton's `platform/database/entities.ts` names its importers (app composition and the test world).
@@ -331,7 +366,6 @@ Breaking for lite apps (ruling lite-self-hosted-postgres-passport-minio; the mig
 - Changed: the bundled lite pattern knowledge (event-bus, idempotency, jobs, projections, queues, reactors, realtime, saga, webhooks) names db migrations and the local db service instead of Supabase; the command policy points `supabase` at `starci app db` and the db scripts.
 - Changed: the bundled slot manifest 3.9.0 replaces the lite `app.supabase*` slots with `app.db` (`db/migrations`, `db/migrations/archive`, `db/seed.sql`, the managed `db/bootstrap.sql`), `be.integrations.supabase` with `be.integrations.passport` and `be.integrations.object-storage`, removes `fe.route.callback`, sets lite `schemaAuthority: sql`, gives lite TypeORM entities in `be.persistence`, adds `ruleParams.be.dbFunctions`, and moves the S3 SDKs to `integrations/object-storage` and the identity libraries to `integrations/passport` in `infraOwners` (`@supabase/*`, `minio` and `bcrypt` nowhere); the bundled rule catalog retires R216, R217, R219, R254 and R287 and adds R328-R334; the bundled canon pins name hfs 4.10.0, eslint-canon-be 3.7.0, eslint-canon-fe 9.5.0 and the Grammar family 0.15.11, pin `@nestjs/passport` 11.0.5 (CommonJS on the Nest 11 line), `passport` 0.7.0, `passport-google-oauth20` 2.0.0, `passport-local` 1.0.0, `bcryptjs` 3.0.3 and their types (tokens are signed and verified with `jose`; `@nestjs/jwt` stays allowed in `integrations/passport` but unpinned), and drop `@supabase/ssr`, `@supabase/supabase-js` and the `supabase` CLI.
 
-
 ## 4.9.11 - 2026-10-29
 
 - Added: `starci app db drift [--url-env <NAME>] [--json]` (`db/drift.mjs`, owner ruling 2026-10-29: lite tables are mapped by TypeORM entities while `db/migrations/*.sql` stays the only DDL and `synchronize` is false). It builds TypeORM's metadata from `be/src/platform/database/entities.ts` with the app's own typescript, typeorm and pg (a `DataSource` that never connects), applies `db/bootstrap.sql` and every active migration to a scratch container of the app's `components.db` image (or the empty database `--url-env` names), and reports every missing table or column, type mismatch and nullability mismatch as `BE_ENTITY_SCHEMA_DRIFT` (R333 in the bundled rule catalog, with its failure-code entry). No Docker, no app packages or an unreadable target is no verdict (`DB_DRIFT_NEEDS_DATABASE`, exit 2), never a green; a migration that does not apply to an empty database is `DB_DRIFT_MIGRATION_FAILED`. An app with an entity list gets a `db-drift` row in its release gate (default or declared gates) and `npx starci app db drift` after `npm run db:lint` in its managed CI's build job. Specs: `src/db-drift.spec.mjs` (real TypeORM metadata over a fixture app, stubbed schema) and `src/db-drift-docker.spec.mjs` (a real postgres:17-alpine scratch database where Docker runs, else the no-verdict answer); typeorm 0.3.31 and pg 8.23.1 are dev dependencies for them.
@@ -669,7 +703,6 @@ Breaking for lite apps (ruling lite-self-hosted-postgres-passport-minio; the mig
 - Changed: `HFS_DUPLICATE_CODE` drops canon scaffold shapes; `HFS_UNUSED_EXPORT` counts staged test consumers; `FE_I18N_KEYS` reads in-segment template keys (`t(`stage_${x}`)`) as globs.
 - Changed: the scaffolded pre-commit hook passes staged files to eslint and prettier in chunks of 50 (Windows command-line limit); `DB_MIGRATION_SHAPE` orders a new migration against HEAD's active migrations, not the clock or the base branch.
 
-
 - Added: HFS manifest 3.1.0 (rule catalog 3.1.0, owner ruling 2026-10-14, R245 and R246): every `be.app.*` slot allows the composition groups `compose/<area>.ts` and budgets its composition files (`app.module.ts` 250, `<app>.options.ts` 200, `compose/<area>.ts` 120, `main.ts` 80); `<app>.options.ts` holds env-derived options and port bindings only (`BE_APP_OPTIONS_COMPOSITION`, `BE_APP_COMPOSITION_BUDGET`).
 - Changed: `starci app scaffold` writes `apps/<api app>/src/compose/platform.ts` (the platform capabilities as one group, `platformModules(options)`) in both editions, and the scaffolded `app.module.ts` spreads it before the domain modules and the guards.
 - Changed: `add table` lists the table's error kinds where the app keeps its error kinds array: the root `app.module.ts`, or else the `compose/` group that holds it.

package/README.md

@@ -10,7 +10,7 @@ Every command runs at the app root. A side is judged with its folder as the root
 ```sh
 starci app scaffold <name> [--edition full|lite] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [--fe] [--no-types] [options] [--cwd <dir>]
-starci app add <block|composite|branch|leaf> <name> [--shapes a,b,c] [--read <read>] [--app <fe app>] [--cwd <dir>]
+starci app add <block|frame|composite|branch|leaf> <name> [--shapes a,b,c] [--read <read>] [--app <fe app>] [--cwd <dir>]
 starci app add <page|layout> <route> [--blocks a,b] [--tabs a,b] [--app <fe app>] [--cwd <dir>]
 starci app add overlay <name> --kind modal|drawer [--form] [--app <fe app>] [--cwd <dir>]
 starci app add service <dir> <name> [--inject <binding>...] [--cwd <dir>]
@@ -41,13 +41,13 @@ and `contexts/ui`, from `templates/fe/units`, with its copy in every catalog; no
 - `page <route>`: `app/[locale]/<route>/{page,loading,error}.tsx`, the server page owner `<Name>Page` drawing one Grammar
   `Page` (R325) whose header carries the trail and the heading and whose body composes `--blocks` (blocks that take no input;
   else the page's empty sentence) and, with `--tabs a,b`, the page tabs in its header as link tabs (the first tab the route, each
-  other one its sub-route `<route>/<tab>`, the selected tab the current path's), its loading view `<Name>LoadingPage` (the same page drawn with `isSkeleton`, STATE-8),
+  other one its sub-route `<route>/<tab>`, the selected tab the current path's), its loading view `<Name>LoadingPage` (the same page drawn with `isLoading`, STATE-8),
   `<Name>ErrorPage` (the page with one negative Alert), and the stories pairing the page with its loading view.
 - `overlay <name> --kind modal|drawer`: `features/overlays/<Name>Overlay`, a `Dialog` or a trailing `Drawer` whose connected
   half owns its open state; its decision group puts the way out first and the commit last, always in the footer; with `--form`
-  the body holds a Form with an `id` over a one-column `FormGrid` and the footer's commit submits it by `form="<id>"`; stories draw it closed and open.
+  the body holds a Form with an `id` over a one-column `Grid kind="form"` and the footer's commit submits it by `form="<id>"`; stories draw it closed and open.
 - `layout <segment>`: `app/[locale]/<segment>/layout.tsx` and `features/layouts/<Name>Layout`, which composes Grammar's
-  `PrimaryRailLayout`: the routed page in its primary region, `--blocks` in its rail. A frame never insets a page.
+  `Grid kind="main-rail"`: the routed page in its primary region, `--blocks` in its rail. A frame never insets a page.
 
 ## Lite edition
 

package/codemod/loading-states.d.mts

@@ -0,0 +1,50 @@
+/** 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 safe rewrite of the report. */
+export interface LoadingStatesChange {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    from: string;
+    to: string;
+}
+/** One case left for a person. */
+export interface LoadingStatesFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    reason: string;
+    component?: string;
+    source?: string;
+}
+/** The report of a migration (`starci app codemod loading-states`). */
+export interface LoadingStatesReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: LoadingStatesChange[];
+    findings: LoadingStatesFinding[];
+}
+/** Migrate the loading-state vocabulary with source edits; a case with no mechanical rewrite keeps its source and gains a finding. */
+export declare function transformLoadingStates({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: LoadingStatesChange[];
+    findings: LoadingStatesFinding[];
+};
+/** Preview or apply the safe rewrites in one app (its fe/ tree, else the root); every unresolved case is retained in the returned report. */
+export declare function migrateLoadingStates({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): LoadingStatesReport;
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function loadingStatesMarkdown(report: LoadingStatesReport): string;
+export {};

package/codemod/loading-states.mjs

@@ -0,0 +1,384 @@
+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';
+import { shadowed } from './small-renames.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GRAMMAR = /^@starci\/grammar(?:\/|$)/;
+const GENERATED = new Set(['node_modules', '.next', '.turbo', 'dist', 'build', 'coverage', '.git', 'storybook-static']);
+/** A file worth parsing at all: it names something this codemod looks at. */
+const RELEVANT = /isSkeleton|loadingRows|loadingContent|DataSlot|Skeleton|Placeholder|isValidating|Slot\b|\?\?\s*\[\s*\]|\brows\b/;
+/** Grammar components that lost `loadingRows`: the Grammar draws its own default rows. */
+const LOADING_ROWS = new Set(['Section', 'SurfaceCard', 'ListBox', 'Timeline', 'DataTable']);
+const HAND_SKELETONS = new Set(['Skeleton', 'ChatBubbleSkeletons', 'MessageBubbleSkeletons']);
+/** The status flags a DataSlot member is made of; `items` belongs to the ready member only. */
+const FLAG_KEYS = new Set(['isLoading', 'isError', 'isForbidden', 'isEmpty']);
+const SLOT_LITERAL_REASON = 'build the slot with slotOfQuery, slotOfReads, mapSlot, or one flag member';
+const LOADING_NAME = /^(?:isLoading|loading|isPending|status)$/;
+const STATUS_KEYS = new Set(['isLoading', 'isError', 'error']);
+const SLOT_NAME = /slot$/i;
+const TEST_FILE = /\.(?:spec|test)\.[cm]?[jt]sx?$/;
+const VALIDATING_REASON = 'a background refresh never drives a loading flag or a status: a skeleton is isLoading (no data yet) alone';
+/** Migrate the loading-state vocabulary with source edits; a case with no mechanical rewrite keeps its source and gains a finding. */
+export function transformLoadingStates({ ts, text, file = 'component.tsx' }) {
+    const changes = [];
+    const findings = [];
+    if (!RELEVANT.test(text))
+        return { text, changes, findings };
+    const syntax = ts.transpileModule(text, { fileName: file, reportDiagnostics: true, compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest } }).diagnostics ?? [];
+    if (syntax.length)
+        return { text, changes, findings: [{ file, line: 1, column: 1, code: 'PARSE_ERROR', reason: ts.flattenDiagnosticMessageText(syntax[0]?.messageText ?? '', '\n') }] };
+    const kind = /\.tsx$/i.test(file) ? ts.ScriptKind.TSX : /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : /\.[cm]?js$/i.test(file) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+    const normalized = file.replaceAll('\\', '/');
+    const reportsFindings = !TEST_FILE.test(normalized);
+    const inHooks = /(?:^|\/)hooks\//.test(normalized) && !/(?:^|\/)hooks\/swr\//.test(normalized);
+    const flag = (node, code, reason, component) => {
+        if (!reportsFindings)
+            return;
+        findings.push({ file, ...sourceLocation(source, node), code, reason, ...(component === undefined ? {} : { component }), source: node.getText(source).slice(0, 200) });
+    };
+    const change = (node, code, from, to) => { changes.push({ file, ...sourceLocation(source, node), code, from, to }); };
+    const edits = [];
+    const edit = (start, end, replacement) => { edits.push({ start, end, text: replacement }); };
+    // Grammar imports: bindings by local name and namespaces.
+    const bindings = new Map();
+    const namespaces = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !GRAMMAR.test(statement.moduleSpecifier.text))
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (named && ts.isNamespaceImport(named))
+            namespaces.add(named.name.text);
+        if (named && ts.isNamedImports(named))
+            for (const specifier of named.elements)
+                bindings.set(specifier.name.text, specifier.propertyName?.text ?? specifier.name.text);
+    }
+    /** The Grammar export a JSX tag names (through an import, an alias or a namespace), or null. */
+    const grammarExport = (tag) => {
+        if (ts.isIdentifier(tag))
+            return shadowed(ts, tag) ? null : bindings.get(tag.text) ?? null;
+        if (ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression) && namespaces.has(tag.expression.text) && !shadowed(ts, tag.expression))
+            return tag.name.text;
+        return null;
+    };
+    const tagLocalName = (tag) => ts.isIdentifier(tag) ? tag.text : ts.isPropertyAccessExpression(tag) ? tag.name.text : null;
+    const attributeOf = (opening, name) => opening.attributes.properties.find((attribute) => ts.isJsxAttribute(attribute) && attribute.name.getText(source) === name);
+    // Data slots: names declared with a `DataSlot<...>` annotation (variable, parameter or property signature) anywhere in the file.
+    const isSlotType = (type) => {
+        if (!type)
+            return false;
+        if (ts.isParenthesizedTypeNode(type))
+            return isSlotType(type.type);
+        if (ts.isUnionTypeNode(type))
+            return type.types.some(isSlotType);
+        if (!ts.isTypeReferenceNode(type))
+            return false;
+        const name = type.typeName;
+        return (ts.isIdentifier(name) ? name.text : name.right.text) === 'DataSlot';
+    };
+    const nameOf = (name) => ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : null;
+    const slotNames = new Set();
+    const collect = (node) => {
+        if ((ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isPropertySignature(node) || ts.isPropertyDeclaration(node)) && isSlotType(node.type)) {
+            const name = nameOf(node.name);
+            if (name)
+                slotNames.add(name);
+        }
+        ts.forEachChild(node, collect);
+    };
+    collect(source);
+    /** Functions of the file declared to return a DataSlot: an object literal passed to one is in a slot context. */
+    const slotFunctions = new Set();
+    for (const statement of source.statements) {
+        if (ts.isFunctionDeclaration(statement) && statement.name && isSlotType(statement.type))
+            slotFunctions.add(statement.name.text);
+        if (ts.isVariableStatement(statement))
+            for (const declaration of statement.declarationList.declarations) {
+                const init = declaration.initializer;
+                if (ts.isIdentifier(declaration.name) && init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) && isSlotType(init.type))
+                    slotFunctions.add(declaration.name.text);
+            }
+    }
+    const unwrap = (node) => {
+        let current = node;
+        while (ts.isParenthesizedExpression(current) || ts.isNonNullExpression(current))
+            current = current.expression;
+        return current;
+    };
+    /** An identifier or property access named like a declared DataSlot. */
+    const isSlotRef = (node) => {
+        const value = unwrap(node);
+        if (ts.isIdentifier(value))
+            return slotNames.has(value.text);
+        return ts.isPropertyAccessExpression(value) && slotNames.has(value.name.text);
+    };
+    const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    /** Whether `node` sits in a branch that narrows `receiver` by a flag or by `"items" in receiver`. */
+    const narrowed = (node, receiver) => {
+        const name = escapeRegExp(receiver);
+        const narrows = new RegExp(`"items"\\s+in\\s+${name}\\b|\\b${name}\\.is(?:Loading|Error|Forbidden|Empty)\\b`);
+        const mentions = (expression) => narrows.test(expression.getText(source).replaceAll('?.', '.'));
+        for (let child = node, at = node.parent; at; child = at, at = at.parent) {
+            if (ts.isIfStatement(at) && at.thenStatement === child && mentions(at.expression))
+                return true;
+            if (ts.isConditionalExpression(at) && at.whenTrue === child && mentions(at.condition))
+                return true;
+            if (ts.isBinaryExpression(at) && at.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken && at.right === child && mentions(at.left))
+                return true;
+            if (ts.isCaseClause(at) && ts.isCaseBlock(at.parent) && ts.isSwitchStatement(at.parent.parent) && mentions(at.parent.parent.expression))
+                return true;
+            if (ts.isFunctionLike(at) || ts.isSourceFile(at))
+                return false;
+        }
+        return false;
+    };
+    const hasKey = (literal, matches) => literal.properties.some(property => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) && matches(nameOf(property.name) ?? ''));
+    const slotLiterals = new Set();
+    const legacyLiterals = new Set();
+    const itemsOf = (literal) => literal.properties.find((property) => ts.isPropertyAssignment(property) && nameOf(property.name) === 'items');
+    const isUndefined = (expression) => { const value = unwrap(expression); return ts.isIdentifier(value) && value.text === 'undefined'; };
+    /** The object literals a typed slot position yields: the expression itself, through parentheses and conditional branches. */
+    const literalsOf = (expression) => {
+        if (!expression)
+            return [];
+        const value = unwrap(expression);
+        if (ts.isObjectLiteralExpression(value))
+            return [value];
+        if (ts.isConditionalExpression(value))
+            return [...literalsOf(value.whenTrue), ...literalsOf(value.whenFalse)];
+        return [];
+    };
+    /** Whether the file reads the status of the read `name`: `name.isLoading`, `name.error`, or `isLoading` destructured (for a bare `data`). */
+    const readsStatus = (name) => {
+        const escaped = escapeRegExp(name);
+        return new RegExp(`\\b${escaped}\\??\\.(?:isLoading|error|isError)\\b`).test(text) || new RegExp(`\\{[^}]*\\b(?:isLoading|error)\\b[^}]*\\}\\s*=\\s*${escaped}\\b`).test(text) || (name === 'data' && /\bisLoading\b/.test(text));
+    };
+    const rootOf = (input) => {
+        let current = unwrap(input);
+        for (;;) {
+            if (ts.isIdentifier(current))
+                return current.text;
+            if (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current) || ts.isCallExpression(current))
+                current = unwrap(current.expression);
+            else
+                return null;
+        }
+    };
+    const placeholder = (node, initializer) => {
+        if (!initializer)
+            return;
+        let value = initializer;
+        while (ts.isParenthesizedExpression(value) || ts.isAsExpression(value) || ts.isSatisfiesExpression(value))
+            value = value.expression;
+        if (!ts.isObjectLiteralExpression(value))
+            return;
+        const emptied = value.properties.some(property => ts.isPropertyAssignment(property) && ts.isArrayLiteralExpression(property.initializer) && property.initializer.elements.length === 0);
+        if (emptied)
+            flag(node, 'PLACEHOLDER_OBJECT', 'a placeholder is the ready tree with its data stripped to []: let the component rest as itself with a loading flag');
+    };
+    /** Whether `node` is inside a JSX attribute of an element that resolves to a Grammar export (a breadcrumb item, for one). */
+    const insideGrammarAttribute = (node) => {
+        for (let at = node.parent; at; at = at.parent) {
+            if (ts.isJsxAttribute(at)) {
+                const opening = at.parent.parent;
+                return (ts.isJsxOpeningElement(opening) || ts.isJsxSelfClosingElement(opening)) && grammarExport(opening.tagName) !== null;
+            }
+            if (ts.isSourceFile(at))
+                return false;
+        }
+        return false;
+    };
+    const visit = (node) => {
+        if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+            const exported = grammarExport(node.tagName);
+            const local = tagLocalName(node.tagName);
+            if (exported !== null) {
+                const skeleton = attributeOf(node, 'isSkeleton');
+                if (skeleton && attributeOf(node, 'isLoading'))
+                    flag(skeleton, 'LOADING_NAME_CONFLICT', 'the element has isSkeleton and isLoading both: merge them into isLoading by hand', exported);
+                else if (skeleton) {
+                    edit(skeleton.name.getStart(source), skeleton.name.end, 'isLoading');
+                    change(skeleton, 'RENAME_IS_SKELETON', 'isSkeleton', 'isLoading');
+                }
+                const loadingRows = attributeOf(node, 'loadingRows');
+                if (loadingRows && LOADING_ROWS.has(exported)) {
+                    edit(loadingRows.getFullStart(), loadingRows.end, '');
+                    change(loadingRows, 'REMOVE_LOADING_ROWS', loadingRows.getText(source), '');
+                }
+                const rows = attributeOf(node, 'rows');
+                if (rows && exported === 'MessageBubble' && (skeleton || attributeOf(node, 'isLoading'))) {
+                    edit(rows.getFullStart(), rows.end, '');
+                    change(rows, 'REMOVE_BUBBLE_ROWS', rows.getText(source), '');
+                }
+                const content = attributeOf(node, 'loadingContent');
+                if (content && exported === 'DataTable')
+                    flag(content, 'LOADING_CONTENT', 'loadingContent is removed: the table draws its own loading rows', exported);
+            }
+            if (local !== null && HAND_SKELETONS.has(local))
+                flag(node, 'HAND_SKELETON', 'the Grammar component draws its loading structure from isLoading; pass the status, not a skeleton', local);
+        }
+        if (ts.isPropertyAccessExpression(node) && node.name.text === 'items' && isSlotRef(node.expression) && !narrowed(node, unwrap(node.expression).getText(source).replaceAll('?.', '.'))) {
+            flag(node, 'SLOT_ITEMS_ACCESS', 'items exists only on the ready member: narrow with `"items" in slot` or render through SlotView');
+        }
+        if ((ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node)) && isSlotType(node.type))
+            for (const literal of literalsOf(node.initializer))
+                slotLiterals.add(literal);
+        if (ts.isArrowFunction(node) && isSlotType(node.type) && !ts.isBlock(node.body))
+            for (const literal of literalsOf(node.body))
+                slotLiterals.add(literal);
+        if (ts.isReturnStatement(node)) {
+            for (let at = node.parent; at; at = at.parent) {
+                if (!ts.isFunctionLike(at))
+                    continue;
+                if (isSlotType(at.type))
+                    for (const literal of literalsOf(node.expression))
+                        slotLiterals.add(literal);
+                break;
+            }
+        }
+        if (ts.isObjectLiteralExpression(node) && hasKey(node, key => key === 'items') && hasKey(node, key => FLAG_KEYS.has(key)))
+            legacyLiterals.add(node);
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && slotFunctions.has(node.expression.text))
+            for (const argument of node.arguments)
+                for (const literal of literalsOf(argument))
+                    slotLiterals.add(literal);
+        if (ts.isParameter(node) && isSlotType(node.type))
+            for (const literal of literalsOf(node.initializer))
+                slotLiterals.add(literal);
+        if (inHooks && ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken && ts.isArrayLiteralExpression(node.right) && node.right.elements.length === 0) {
+            const left = unwrap(node.left);
+            const isData = (ts.isPropertyAccessExpression(left) && left.name.text === 'data') || (ts.isIdentifier(left) && left.text === 'data');
+            const isMap = ts.isCallExpression(left) && ts.isPropertyAccessExpression(left.expression) && left.expression.name.text === 'map';
+            const root = isData || isMap ? rootOf(left) : null;
+            if (root !== null && !readsStatus(root))
+                flag(node, 'SWR_DEFAULT_ARRAY', "return the read's status with the list, or fold every read of the frame with slotOfReads");
+        }
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            if (LOADING_NAME.test(node.name.text) && node.initializer && /\bisValidating\b/.test(node.initializer.getText(source)))
+                flag(node, 'VALIDATING_AS_LOADING', VALIDATING_REASON);
+            if (/Placeholder$/.test(node.name.text))
+                placeholder(node, node.initializer);
+        }
+        if ((ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) && nameOf(node.name) === 'isSkeleton' && insideGrammarAttribute(node)) {
+            if (ts.isPropertyAssignment(node) && !hasKey(node.parent, key => key === 'isLoading')) {
+                edit(node.name.getStart(source), node.name.end, 'isLoading');
+                change(node, 'RENAME_IS_SKELETON', 'isSkeleton', 'isLoading');
+            }
+            else
+                flag(node, 'IS_SKELETON_KEY', 'isSkeleton is now isLoading: rename the key by hand (a shorthand or a second isLoading key blocks the rewrite)');
+        }
+        if (ts.isPropertyAssignment(node)) {
+            const key = nameOf(node.name);
+            if (key !== null && LOADING_NAME.test(key) && /\bisValidating\b/.test(node.initializer.getText(source)))
+                flag(node, 'VALIDATING_AS_LOADING', VALIDATING_REASON);
+            if (key !== null && /Placeholder$/.test(key))
+                placeholder(node, node.initializer);
+            const value = unwrap(node.initializer);
+            if (key !== null && STATUS_KEYS.has(key) && ts.isPropertyAccessExpression(value) && value.name.text === key) {
+                const owner = unwrap(value.expression);
+                const ownerName = ts.isIdentifier(owner) ? owner.text : ts.isPropertyAccessExpression(owner) ? owner.name.text : null;
+                if (ownerName !== null && SLOT_NAME.test(ownerName))
+                    flag(node, 'FOREIGN_SLOT_STATUS', "a slot takes its loading and error from its own reads, never from another slot's: build it with slotOfReads");
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    for (const literal of slotLiterals) {
+        legacyLiterals.delete(literal);
+        const items = itemsOf(literal);
+        if (literal.properties.some(property => ts.isSpreadAssignment(property)) || (items && ts.isConditionalExpression(unwrap(items.initializer)))) {
+            flag(literal, 'SLOT_LITERAL', SLOT_LITERAL_REASON);
+            continue;
+        }
+        if (!items)
+            continue;
+        const others = literal.properties.filter(property => property !== items);
+        const flagged = others.filter(property => FLAG_KEYS.has(ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property) ? nameOf(property.name) ?? '' : ''));
+        if (!isUndefined(items.initializer)) {
+            if (flagged.length)
+                flag(literal, 'SLOT_LITERAL', SLOT_LITERAL_REASON);
+            continue;
+        }
+        if (!others.length) {
+            edit(literal.getStart(source), literal.end, '{ isEmpty: true }');
+            change(literal, 'SLOT_LITERAL_FLAGS', literal.getText(source), '{ isEmpty: true }');
+            continue;
+        }
+        const [only] = others;
+        if (others.length === 1 && only && ts.isPropertyAssignment(only) && ['isLoading', 'isError', 'isForbidden'].includes(nameOf(only.name) ?? '') && only.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+            edit(literal.getStart(source), literal.end, `{ ${only.getText(source)} }`);
+            change(literal, 'SLOT_LITERAL_FLAGS', literal.getText(source), `{ ${only.getText(source)} }`);
+        }
+        else
+            flag(literal, 'SLOT_LITERAL', SLOT_LITERAL_REASON);
+    }
+    for (const literal of legacyLiterals)
+        flag(literal, 'SLOT_LITERAL', SLOT_LITERAL_REASON);
+    edits.sort((first, second) => first.start - second.start || first.end - second.end);
+    const unique = [];
+    for (const current of edits) {
+        const previous = unique.at(-1);
+        if (previous && previous.start === current.start && previous.end === current.end && previous.text === current.text)
+            continue;
+        if (previous && current.start < previous.end) {
+            return { text, changes: [], findings: [...findings, { file, line: 1, column: 1, code: 'EDIT_CONFLICT', reason: 'two rewrites overlap: nothing in this file was changed; migrate by hand' }] };
+        }
+        unique.push(current);
+    }
+    let output = text;
+    for (const current of unique.reverse())
+        output = output.slice(0, current.start) + current.text + output.slice(current.end);
+    findings.sort((first, second) => first.line - second.line || first.column - second.column);
+    return { text: output, changes, findings };
+}
+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() && /\.tsx?$/i.test(entry.name) && !/\.d\.[cm]?ts$/i.test(entry.name) ? [target] : [];
+    }).sort();
+}
+/** Preview or apply the safe rewrites in one app (its fe/ tree, else the root); every unresolved case is retained in the returned report. */
+export function migrateLoadingStates({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+    if (!ts)
+        throw new Error('loading-states needs TypeScript installed in the app or @starci/hfs development checkout');
+    const frontend = path.join(root, 'fe');
+    const base = fs.statSync(frontend, { throwIfNoEntry: false })?.isDirectory() ? frontend : root;
+    const report = { schema: 'starci/loading-states-report@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [] };
+    for (const target of sourceFiles(base)) {
+        const file = path.relative(root, target).split(path.sep).join('/');
+        const original = fs.readFileSync(target, 'utf8');
+        const result = transformLoadingStates({ ts, text: original, file });
+        report.filesScanned += 1;
+        report.changes.push(...result.changes);
+        report.findings.push(...result.findings);
+        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 what is left for a person as Markdown; JSON consumers read the same report object. */
+export function loadingStatesMarkdown(report) {
+    const out = ['# loading-states', '', `Scanned ${report.filesScanned} files, ${report.filesChanged.length} ${report.write ? 'changed' : 'would change'}, ${report.changes.length} rewrites, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| location | code | reason |', '|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Rewrites', '', '| location | code | from | to |', '|---|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${cell(`${item.file}:${item.line}:${item.column}`)} | ${item.code} | \`${cell(item.from)}\` | \`${cell(item.to)}\` |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/main.d.mts

@@ -1,6 +1,6 @@
 /** 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. */
+/** The arguments of `starci app codemod spacing-roles`, `theme-tokens`, `small-renames`, `page-navigation`, `section-frame`, `surface-card-kinds`, `tier-binding` and `loading-states`: --execute, --json, --format and --out; any other is refused. */
 export declare function spacingRolesArguments(argv: readonly string[]): {
     write: boolean;
     format: 'json' | 'markdown';

package/codemod/main.mjs

@@ -1,10 +1,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { codemodMain as buttonIntentMain } from './button-intent.mjs';
+import { migratePageNavigation, pageNavigationMarkdown } from './page-navigation.mjs';
+import { loadingStatesMarkdown, migrateLoadingStates } from './loading-states.mjs';
+import { migrateSectionFrame, sectionFrameMarkdown } from './section-frame.mjs';
+import { migrateSmallRenames, smallRenamesMarkdown } from './small-renames.mjs';
 import { migrateSpacingRoles, spacingRolesMarkdown } from './spacing-roles.mjs';
+import { migrateSurfaceCardKinds, surfaceCardKindsMarkdown } from './surface-card-kinds.mjs';
+import { migrateThemeTokens, themeTokensMarkdown } from './theme-tokens.mjs';
+import { migrateTierBinding, tierBindingMarkdown } from './tier-binding.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 const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states']);
+/** The arguments of `starci app codemod spacing-roles`, `theme-tokens`, `small-renames`, `page-navigation`, `section-frame`, `surface-card-kinds`, `tier-binding` and `loading-states`: --execute, --json, --format and --out; any other is refused. */
 export function spacingRolesArguments(argv) {
     const options = { write: false, format: 'markdown' };
     const args = argv.values();
@@ -35,6 +42,39 @@ export function spacingRolesArguments(argv) {
     }
     return options;
 }
+/** One of the report-style codemods run at an app root: its report object and the Markdown of it. */
+function runCodemod(name, root, write) {
+    if (name === 'theme-tokens') {
+        const report = migrateThemeTokens({ root, write });
+        return { report, markdown: themeTokensMarkdown(report) };
+    }
+    if (name === 'surface-card-kinds') {
+        const report = migrateSurfaceCardKinds({ root, write });
+        return { report, markdown: surfaceCardKindsMarkdown(report) };
+    }
+    if (name === 'tier-binding') {
+        const report = migrateTierBinding({ root, write });
+        return { report, markdown: tierBindingMarkdown(report) };
+    }
+    if (name === 'page-navigation') {
+        const report = migratePageNavigation({ root, write });
+        return { report, markdown: pageNavigationMarkdown(report) };
+    }
+    if (name === 'section-frame') {
+        const report = migrateSectionFrame({ root, write });
+        return { report, markdown: sectionFrameMarkdown(report) };
+    }
+    if (name === 'loading-states') {
+        const report = migrateLoadingStates({ root, write });
+        return { report, markdown: loadingStatesMarkdown(report) };
+    }
+    if (name === 'small-renames') {
+        const report = migrateSmallRenames({ root, write });
+        return { report, markdown: smallRenamesMarkdown(report) };
+    }
+    const report = migrateSpacingRoles({ root, write });
+    return { report, markdown: spacingRolesMarkdown(report) };
+}
 /**
  * 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.
@@ -43,13 +83,14 @@ export function codemodMain(argv, io) {
     const [name, ...rest] = argv;
     if (name === 'button-intent')
         return buttonIntentMain(argv, io);
-    if (name !== 'spacing-roles')
+    if (name !== 'spacing-roles' && name !== 'theme-tokens' && name !== 'small-renames' && name !== 'page-navigation' && name !== 'section-frame' && name !== 'surface-card-kinds' && name !== 'tier-binding' && name !== 'loading-states')
         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);
+    const root = path.resolve(io.cwd);
+    const { report, markdown } = runCodemod(name, root, options.write);
+    const output = options.format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : markdown;
     if (options.out) {
         const target = path.resolve(io.cwd, options.out);
         fs.mkdirSync(path.dirname(target), { recursive: true });