@starci/hfs 4.16.4 → 4.17.0

package/runtime/knowledge/patterns/fe/folder.yaml

@@ -364,7 +364,7 @@ rules:
     cases:
       - id: case-1
         when: "A Grammar component (runtime package)"
-        write: "packages/grammar/src/core/<primitive|composite|branch|composition>/<Name>/index.tsx"
+        write: "packages/grammar/src/core/<leaf|branch|composite|frame>/<Name>/index.tsx"
       - id: case-2
         when: "A Grammar component's class strings and spec (runtime package)"
         write: "sibling classNames.ts and index.spec.tsx"

package/runtime/modules/kernel/failure-codes.yaml

@@ -2113,16 +2113,6 @@ FE_BUTTON_INTENT_REQUIRED:
   owner: op-retry
   kind: check-finding
 
-FE_BUTTON_NO_VARIANT:
-  title: "An app button chooses a visual variant"
-  title_vi: "Nút ứng dụng tự chọn variant"
-  meaning_vi: "Button hoặc IconButton tại <file> truyền variant thay vì để Grammar suy ra từ intent và vị trí."
-  causes_vi:
-    - "Ứng dụng truyền variant trực tiếp hoặc qua props spread."
-  nextStep_vi: "Thay variant bằng intent theo hệ quả của lệnh (CTA-6)."
-  owner: op-retry
-  kind: check-finding
-
 
 FE_CLIENT_BOUNDARY:
   title: "Server first; `\"use client\"` only where allowed"
@@ -2377,6 +2367,26 @@ FE_HOOKS_ARE_HOOKS:
   owner: op-retry
   kind: check-finding
 
+FE_SURFACE_NESTING:
+  title: "A surface stands inside a surface, or a table, grid or heading stands where the card laws refuse it"
+  title_vi: "Bề mặt nằm trong bề mặt, hoặc bảng, lưới, tiêu đề nằm sai chỗ"
+  meaning_vi: "Qua các tệp, `<file>` vẽ một card trong card, trong `Pane surface` hoặc trong lớp phủ; một `DataTable` trong card; một `PaneGrid` ngoài `Page chrome=\"panes\"`; một tiêu đề đứng ngay trên một card; hoặc một card có nhãn lặp trong `Grid`. Từng tệp đứng riêng thì hợp lệ, ghép lại thì sai."
+  causes_vi:
+    - "Vi phạm luật R356: bề mặt trong bề mặt bị cấm hoàn toàn (kể cả hộp thoại và ngăn kéo); card tự mang nhãn nên không cần tiêu đề phía trên; bảng đứng trên trang; lưới chia pane chỉ đứng trong `Page chrome=\"panes\"`; ô lặp lại không có nhãn."
+  nextStep_vi: "Bỏ card bên trong (đưa nội dung lên card ngoài), chuyển bảng ra trang, đưa tiêu đề vào nhãn của card, hoặc chuyển ô lặp thành tile không nhãn. Bộ kiểm tra nêu chuỗi thành phần dẫn tới chỗ sai."
+  owner: op-retry
+  kind: check-finding
+
+FE_RENDER_PROP_ACROSS_SERVER:
+  title: "A server file hands a function to a client component"
+  title_vi: "Tệp server truyền hàm vào component client"
+  meaning_vi: "`<file>` không có 'use client' truyền một hàm (prop dạng arrow hoặc function) vào một component nằm trong tệp có 'use client'. Hàm không đi qua ranh giới server-client."
+  causes_vi:
+    - "Vi phạm luật R361: một block nhận dữ liệu và tự vẽ; callback thuộc nhánh client sở hữu tương tác."
+  nextStep_vi: "Truyền dữ liệu thay vì hàm, hoặc chuyển callback vào nhánh client sở hữu tương tác."
+  owner: op-retry
+  kind: check-finding
+
 FE_HREF_RESOLVES:
   title: "Link points to a route that does not exist"
   title_vi: "Liên kết trỏ tới đường dẫn không tồn tại"
