@starci/eslint-canon-fe 8.4.39 → 8.4.41

package/runtime/scripts/lib/language.mjs

@@ -15,7 +15,7 @@ export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìí
 export const hasSecondLanguage = (text) => typeof text === 'string' && SECOND_LANGUAGE_LETTER.test(text.normalize('NFC'));
 
 /** Every line of `text` with a Vietnamese letter: `[{ line, column }]`, both 1-based. */
-export function secondLanguageHits(text) {
+function secondLanguageHits(text) {
   const hits = [];
   String(text).split(/\r?\n/).forEach((raw, index) => {
     const match = SECOND_LANGUAGE_LETTER.exec(raw.normalize('NFC'));
@@ -24,6 +24,99 @@ export function secondLanguageHits(text) {
   return hits;
 }
 
+/** The named bindings of an import from the backend message catalog contract. */
+function messageCatalogBindings(ts, statement) {
+  if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== '@modules/platform/i18n') return null;
+  return statement.importClause?.namedBindings ?? null;
+}
+
+/** The local type names imported from the backend message catalog contract. */
+function messageBundleImports(ts, source) {
+  const named = new Set();
+  const namespaces = new Set();
+  for (const statement of source.statements) {
+    const bindings = messageCatalogBindings(ts, statement);
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    for (const entry of ts.isNamedImports(bindings) ? bindings.elements : []) {
+      if ((entry.propertyName ?? entry.name).text === 'MessageBundle') named.add(entry.name.text);
+    }
+  }
+  return { named, namespaces };
+}
+
+/** A declaration that introduces a same-named local type or namespace. */
+function declaresTypeName(ts, statement, name) {
+  if (statement.name?.text !== name) return false;
+  return [ts.isTypeAliasDeclaration, ts.isInterfaceDeclaration, ts.isClassDeclaration, ts.isEnumDeclaration, ts.isModuleDeclaration]
+    .some(predicate => predicate(statement));
+}
+
+/** A type reference bound to the imported MessageBundle contract, including import aliases. */
+function isMessageBundleType(ts, type, imports) {
+  if (!type || !ts.isTypeReferenceNode(type)) return false;
+  const name = type.typeName;
+  if (ts.isIdentifier(name)) return imports.named.has(name.text) && !shadowsImportedType(ts, type, name.text);
+  return ts.isQualifiedName(name) && ts.isIdentifier(name.left)
+    && imports.namespaces.has(name.left.text) && name.right.text === 'MessageBundle' && !shadowsImportedType(ts, type, name.left.text);
+}
+
+/** A local declaration or generic type parameter takes precedence over a same-named import. */
+function shadowsImportedType(ts, node, name) {
+  for (let scope = node.parent; scope; scope = scope.parent) {
+    if (scope.typeParameters?.some(parameter => parameter.name.text === name)) return true;
+    if (scope.statements?.some(statement => declaresTypeName(ts, statement, name))) return true;
+  }
+  return false;
+}
+
+/** The literal object supplied by a variable typed with the imported MessageBundle contract. */
+function messageCatalogObject(ts, node, imports) {
+  if (!ts.isVariableDeclaration(node) || !node.initializer) return null;
+  let value = node.initializer;
+  const type = ts.isSatisfiesExpression(value) ? value.type : node.type;
+  if (ts.isSatisfiesExpression(value)) value = value.expression;
+  return isMessageBundleType(ts, type, imports) && ts.isObjectLiteralExpression(value) ? value : null;
+}
+
+/** Literal string values in the Vietnamese locale of one message catalog. */
+function vietnameseValueRanges(ts, catalog, source) {
+  const ranges = [];
+  for (const locale of catalog.properties) {
+    if (!ts.isPropertyAssignment(locale) || locale.name.text !== 'vi' || !ts.isObjectLiteralExpression(locale.initializer)) continue;
+    for (const message of locale.initializer.properties) {
+      if (ts.isPropertyAssignment(message) && ts.isStringLiteralLike(message.initializer))
+        ranges.push({ start: message.initializer.getStart(source), end: message.initializer.end });
+    }
+  }
+  return ranges;
+}
+
+/** Literal Vietnamese message values of typed catalogs; keys, comments, English values and expressions remain source. */
+function messageBundleValueRanges(ts, source) {
+  const imports = messageBundleImports(ts, source);
+  const ranges = [];
+  const visit = (node) => {
+    const catalog = messageCatalogObject(ts, node, imports);
+    if (catalog) ranges.push(...vietnameseValueRanges(ts, catalog, source));
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return ranges;
+}
+
+/** Source-language hits, treating only literal vi values of typed backend MessageBundle objects as translated product data. */
+export function sourceLanguageHits(rel, text, ts) {
+  if (!hasSecondLanguage(text)) return [];
+  if (!ts || !/\.[cm]?tsx?$/.test(rel)) return secondLanguageHits(text);
+  const source = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true);
+  let sourceText = text;
+  for (const range of messageBundleValueRanges(ts, source).sort((left, right) => right.start - left.start)) {
+    sourceText = sourceText.slice(0, range.start) + sourceText.slice(range.start, range.end).replace(/[^\r\n]/g, ' ') + sourceText.slice(range.end);
+  }
+  return secondLanguageHits(sourceText);
+}
+
 /**
  * The Vietnamese fields of one failure-code entry: the operator text the owner mandated for the failure-code catalog
  * (scripts/checks/check-failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.

package/runtime/scripts/lib/package-at.mjs

@@ -0,0 +1,62 @@
+// scripts/lib/package-at.mjs — a package the runtime does not ship (playwright, esbuild, tailwindcss) comes from the
+// project that owns it: node resolution from that project's directory, walking up its node_modules.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+
+/** The package.json of `name` as resolved from `dir`, or null. */
+export const packageAt = (dir, name) => {
+  try { return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`); } catch { return null; }
+};
+
+/** This runtime's own `starci` bin (packages/cli is the only package that declares one). */
+const RUNTIME_STARCI_BIN = path.join(skillRoot, 'packages', 'cli', 'bin', 'starci.mjs');
+
+/** The `starci` bin of the @starci/cli that `dir` installs (a product runs its own pinned CLI), else this runtime's own. */
+function starciBin(dir) {
+  const packageFile = packageAt(dir, '@starci/cli');
+  if (packageFile) {
+    try {
+      const { bin } = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+      const rel = typeof bin === 'string' ? bin : bin?.starci;
+      const file = rel ? path.join(path.dirname(packageFile), rel) : null;
+      if (file && fs.existsSync(file)) return file;
+    } catch { /* an unreadable install falls back to the runtime's own CLI */ }
+  }
+  return RUNTIME_STARCI_BIN;
+}
+
+/** The first of `names` resolvable from the first of `dirs` that has one: {name, root, packageFile, version} or null. */
+export function findPackage(dirs, names) {
+  for (const dir of dirs.filter(Boolean)) {
+    for (const name of names) {
+      const packageFile = packageAt(dir, name);
+      if (!packageFile) continue;
+      const require = createRequire(packageFile);
+      return { name, root: path.dirname(packageFile), packageFile, version: require(packageFile).version };
+    }
+  }
+  return null;
+}
+
+/** The CommonJS entry of a package found by findPackage. */
+export const requirePackage = (found) => createRequire(found.packageFile)(found.name);
+
+/** The TypeScript compiler resolvable from the first of `dirs` (an app root, then the caller's own), or null. */
+export const loadTypescript = (...dirs) => {
+  const located = findPackage(dirs, ['typescript']);
+  return located ? requirePackage(located) : null;
+};
+
+/**
+ * The app's command line and the app implementation behind it: `bin` the `starci` bin of the app's installed @starci/cli, else
+ * this runtime's packages/cli/bin/starci.mjs (starciBin); `dir` the @starci/hfs that answers
+ * `starci app` - the app's own install, else the one beside its @starci/cli, else this runtime's packages/hfs - whose runtime
+ * slice the gate's base lint (scripts/gates/gate.mjs) and the READ digest (scripts/gates/read-digest.mjs) load in-process.
+ */
+export function hfsEntry(root) {
+  const cli = packageAt(root, '@starci/cli');
+  const manifest = packageAt(root, '@starci/hfs') ?? (cli && packageAt(path.dirname(cli), '@starci/hfs'));
+  return { dir: manifest ? path.dirname(manifest) : path.join(skillRoot, 'packages', 'hfs'), bin: starciBin(root) };
+}

package/runtime/scripts/lib/same-text.mjs

@@ -0,0 +1,5 @@
+// same-text.mjs - text equality that ignores the line-ending form and a trailing blank tail (a git runner may trim stdout, a work tree may
+// carry CRLF): the one comparison the database rules use for a committed file against its base or against a regenerated one.
+
+/** True when both texts exist and are equal once CRLF is folded to LF and trailing whitespace at the end is dropped. */
+export const sameText = (a, b) => a !== null && b !== null && a.replaceAll('\r\n', '\n').trimEnd() === b.replaceAll('\r\n', '\n').trimEnd();

package/runtime/scripts/lib/secret-patterns.mjs

@@ -56,6 +56,45 @@ const ASSIGNED_UNQUOTED = new RegExp(
   SECRET_NAME + String.raw`(?!['"\`]|env\()([A-Za-z0-9_+=-]{12,})(?![A-Za-z0-9_+=.(\[-])`,
 );
 
+const SQL_ROLE_HEAD = /^\s*(?:CREATE|ALTER)\s+(?:ROLE|USER)\b/i;
+const SQL_STATEMENT = /[^;\r\n]+/g;
+const SQL_PASSWORD_WORD = /\bPASSWORD\s+/gi;
+const PSQL_PASSWORD_REFERENCE = /:(?:'[A-Za-z_]\w*'|"[A-Za-z_]\w*")/y;
+const SQL_PASSWORD_QUOTED = /'([^'\r\n]{12,})'/y;
+const ASSIGNED_PLACEHOLDER = /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i;
+const SQL_PASSWORD_RULE = { name: 'assigned-secret' };
+
+/** Read only password tokens in role statements; sticky value readers never retry at later character positions. */
+function sqlPasswordParts(file, text) {
+  const references = [], literals = [];
+  if (!/\.(?:sql|sh)(?:\.tpl)?$/i.test(file ?? '')) return { references, literals };
+  for (const statement of text.matchAll(SQL_STATEMENT)) {
+    if (!SQL_ROLE_HEAD.test(statement[0])) continue;
+    for (const keyword of statement[0].matchAll(SQL_PASSWORD_WORD)) {
+      const start = statement.index + keyword.index + keyword[0].length;
+      PSQL_PASSWORD_REFERENCE.lastIndex = start;
+      SQL_PASSWORD_QUOTED.lastIndex = start;
+      const reference = PSQL_PASSWORD_REFERENCE.exec(text);
+      const literal = SQL_PASSWORD_QUOTED.exec(text);
+      if (reference) references.push([start, start + reference[0].length]);
+      if (literal) literals.push(literal[1]);
+    }
+  }
+  return { references, literals };
+}
+
+/** Psql variable references retain their positions while the assignment heuristic sees no literal value there. */
+function maskedReferences(text, references) {
+  const parts = [];
+  let cursor = 0;
+  for (const [start, end] of references) {
+    parts.push(text.slice(cursor, start), ' '.repeat(end - start));
+    cursor = end;
+  }
+  parts.push(text.slice(cursor));
+  return parts.join('');
+}
+
 const NAME_WORD = (word, tail) => new RegExp(`^${NAME_REST}${SEGMENT_BEFORE}(?:${word})${tail}`);
 const SECRET_NAME_TEST = NAME_WORD(SECRET_WORD, String.raw`(?:[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$)`);
 const BENIGN_TAIL_TEST = NAME_WORD(BENIGN_WORD, '$');
@@ -84,27 +123,37 @@ export const SECRET_PATTERNS = [
   // A spec file's keyword-assigned values are test inputs (a spec's sign-in
   // form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
   // A SCREAMING_SNAKE quoted value in source is a public code (an enum member whose value is an upper-case code), not a credential.
-  { name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  { name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: ASSIGNED_PLACEHOLDER,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
   // An unquoted value in TypeScript or JavaScript source is an identifier or a type (`token: InjectionToken`,
   // `MODULE_OPTIONS_TOKEN: DATABASE_OPTIONS_TOKEN`), never a literal; the unquoted form is the dotenv, compose and toml shape.
-  { name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  { name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: ASSIGNED_PLACEHOLDER,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$|\.[cm]?[jt]sx?$/ },
 ];
 
 
-/** The names of the patterns one line of `file` matches (never the value). A stand-in value and a spec file's keyword assignment are no hit. */
-export function secretHits(file, text) {
-  const names = [];
+/** Matched pattern metadata stays private; callers receive pattern names, never credential values. */
+function matchingSecretPatterns(file, text) {
+  const matches = [];
+  const sql = sqlPasswordParts(file, text);
+  const assignments = maskedReferences(text, sql.references);
   for (const rule of SECRET_PATTERNS) {
     if (rule.skipFile?.test(file ?? '')) continue;
-    const hit = rule.re.exec(text);
-    if (hit && rule.sourceCode?.test(hit[1] ?? '') && /\.[cm]?[jt]sx?$/.test(file ?? '')) continue;
-    if (hit && !rule.placeholder?.test(hit[1] ?? '')) names.push(rule.name);
+    const hit = rule.re.exec(rule.name === 'assigned-secret' ? assignments : text);
+    if (hit && !rule.placeholder?.test(hit[1] ?? '')) matches.push({ rule, value: hit[1] ?? '' });
   }
-  return names;
+  for (const value of sql.literals) if (!ASSIGNED_PLACEHOLDER.test(value)) matches.push({ rule: SQL_PASSWORD_RULE, value });
+  return matches;
 }
 
+/** The strict secret-shape judgement used by Work custody, including uppercase keyword-assigned credentials. */
+export const secretPatternHits = (file, text) => matchingSecretPatterns(file, text).map(({ rule }) => rule.name);
+
+/** The source judgement also admits public SCREAMING_SNAKE codes; every provider shape remains refused. */
+export const secretHits = (file, text) => matchingSecretPatterns(file, text)
+  .filter(({ rule, value }) => !(rule.sourceCode?.test(value) && /\.[cm]?[jt]sx?$/.test(file ?? '')))
+  .map(({ rule }) => rule.name);
+
 const BADGE_BEGIN = '<!-- >>> starci app sync (managed block; do not edit) >>> -->';
 const BADGE_END = '<!-- <<< starci app sync <<< -->';
 

package/runtime/scripts/lib/source-phrases.mjs

@@ -0,0 +1,34 @@
+// source-phrases.mjs - the Vietnamese phrase lists runtime source matches against owner or product text are DATA,
+// not source: they live in modules/goal/source-phrases.yaml (its leaf keys are declared Vietnamese fields,
+// scripts/lib/language.mjs DECLARED_VIETNAMESE_FIELDS - like the archetypes.yaml phrase lists) so the matchers'
+// source stays English. A list is plain words or regex alternatives, per its comment in the lexicon.
+//
+//   phrasesOf('owed.ownerWord')   -> the list as written (['<owner word>', ...])
+//   altOf('owed.ownerWord')       -> the regex alternation 'a|b|c'; '(?!)' - never matches - when absent
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+const SOURCE_PHRASES_FILE = 'modules/goal/source-phrases.yaml';
+
+const cache = new Map();
+
+/** The lexicon's `phrases` map ({<group>: {<list>: string[]}}), cached per root. */
+function sourcePhrases(root = skillRoot) {
+  if (!cache.has(root)) {
+    let doc = null;
+    try { doc = parseYaml(fs.readFileSync(path.join(root, ...SOURCE_PHRASES_FILE.split('/')), 'utf8')); } catch { doc = null; }
+    cache.set(root, doc?.phrases && typeof doc.phrases === 'object' ? doc.phrases : {});
+  }
+  return cache.get(root);
+}
+
+/** The phrase list `dotKey` (`<group>.<list>`) of `root`, [] when absent. */
+export function phrasesOf(dotKey, root = skillRoot) {
+  const value = dotKey.split('.').reduce((v, k) => (v && typeof v === 'object' ? v[k] : undefined), sourcePhrases(root));
+  return (Array.isArray(value) ? value : []).map(String);
+}
+
+/** The regex alternation of `dotKey` ('a|b|c'); '(?!)' - a never-match - when the list is empty. */
+export const altOf = (dotKey, root = skillRoot) => phrasesOf(dotKey, root).join('|') || '(?!)';

package/runtime/scripts/lib/ts-analysis.mjs

@@ -25,3 +25,13 @@ export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiterals
 
 /** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
 export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });
+
+/** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
+export function lexicalChecker(ts, source) {
+  const options = { noLib: true, noResolve: true, allowJs: true };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = (file) => file === source.fileName ? source : undefined;
+  host.fileExists = () => false;
+  host.readFile = () => undefined;
+  return ts.createProgram([source.fileName], options, host).getTypeChecker();
+}

package/size-and-state-budget.mjs

@@ -205,9 +205,9 @@ const readsData = (context, fn, seen = new Set()) => {
  * No hand-written polling loop in a component or hook.
  *
  * A timer is polling when what it runs READS DATA (see `readsData`, decided by the type of each call, not by a name): a
- * `setInterval`, or a `setTimeout` whose callback schedules the enclosing function again. The FE convention names no shared clock
- * owner (knowledge/hfs/README.md section 6: "one refresh mechanism per resource, poll or socket"), so a timer that only ticks time
- * or state - a `useNow`-style one-minute clock behind `useSyncExternalStore` - is not a second refresh mechanism.
+ * `setInterval`, or a `setTimeout` whose callback schedules the enclosing function again. A timer that only ticks time or state
+ * is not a data-refresh mechanism. Grammar's live-time ownership is independently enforced by `no-app-relative-clock` in
+ * `grammar-boundary.mjs`.
  */
 export const noHandRolledPolling = {
   meta: {

package/surface-rules.mjs

@@ -0,0 +1,230 @@
+/** Grammar owns surface nesting and the single content edge of a panel list (ANATOMY-2, PADDING-0). */
+import { attributeValue, stringOf } from "./lib/ast.mjs"
+import { importOf, isFn, patternPath, unwrap, variableOf } from "./lib/bindings.mjs"
+import { typedClassStrings, typedPropertyStrings } from "./lib/typed-class-values.mjs"
+import { reactHookOf } from "./lib/react.mjs"
+
+const GRAMMAR_ENTRY = /^@starci\/grammar(?:\/(?:common|core|heritage|offset-pop))?$/
+const SURFACES = new Set([
+  "SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard", "Rail", "Sidebar",
+  "Dialog", "Drawer", "AlertDialog", "Popover",
+])
+const FIELDS = new Set([
+  "Input", "TextField", "Textarea", "TextArea", "SearchField", "NumberField", "DateField", "TimeField",
+  "Select", "ComboBox", "DatePicker", "DateRangePicker", "Checkbox", "CheckboxGroup", "RadioGroup", "PressableField", "OtpInput",
+])
+const CLASS_BUILDERS = new Set(["cn", "clsx", "classNames", "cva", "tv"])
+
+/** Resolve a JSX name to its Grammar export and optional compound parts, preserving lexical import identity. */
+const grammarName = (context, name) => {
+  if (name.type === "JSXMemberExpression") {
+    const owner = grammarName(context, name.object)
+    return owner === null ? null : [...owner, name.property.name]
+  }
+  if (name.type !== "JSXIdentifier") return null
+  const imported = importOf(context, name)
+  if (!imported || !GRAMMAR_ENTRY.test(imported.source)) return null
+  if (imported.imported !== null) return [imported.imported]
+  const binding = variableOf(context, name)?.defs.find((definition) => definition.type === "ImportBinding")
+  return binding?.node.type === "ImportNamespaceSpecifier" ? [] : null
+}
+
+/** Class and variant expressions expose their statically authored strings, including const aliases and cn branches. */
+const authoredStrings = (context, input, seen = new Set(), mode = "classes") => {
+  const node = unwrap(input?.type === "JSXExpressionContainer" ? input.expression : input)
+  if (!node || seen.has(node)) return []
+  seen.add(node)
+  const text = stringOf(node)
+  if (text !== null) return [{ node, text }]
+  if (node.type === "TemplateElement") return [{ node, text: node.value.cooked ?? node.value.raw }]
+  if (node.type === "Identifier") {
+    const values = bindingValues(context, node)
+    return values.length ? values.flatMap((value) => authoredStrings(context, value, seen, mode)) : typedClassStrings(context, node, mode)
+  }
+  if (node.type === "MemberExpression") {
+    const propertyName = node.computed ? stringOf(node.property) : node.property.name
+    const values = propertyValues(context, node.object, propertyName)
+    return values.length ? values.flatMap((value) => authoredStrings(context, value, seen, mode)) : typedClassStrings(context, node, mode)
+  }
+  const children = stringChildren(node, mode)
+  return children.flatMap((child) => authoredStrings(context, child, seen, mode))
+}
+
+/** Only value-bearing positions contribute classes; object keys support cn's conditional class dictionary. */
+const stringChildren = (node, mode) => {
+  if (node.type === "TemplateLiteral") return mode === "classes" ? [...node.quasis, ...node.expressions] : []
+  if (node.type === "ArrayExpression") return node.elements
+  if (node.type === "CallExpression") return mode === "classes" ? node.arguments : []
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate]
+  if (node.type === "LogicalExpression") return node.operator === "&&" ? [node.right] : [node.left, node.right]
+  if (node.type === "ObjectExpression") return node.properties.flatMap((property) => property.type === "Property" ? [property.key, property.value] : [property.argument])
+  return []
+}
+
+/** A declared React component is a separate render tree; inline collection/render callbacks keep the surrounding context. */
+const componentBoundary = (context, node) => {
+  if (!isFn(node)) return false
+  if (node.parent?.type === "CallExpression" && ["memo", "forwardRef"].includes(reactHookOf(context, node.parent))) return true
+  if (node.parent?.type === "JSXExpressionContainer" || node.parent?.type === "CallExpression" && node.parent.arguments.includes(node)) return false
+  const name = node.id?.name ?? (node.parent?.type === "VariableDeclarator" ? node.parent.id.name : null)
+  return name !== null && /^[A-Z]/.test(name)
+}
+
+/** The Grammar ancestors whose rendered content contains this node, excluding an overlay's trigger. */
+function* surfaceAncestors(context, node) {
+  const triggers = new Set()
+  for (let current = node.parent; current; current = current.parent) {
+    if (componentBoundary(context, current)) return
+    if (current.type === "JSXAttribute" && current.name.name === "trigger") triggers.add(current.parent)
+    if (current.type === "JSXElement" && !triggers.has(current.openingElement)) yield current.openingElement
+  }
+}
+
+const isSurface = (context, node, descendant) => {
+  const name = grammarName(context, node.name)
+  if (name?.length !== 1) return false
+  if (SURFACES.has(name[0])) return true
+  if (name[0] !== "ChatWorkspace") return false
+  for (let current = descendant; current && current !== node.parent; current = current.parent) {
+    if (current.type === "JSXAttribute" && current.parent === node && current.name.name === "rail") return true
+  }
+  return false
+}
+const classTokens = (text) => text.split(/\s+/).map((token) => token.split(":").at(-1).replace(/^!|!$/g, ""))
+const rawSurface = (token) => /^bg-surface(?:-[a-z0-9-]+)?(?:\/[^\s]+)?$/.test(token)
+const horizontalPadding = (token) => /^(?:px|ps|pe)-.+$/.test(token)
+
+/** Computed keys select their evaluated static name, rather than the identifier's spelling. */
+const propertyName = (context, property) => {
+  if (!property.computed) return property.key.name ?? property.key.value
+  const values = authoredStrings(context, property.key, new Set(), "variant")
+  return values.length === 1 ? values[0].text : null
+}
+
+/** A binding selects its own object property; sibling declarations do not become its value. */
+const bindingValues = (context, node, seen = new Set()) => {
+  const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable")
+  if (!definition) return []
+  const path = patternPath(definition.node.id, node.name)
+  if (path === null) return []
+  return path.reduce((values, key) => values.flatMap((value) => propertyValues(context, value, key, seen)), [definition.node.init]).filter(Boolean)
+}
+
+/** Static object spreads retain the same published-prop obligations as ordinary JSX attributes. */
+const propertyValues = (context, input, key, seen = new Set()) => {
+  const node = unwrap(input)
+  if (!node || seen.has(node)) return []
+  seen.add(node)
+  if (node.type === "Identifier") {
+    return bindingValues(context, node, seen).flatMap((value) => propertyValues(context, value, key, seen))
+  }
+  if (node.type === "MemberExpression") {
+    const member = node.computed ? stringOf(node.property) : node.property.name
+    return propertyValues(context, node.object, member, seen).flatMap((value) => propertyValues(context, value, key, seen))
+  }
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].flatMap((branch) => propertyValues(context, branch, key, seen))
+  if (node.type !== "ObjectExpression") return []
+  return node.properties.flatMap((property) => {
+    if (property.type === "SpreadElement") return propertyValues(context, property.argument, key, seen)
+    return propertyName(context, property) === key ? [property.value] : []
+  })
+}
+
+const propStrings = (context, entry, name, mode = "classes") => {
+  if (entry.type === "JSXSpreadAttribute") {
+    const values = propertyValues(context, entry.argument, name)
+    return values.length ? values.flatMap((value) => authoredStrings(context, value, new Set(), mode)) : typedPropertyStrings(context, entry.argument, name, mode)
+  }
+  return entry.name.name === name ? authoredStrings(context, attributeValue(entry), new Set(), mode) : []
+}
+
+/** An explicit section caption excludes the row's own content subtree. */
+const inSectionCaption = (context, node) => {
+  for (const ancestor of surfaceAncestors(context, node.parent)) {
+    const owner = grammarName(context, ancestor.name)
+    if (owner?.[0] !== "ListBox") continue
+    if (owner[1] === "Item") return false
+    if (["Section", "Header", "SectionHeader"].includes(owner[1])) return true
+  }
+  return false
+}
+
+/** ANATOMY-2: Grammar provides the secondary default; apps cannot force primary or paint a raw surface. */
+export const nestedControlVariant = {
+  meta: {
+    type: "problem",
+    docs: { description: "ANATOMY-2: nested fields use Grammar's secondary default and surfaces belong to Grammar." },
+    schema: [],
+    messages: {
+      primary: "FE_NESTED_VARIANT: a field inside a Grammar surface cannot force variant=\"primary\". Omit variant so Grammar supplies secondary through its nesting context.",
+      surface: "FE_NESTED_VARIANT: bg-surface paints a surface in app CSS. Compose SurfaceCard, Rail, Sidebar or another Grammar surface instead.",
+    },
+  },
+  create(context) {
+    const reported = new Set()
+    const checkClasses = (value) => {
+      for (const entry of authoredStrings(context, value)) {
+        if (!classTokens(entry.text).some(rawSurface) || reported.has(entry.node)) continue
+        reported.add(entry.node)
+        context.report({ node: entry.node, messageId: "surface" })
+      }
+    }
+    return {
+      JSXOpeningElement(node) {
+        const name = grammarName(context, node.name)
+        const variant = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").some((value) => value.text === "primary"))
+        if (name?.length !== 1 || !FIELDS.has(name[0]) || !variant) return
+        if ([...surfaceAncestors(context, node.parent)].some((ancestor) => isSurface(context, ancestor, node))) context.report({ node: variant, messageId: "primary" })
+      },
+      JSXAttribute(node) {
+        if (["className", "class", "classNames"].includes(node.name.name)) checkClasses(node.value)
+      },
+      CallExpression(node) {
+        if (node.callee.type === "Identifier" && CLASS_BUILDERS.has(node.callee.name)) checkClasses(node)
+      },
+      VariableDeclarator(node) {
+        if (/[Cc]lass/.test(node.id.name ?? "") || /(?:^|[/\\])classNames\.[cm]?[jt]sx?$/.test(context.filename)) checkClasses(node.init)
+      },
+      Property(node) {
+        if (["className", "class", "classNames"].includes(propertyName(context, node))) checkClasses(node.value)
+      },
+    }
+  },
+}
+
+/** PADDING-0: app padding wrappers cannot add a second horizontal inset to Grammar's list or section caption. */
+export const noListPanelPadding = {
+  meta: {
+    type: "problem",
+    docs: { description: "PADDING-0: panel lists and section captions share the Grammar surface's content edge." },
+    schema: [],
+    messages: { padding: "FE_LIST_PANEL_PADDING: horizontal padding stacks with the Grammar list inset. Remove this wrapper padding and use ListBox inset=\"panel\" so rows and section captions share the panel content edge." },
+  },
+  create(context) {
+    const reported = new Set()
+    const check = (opening) => {
+      const className = opening.attributes.find((entry) => ["className", "class"].some((name) => propStrings(context, entry, name).some((value) => classTokens(value.text).some(horizontalPadding))))
+      if (!className || reported.has(className)) return
+      reported.add(className)
+      context.report({ node: className, messageId: "padding" })
+    }
+    return {
+      JSXOpeningElement(node) {
+        const name = grammarName(context, node.name)
+        if (name?.[0] === "ListBox" && (name.length === 1 || ["Section", "Header", "SectionHeader"].includes(name[1]))) {
+          check(node)
+          for (const ancestor of surfaceAncestors(context, node.parent)) {
+            check(ancestor)
+            if (isSurface(context, ancestor, node)) break
+          }
+        } else if (inSectionCaption(context, node)) check(node)
+      },
+    }
+  },
+}
+
+/** The surface laws ship at error in every composing source tree. */
+export const rules = { "nested-control-variant": nestedControlVariant, "no-list-panel-padding": noListPanelPadding }
+
+/** No app can lower or omit a surface law. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))