@@ -2643,10 +2653,10 @@ FE_PACKAGE_SHAPE:
 FE_PAGE_HEADER_HAND_ROLLED:
   title: "A page head is composed by hand instead of PageHeader"
   title_vi: "Phần đầu trang được ghép tay thay vì dùng PageHeader"
-  meaning_vi: "Tại <file>, một Breadcrumbs theo sau là một SectionHeader trong cùng một phần tử cha: phần đầu trang ghép tay không có dải nền, không có khoảng đệm trên và không có đường phân cách, nên mỗi trang tự quyết khoảng cách riêng."
+  meaning_vi: "Tại <file>, một PageHeader hoặc Breadcrumbs được nhập trực tiếp từ Grammar, vốn là bộ phận riêng của Page và không còn được export: phần đầu trang ghép tay không có dải nền, không có khoảng đệm trên và không có đường phân cách, nên mỗi trang tự quyết khoảng cách riêng."
   causes_vi:
-    - "Đặt Breadcrumbs rồi SectionHeader level={1} ở đầu trang hoặc layout."
-  nextStep_vi: "Dùng PageHeader của Grammar với breadcrumbs, title và các khe cần thiết (description, meta, status, mark, actions, tabs) (quy định page-header-band)."
+    - "Nhập PageHeader hoặc Breadcrumbs từ Grammar để ghép đầu trang ở trang hoặc layout."
+  nextStep_vi: "Dùng khe header của Page với breadcrumbs, title và các khe cần thiết (description, meta, status, mark, actions, tabs) (quy định page-header-band)."
   owner: op-retry
   kind: check-finding
 

package/runtime/scripts/hfs/architecture/clones.mjs

@@ -255,9 +255,19 @@ const cloneCoverage = (entries, blocks, N, T) => {
     return { status: 'checked', minLines: N, minTokens: T, files: entries.length, cloneBlocks: blocks.length, ownersInvolved: owners.size, duplicatedLines,
         ...(blocks.length > MAX_VIOLATIONS ? { truncated: true } : {}) };
 };
+/**
+ * The threshold of the run. The app root (profile app) answers `ruleParams()` with null: its rule parameters are its sides', and
+ * duplicateBlock is the one value they share (ruleParams.common), so the root reads it from a side. A run on the app root
+ * (the root has its own tsconfig) threw "Cannot destructure property 'lines'" here before.
+ */
+function duplicateBlockOf(resolver) {
+    const own = resolver.ruleParams()?.duplicateBlock;
+    const block = own ?? Object.values(resolver.sides ?? {}).map(side => side.ruleParams().duplicateBlock).find(found => found !== undefined);
+    // reason: the rule-params validators require duplicateBlock on every profile, so a side that runs this check carries it
+    return block;
+}
 export function checkClones({ context, graph }) {
-    // reason: the rule-params validators require duplicateBlock on every profile that runs this check
-    const { lines: N, tokens: T } = graph.resolver.ruleParams()?.duplicateBlock;
+    const { lines: N, tokens: T } = duplicateBlockOf(graph.resolver);
     const ts = context.ts ?? context.loaded.ts;
     const entries = [];
     for (const rel of [...graph.files.keys()].sort(byCodeUnit)) {

package/runtime/scripts/hfs/architecture/component-tiers.d.mts

@@ -0,0 +1,46 @@
+import type { ArchitectureViolation, CheckInput } from './hfs-graph.mjs';
+/**
+ * The component tier ladder, checked on the source of a component library and of a component tree.
+ *
+ *   FE_GRAMMAR_TIER_DIRECTION  a grammar component imports a tier above it (the ladder leaf, branch, composite, frame: a tier imports
+ *                           nothing above itself), type-only imports included, through a shared untiered module as well;
+ *                           `tiers.grammar` of knowledge/hfs/slots.yaml is the matrix
+ *   FE_GRAMMAR_TIER_STAMP      a `data-tier` stamp names a tier other than the folder the file sits in (`atom`, `primitive` and
+ *                           `composition` are not tiers)
+ *   FE_TIER_DIRECTION       (layers) a component imports a layer at or above its own: blocks, frames, composites, branches, leaves
+ *
+ * A library is a folder holding `src/core/<tier>/<Name>/`; a tree is a folder holding `components/<layer>/<Unit>/` that no hfs
+ * front-end slot already judges (an app without hfs.json, such as the harness desktop app).
+ */
+export declare const COMPONENT_TIER_RULE_IDS: string[];
+/** One tier of the matrix: the tiers it may import. */
+export interface TierMatrixEntry {
+    mayImport: readonly string[];
+}
+/** The result of a check: findings and the coverage line. */
+export interface ComponentTierResult {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        [field: string]: unknown;
+    };
+}
+/**
+ * Check the component libraries under `root` against `matrix` (`tiers.grammar`). Not applicable when no folder holds
+ * `src/core/<tier>/<Name>/`. A file outside the tier folders (a shared helper under `src/core`) is not a tier, but an import that
+ * reaches a higher tier through it is the importing tier's edge.
+ */
+export declare function checkGrammarLibraries({ root, matrix }: {
+    root: string;
+    matrix: Readonly<Record<string, TierMatrixEntry>>;
+}): ComponentTierResult;
+/**
+ * Check a component tree under `root` that no hfs slot judges: a component imports only the layers after its own (`layers` in order,
+ * the first layer imports all below it). The layers are the folder names of slot fe.components.
+ */
+export declare function checkComponentLayers({ root, layers }: {
+    root: string;
+    layers: readonly string[];
+}): ComponentTierResult;
+/** The machine check: the grammar libraries of the repository, judged by `tiers.grammar` of the slot manifest. */
+export declare function checkGrammarTiers({ config }: CheckInput): ComponentTierResult;

package/runtime/scripts/hfs/architecture/component-tiers.mjs

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { byCodeUnit } from '../../lib/list.mjs';
+/**
+ * The component tier ladder, checked on the source of a component library and of a component tree.
+ *
+ *   FE_GRAMMAR_TIER_DIRECTION  a grammar component imports a tier above it (the ladder leaf, branch, composite, frame: a tier imports
+ *                           nothing above itself), type-only imports included, through a shared untiered module as well;
+ *                           `tiers.grammar` of knowledge/hfs/slots.yaml is the matrix
+ *   FE_GRAMMAR_TIER_STAMP      a `data-tier` stamp names a tier other than the folder the file sits in (`atom`, `primitive` and
+ *                           `composition` are not tiers)
+ *   FE_TIER_DIRECTION       (layers) a component imports a layer at or above its own: blocks, frames, composites, branches, leaves
+ *
+ * A library is a folder holding `src/core/<tier>/<Name>/`; a tree is a folder holding `components/<layer>/<Unit>/` that no hfs
+ * front-end slot already judges (an app without hfs.json, such as the harness desktop app).
+ */
+export const COMPONENT_TIER_RULE_IDS = ['FE_GRAMMAR_TIER_DIRECTION', 'FE_GRAMMAR_TIER_STAMP'];
+const SKIPPED = new Set(['node_modules', '.git', 'dist', '.next', 'storybook-static', 'proof']);
+const SOURCE = /\.(?:ts|tsx)$/u;
+const TEST_OR_STORY = /\.(?:stories|spec|test)\.[jt]sx?$/u;
+const IMPORT = /(?:\bimport|\bexport)\b[^'"`;]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/gu;
+const STAMP = /["']?data-tier["']?\s*[=:]\s*\{?\s*["']([a-z-]+)["']/gu;
+const LIBRARY_FILE = /^(.*?)src\/core\/(leaf|branch|composite|frame)\/([^/]+)\//u;
+function walk(root, dir = '') {
+    const out = [];
+    for (const entry of fs.readdirSync(path.join(root, dir), { withFileTypes: true })) {
+        if (SKIPPED.has(entry.name))
+            continue;
+        const rel = dir === '' ? entry.name : `${dir}/${entry.name}`;
+        if (entry.isDirectory())
+            out.push(...walk(root, rel));
+        else if (SOURCE.test(entry.name) && !entry.name.endsWith('.d.ts') && !TEST_OR_STORY.test(entry.name))
+            out.push(rel);
+    }
+    return out;
+}
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+/** The file an import specifier names, as a repo-relative path in `files`, or null (a package, or a file outside the walk). */
+function resolveImport(files, from, specifier) {
+    if (!specifier.startsWith('.'))
+        return null;
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier)).replace(/\.(?:js|mjs|cjs)$/u, '');
+    for (const candidate of [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`, base])
+        if (files.has(candidate))
+            return candidate;
+    return null;
+}
+function edgesOf(root, files, cache, file) {
+    const cached = cache.get(file);
+    if (cached)
+        return cached;
+    const text = fs.readFileSync(path.join(root, ...file.split('/')), 'utf8');
+    const edges = [];
+    for (const match of text.matchAll(IMPORT)) {
+        const specifier = match[1] ?? match[2] ?? match[3] ?? '';
+        const to = resolveImport(files, file, specifier);
+        if (to !== null)
+            edges.push({ to, line: lineOf(text, match.index ?? 0), specifier });
+    }
+    const entry = { text, edges };
+    cache.set(file, entry);
+    return entry;
+}
+/** The tier (the folder under `src/core`) and the component of a grammar source file, or null for a file outside the ladder. */
+const gradeOf = (file) => {
+    const match = LIBRARY_FILE.exec(file);
+    return match === null ? null : { tier: match[2], unit: `${match[1]}${match[2]}/${match[3]}` };
+};
+/**
+ * Check the component libraries under `root` against `matrix` (`tiers.grammar`). Not applicable when no folder holds
+ * `src/core/<tier>/<Name>/`. A file outside the tier folders (a shared helper under `src/core`) is not a tier, but an import that
+ * reaches a higher tier through it is the importing tier's edge.
+ */
+export function checkGrammarLibraries({ root, matrix }) {
+    const all = walk(root).filter(file => /(?:^|\/)src\//u.test(file));
+    const library = all.filter(file => gradeOf(file) !== null);
+    if (!library.length)
+        return { violations: [], coverage: { status: 'not-applicable' } };
+    const files = new Set(all);
+    const cache = new Map();
+    const violations = [];
+    const tiers = new Set(Object.keys(matrix));
+    let edgesChecked = 0;
+    let stamps = 0;
+    for (const file of library.sort(byCodeUnit)) {
+        const from = gradeOf(file);
+        const { text, edges } = edgesOf(root, files, cache, file);
+        for (const stamp of text.matchAll(STAMP)) {
+            stamps += 1;
+            if (stamp[1] !== from.tier) {
+                violations.push({ ruleId: 'FE_GRAMMAR_TIER_STAMP', path: file, line: lineOf(text, stamp.index ?? 0), column: 1,
+                    message: `${file} stamps data-tier="${stamp[1]}" and sits in the ${from.tier} folder: the stamp is the folder (${[...tiers].join(', ')}).` });
+            }
+        }
+        // Follow shared untiered modules, so a leaf cannot reach a frame by one hop of indirection.
+        const queue = edges.map(edge => ({ edge, via: [] }));
+        const seen = new Set();
+        for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+            const { edge, via } = next;
+            const target = gradeOf(edge.to);
+            if (target === null) {
+                if (seen.has(edge.to) || !edge.to.includes('/src/') && !edge.to.startsWith('src/'))
+                    continue;
+                seen.add(edge.to);
+                for (const onward of edgesOf(root, files, cache, edge.to).edges)
+                    queue.push({ edge: { ...onward, line: edge.line }, via: [...via, edge.to] });
+                continue;
+            }
+            if (target.unit === from.unit)
+                continue;
+            edgesChecked += 1;
+            if ((matrix[from.tier]?.mayImport ?? []).includes(target.tier))
+                continue;
+            violations.push({ ruleId: 'FE_GRAMMAR_TIER_DIRECTION', path: file, line: edge.line, column: 1, specifier: edge.specifier, resolvedPath: edge.to,
+                message: `${file} (${from.tier}) imports ${edge.to} (${target.tier})${via.length ? ` through ${via.join(' -> ')}` : ''}: a ${from.tier} may import only ${(matrix[from.tier]?.mayImport ?? []).join(', ') || 'nothing'}. Type-only imports count.` });
+        }
+    }
+    const unique = new Map(violations.map(violation => [`${violation.ruleId}|${violation.path}|${violation.line}|${violation.resolvedPath ?? ''}`, violation]));
+    return { violations: [...unique.values()], coverage: { status: 'checked', files: library.length, edgesChecked, stamps } };
+}
+const LAYER_FILE = /^(.*?)components\/([^/]+)\/([^/]+)\//u;
+/**
+ * Check a component tree under `root` that no hfs slot judges: a component imports only the layers after its own (`layers` in order,
+ * the first layer imports all below it). The layers are the folder names of slot fe.components.
+ */
+export function checkComponentLayers({ root, layers }) {
+    const all = walk(root).filter(file => /(?:^|\/)src\//u.test(file));
+    const placed = (file) => {
+        const match = LAYER_FILE.exec(file);
+        const layer = match === null ? -1 : layers.indexOf(match[2]);
+        return match === null || layer < 0 ? null : { layer, unit: `${match[1]}components/${match[2]}/${match[3]}` };
+    };
+    const tree = all.filter(file => placed(file) !== null);
+    if (!tree.length)
+        return { violations: [], coverage: { status: 'not-applicable' } };
+    const files = new Set(all);
+    const cache = new Map();
+    const violations = [];
+    let edgesChecked = 0;
+    for (const file of tree.sort(byCodeUnit)) {
+        const from = placed(file);
+        for (const edge of edgesOf(root, files, cache, file).edges) {
+            const target = placed(edge.to);
+            if (target === null || target.unit === from.unit)
+                continue;
+            edgesChecked += 1;
+            if (target.layer > from.layer)
+                continue;
+            violations.push({ ruleId: 'FE_TIER_DIRECTION', path: file, line: edge.line, column: 1, specifier: edge.specifier, resolvedPath: edge.to,
+                message: `${file}: a ${layers[from.layer]} component may import only the layers after it (${layers.slice(from.layer + 1).join(', ') || 'none'}); it imports a ${layers[target.layer]}. Type-only imports count.` });
+        }
+    }
+    return { violations, coverage: { status: 'checked', files: tree.length, edgesChecked } };
+}
+/** The machine check: the grammar libraries of the repository, judged by `tiers.grammar` of the slot manifest. */
+export function checkGrammarTiers({ config }) {
+    const matrix = config.hfs.manifest.tiers.grammar;
+    if (matrix === undefined)
+        return { violations: [], coverage: { status: 'not-applicable' } };
+    return checkGrammarLibraries({ root: config.root, matrix });
+}

package/runtime/scripts/hfs/architecture/config.mjs

@@ -208,7 +208,7 @@ function inferredLayout(root, workspaces) {
     // A design-system workspace whose src carries tier dirs (leaves/branches/…) IS a component root;
     // collecting its src/components too would nest two roots in one role and fail the disjoint check.
     const tierSources = new Set(workspaces.map(prefix => `${prefix}/src`)
-        .filter(source => ['leaves', 'branches', 'blocks', 'overlays', 'composites', 'layouts', 'product-shells', 'pages']
+        .filter(source => ['leaves', 'branches', 'blocks', 'frames', 'overlays', 'composites', 'layouts', 'product-shells', 'pages']
         .some(tier => existingDirectory(root, `${source}/${tier}`))));
     const components = collect('src/components')
         .filter(relative => !tierSources.has(path.posix.dirname(relative)));

package/runtime/scripts/hfs/architecture/frontend-world.mjs

@@ -5,7 +5,7 @@ import { WorldRenderAnalysis } from './frontend-world-render.mjs';
 const WORLD_NAVIGATION_CALLS = new Set(['useParams', 'usePathname', 'useRouter', 'useSearchParams', 'useSelectedLayoutSegment', 'useSelectedLayoutSegments']);
 const WORLD_INTL_CALLS = new Set(['useLocale', 'useMessages', 'useNow', 'useTimeZone', 'useTranslations']);
 const WORLD_SWR_CALLS = new Set(['default', 'useSWR', 'useSWRConfig', 'useSWRImmutable', 'useSWRMutation']);
-const LOWER_COMPONENT_TIERS = new Set(['composites', 'branches', 'leaves']);
+const LOWER_COMPONENT_TIERS = new Set(['frames', 'composites', 'branches', 'leaves']);
 function selectedSymbol(ts, checker, expression) {
     const selected = unwrapExpression(ts, expression);
     if (!selected)

package/runtime/scripts/hfs/architecture/frontend.mjs

@@ -8,7 +8,7 @@ import { checkWorldRenderBoundaries } from './frontend-world.mjs';
 import { checkGrammar } from './frontend-grammar.mjs';
 import { checkRoute } from './frontend-routing.mjs';
 const FEATURE_TIERS = new Set(['pages', 'layouts', 'overlays']);
-const COMPONENT_TIERS = new Set(['blocks', 'composites', 'branches', 'leaves', 'providers']);
+const COMPONENT_TIERS = new Set(['blocks', 'frames', 'composites', 'branches', 'leaves', 'providers']);
 function absolute(root, relative) {
     return path.resolve(root, ...relative.split('/'));
 }
@@ -82,7 +82,7 @@ function checkFrontendSourceLayout(config, sourceFile, roots) {
         valid = located.relative.includes('/') || roleEntry(located.relative);
     return valid ? [] : [{ ruleId: 'FE_SOURCE_LAYOUT_INVALID', path: relativePath(config.root, sourceFile.fileName), line: 1, column: 1,
             message: { features: 'Frontend features contain only pages, layouts and overlays plus an optional root public entry.',
-                components: 'Frontend components contain only blocks, composites, branches, leaves and providers plus an optional root public entry.',
+                components: 'Frontend components contain only blocks, frames, composites, branches, leaves and providers plus an optional root public entry.',
                 hooks: 'Every authored custom hook is grouped below a domain folder under hooks; only the root public entry may sit directly under hooks.' }[located.role] }];
 }
 function declarationName(ts, declaration) {

package/runtime/scripts/hfs/architecture/index.mjs

@@ -42,9 +42,12 @@ import { checkBackgroundUnowned, BACKGROUND_UNOWNED_RULE_IDS } from './backgroun
 import { checkTransportOwner, TRANSPORT_OWNER_RULE_IDS } from './transport-owner.mjs';
 import { checkRouteFilesThin, ROUTE_FILES_THIN_RULE_IDS } from './route-files-thin.mjs';
 import { checkHooksAreHooks, HOOKS_ARE_HOOKS_RULE_IDS } from './hooks-are-hooks.mjs';
+import { checkRenderPropAcrossServer, RENDER_PROP_ACROSS_SERVER_RULE_IDS } from './render-prop-across-server.mjs';
+import { checkSurfaceNesting, SURFACE_NESTING_RULE_IDS } from './surface-nesting.mjs';
 import { checkClientReachesServer, CLIENT_REACHES_SERVER_RULE_IDS } from './client-reaches-server.mjs';
 import { checkCrossAppDuplicate, CROSS_APP_DUPLICATE_RULE_IDS } from './cross-app-duplicate.mjs';
 import { checkPackageShape, PACKAGE_SHAPE_RULE_IDS } from './package-shape.mjs';
+import { COMPONENT_TIER_RULE_IDS, checkGrammarTiers } from './component-tiers.mjs';
 import { checkFeSlotAllows, FE_SLOT_ALLOWS_RULE_IDS } from './fe-slot-allows.mjs';
 import { checkI18nKeys, I18N_KEYS_RULE_IDS } from './i18n-keys.mjs';
 import { checkDocLanguage, DOC_LANGUAGE_RULE_IDS } from './doc-language.mjs';
@@ -92,10 +95,13 @@ const FRONTEND_MACHINE = {
     hooksAreHooks: [checkHooksAreHooks, HOOKS_ARE_HOOKS_RULE_IDS],
     packageShape: [checkPackageShape, PACKAGE_SHAPE_RULE_IDS],
     clientReachesServer: [checkClientReachesServer, CLIENT_REACHES_SERVER_RULE_IDS],
+    surfaceNesting: [checkSurfaceNesting, SURFACE_NESTING_RULE_IDS],
+    renderPropAcrossServer: [checkRenderPropAcrossServer, RENDER_PROP_ACROSS_SERVER_RULE_IDS],
     crossAppDuplicate: [checkCrossAppDuplicate, CROSS_APP_DUPLICATE_RULE_IDS],
     feSlotAllows: [checkFeSlotAllows, FE_SLOT_ALLOWS_RULE_IDS],
     i18nKeys: [checkI18nKeys, I18N_KEYS_RULE_IDS],
     serverActions: [checkServerActions, SERVER_ACTION_RULE_IDS],
+    grammarTiers: [checkGrammarTiers, COMPONENT_TIER_RULE_IDS],
 };
 /** Errors the machine reports when a program cannot be built or an edge cannot be proven: it cannot judge, so it refuses. */
 const COMMON_REFUSAL_RULE_IDS = [

package/runtime/scripts/hfs/architecture/render-graph.d.mts

@@ -0,0 +1,125 @@
+/**
+ * The render graph: which component draws which, and where each places the `children` and slot props it is given.
+ *
+ * One ESLint file sees one component. An app splits a screen across files, so a card inside a card, a table inside a card or a
+ * grid in the wrong page can stand in three files. This module reads the source of the program (no type checker: the parsed files
+ * of the HFS graph and its resolved import edges) and answers one question for the checks built on it: starting from a component,
+ * what is drawn inside what, once every app component is replaced by what it draws and every `{children}` or `{props.slot}` by what
+ * its caller handed it.
+ *
+ * Limits, stated because a check built here is only as honest as they are:
+ *   - conditional JSX counts as drawn (both branches), a `.map` callback counts as drawn once and is marked `repeated`;
+ *   - a render prop (a function passed as a prop) is not followed;
+ *   - a component reached through a variable, a prop or a dynamic import is not followed;
+ *   - a local render helper (`renderRow(x)`) is followed to three levels.
+ */
+import type { Node } from 'typescript';
+import type { TypeScriptApi } from './config.mjs';
+import type { HfsGraph } from './hfs-graph.mjs';
+/** What a JSX tag names. */
+export type Tag = {
+    readonly kind: 'grammar';
+    readonly name: string;
+} | {
+    readonly kind: 'component';
+    readonly file: string;
+    readonly name: string;
+} | {
+    readonly kind: 'host';
+    readonly name: string;
+} | {
+    readonly kind: 'unknown';
+    readonly name: string;
+};
+/** A JSX attribute as the graph keeps it: its literal text when it has one, and the elements it carries. */
+export interface RenderAttribute {
+    readonly name: string;
+    /** The string of a string literal or `{"..."}`, `'true'` for a bare attribute or `{true}`, `'false'` for `{false}`, otherwise null. */
+    readonly text: string | null;
+    readonly parts: readonly RenderPart[];
+}
+/** One element of a render. */
+export interface RenderElement {
+    readonly kind: 'element';
+    readonly tag: Tag;
+    readonly attributes: ReadonlyMap<string, RenderAttribute>;
+    readonly children: readonly RenderPart[];
+    /** True when the element is made by a `.map` callback: one of several. */
+    readonly repeated: boolean;
+    readonly file: string;
+    readonly node: Node;
+}
+/** Where a component places something its caller handed it: `children`, or the named slot prop. */
+export interface RenderPlacement {
+    readonly kind: 'placement';
+    readonly prop: string;
+    readonly file: string;
+    readonly node: Node;
+}
+/** A piece of a render. */
+export type RenderPart = RenderElement | RenderPlacement;
+/** An app component: where it is declared and what it draws. */
+export interface ComponentDefinition {
+    readonly file: string;
+    readonly name: string;
+    readonly returns: readonly RenderPart[];
+}
+/** What a caller handed a component, with the supplier of the caller's own render. */
+export interface Supplier {
+    readonly children: readonly RenderPart[];
+    readonly slots: ReadonlyMap<string, readonly RenderPart[]>;
+    readonly outer: Supplier | null;
+}
+/** An element on the way down: a grammar or host element that encloses what is being walked. */
+export interface Ancestor {
+    readonly element: RenderElement;
+}
+/** What a walk reports to a check. */
+export interface RenderVisitor {
+    /** An element, with its grammar ancestors outermost first and the component stack that led to it. */
+    enter?(element: RenderElement, ancestors: readonly Ancestor[], stack: readonly string[]): void;
+    /** The elements one parent draws side by side, placements and fragments resolved, in order. */
+    siblings?(elements: readonly RenderElement[], ancestors: readonly Ancestor[], stack: readonly string[]): void;
+    /** A grammar or host element with the elements it draws directly, placements resolved. */
+    parent?(element: RenderElement, drawn: readonly RenderElement[], ancestors: readonly Ancestor[], stack: readonly string[]): void;
+}
+/** Everything the walk needs about the files of one program. */
+export declare class RenderGraph {
+    readonly ts: TypeScriptApi;
+    readonly graph: HfsGraph;
+    private readonly components;
+    private readonly imports;
+    private readonly exportsCache;
+    private readonly fileEdges;
+    constructor(ts: TypeScriptApi, graph: HfsGraph);
+    /** Every app component of the program. */
+    allComponents(): ComponentDefinition[];
+    /** The component a file declares under a name. */
+    componentOf(file: string, name: string): ComponentDefinition | null;
+    /** The location of a node, 1-based. */
+    locate(element: {
+        readonly file: string;
+        readonly node: Node;
+    }): {
+        path: string;
+        line: number;
+        column: number;
+    };
+    private readComponents;
+    /** The function a declaration initializer is or wraps (`memo(fn)`, `forwardRef(fn)`). */
+    private functionOf;
+    private returnsOf;
+    private importsOf;
+    /** The file and local name that declare what `file` exports under `name`, following re-exports. */
+    private resolveExport;
+    private exportTable;
+    /** What the JSX tag `tagName` of a file names. */
+    tagOf(rel: string, tagName: Node): Tag;
+    /** Walks everything `root` draws with the empty context, reporting each element and each run of siblings to the visitor. */
+    walkFrom(root: ComponentDefinition, visitor: RenderVisitor): void;
+    private walk;
+    /** Parts with placements replaced by what the supplier handed over; each element keeps the supplier its own placements read. */
+    private flatten;
+    /** The one element a component element draws at its root, or null when it draws several things or none. */
+    rootOf(element: RenderElement): RenderElement | null;
+}