@softize/opus 12.10.0 → 12.11.0

package/bin/lib/check.mjs

@@ -21,66 +21,287 @@
  * É a régua do reviewer e a métrica de padrão.
  */
 
-import path from 'node:path'
-import ts from 'typescript'
+import path from "node:path";
+import ts from "typescript";
 import {
   canonicalProjectDirectory,
   readProjectDirectory,
   readProjectFile,
   safeProjectPath,
-} from '@softize/base/project-path'
+} from "@softize/base/project-path";
 
 // Ordem canônica (grupos do ActionBase em src/core/types.ts). Campos kind-específicos
 // (fields/paginate/filters/expand/background/emits/successStatus…) NÃO entram no mapa —
 // são ignorados na checagem de ordem (não geram falso-positivo).
 const FIELD_GROUP = {
-  name: 0, kind: 0,
-  label: 1, title: 1, summary: 1, description: 1, icon: 1, color: 1, messages: 1, tags: 1, examples: 1, errors: 1,
-  input: 2, output: 2,
-  public: 3, requires: 3, authorize: 3, loads: 3,
-  handler: 4, mockHandler: 4,
-  audit: 5, confirm: 5, invalidates: 5, rateLimit: 5, idempotency: 5,
-  ai: 6, automatable: 6, internal: 6,
-}
+  name: 0,
+  kind: 0,
+  label: 1,
+  title: 1,
+  summary: 1,
+  description: 1,
+  icon: 1,
+  color: 1,
+  messages: 1,
+  tags: 1,
+  examples: 1,
+  errors: 1,
+  input: 2,
+  output: 2,
+  public: 3,
+  requires: 3,
+  authorize: 3,
+  loads: 3,
+  handler: 4,
+  mockHandler: 4,
+  audit: 5,
+  confirm: 5,
+  invalidates: 5,
+  rateLimit: 5,
+  idempotency: 5,
+  ai: 6,
+  automatable: 6,
+  internal: 6,
+};
 
 // <resource>.<verb> com namespacing opcional: <resource>(.<sub>)*.<verb> — ≥2 segmentos,
 // minúsculo+hífen. Ex.: client.list, user.set-password, ticket.sla.check.
-const SEG = '[a-z][a-z0-9]*(-[a-z0-9]+)*'
-const ACTION_NAME_RE = new RegExp(`^${SEG}(\\.${SEG})+$`)
-const KINDS = new Set(['simple', 'form', 'list', 'view'])
+const SEG = "[a-z][a-z0-9]*(-[a-z0-9]+)*";
+const ACTION_NAME_RE = new RegExp(`^${SEG}(\\.${SEG})+$`);
+const KINDS = new Set(["simple", "form", "list", "view"]);
 
 // Tokens públicos removidos cuja ausência no CSS não quebra typecheck/build: sem uma
 // migração executável, o consumidor perde borda/sombra em silêncio. O check fica no Opus
 // (dono do contrato visual), não no Maestro. Uma ocorrência por token/arquivo basta.
 const REMOVED_UI_TOKENS = new Map([
-  ['ring-edge', 'use `border border-border` para a aresta da superfície'],
-  ['border-edge', 'use `border-border`'],
-  ['shadow-card', 'use `shadow-sm`'],
-  ['shadow-popover', 'use `shadow-md`'],
-  ['shadow-dialog', 'use `shadow-lg`'],
-  ['rounded-card', 'use `rounded-xl`'],
-  ['rounded-popover', 'use `rounded-md`'],
-  ['rounded-dialog', 'use `rounded-xl`'],
-  ['--edge-value', 'remova o override; a aresta agora usa `--border`'],
-  ['--color-edge', 'remova o token; a aresta agora usa `--border`'],
-  ['--elevation-card', 'use/ajuste `--shadow-sm`'],
-  ['--elevation-popover', 'use/ajuste `--shadow-md`'],
-  ['--elevation-dialog', 'use/ajuste `--shadow-lg`'],
-  ['--radius-card', 'use/ajuste `--radius-xl`'],
-  ['--radius-popover', 'use/ajuste `--radius-md`'],
-  ['--radius-dialog', 'use/ajuste `--radius-xl`'],
-])
+  ["ring-edge", "use `border border-border` para a aresta da superfície"],
+  ["border-edge", "use `border-border`"],
+  ["shadow-card", "use `shadow-sm`"],
+  ["shadow-popover", "use `shadow-md`"],
+  ["shadow-dialog", "use `shadow-lg`"],
+  ["rounded-card", "use `rounded-xl`"],
+  ["rounded-popover", "use `rounded-md`"],
+  ["rounded-dialog", "use `rounded-xl`"],
+  ["--edge-value", "remova o override; a aresta agora usa `--border`"],
+  ["--color-edge", "remova o token; a aresta agora usa `--border`"],
+  ["--elevation-card", "use/ajuste `--shadow-sm`"],
+  ["--elevation-popover", "use/ajuste `--shadow-md`"],
+  ["--elevation-dialog", "use/ajuste `--shadow-lg`"],
+  ["--radius-card", "use/ajuste `--radius-xl`"],
+  ["--radius-popover", "use/ajuste `--radius-md`"],
+  ["--radius-dialog", "use/ajuste `--radius-xl`"],
+]);
 
 // Superfícies com foreground próprio formam um par indivisível. Exigir as duas
 // utilities no mesmo fragmento de classes torna a regra local, revisável e evita que a
 // igualdade acidental com `--foreground` esconda um tema quebrado.
 const UI_SURFACE_PAIRS = new Map([
-  ['bg-card', 'text-card-foreground'],
-  ['bg-popover', 'text-popover-foreground'],
-])
+  ["bg-card", "text-card-foreground"],
+  ["bg-popover", "text-popover-foreground"],
+]);
+
+// Anatomia pública das superfícies compostas (ADR 0005). O lint olha somente nomes
+// importados de @softize/opus/ui/react, evitando atribuir regras da biblioteca a componentes
+// locais homônimos.
+const UI_STRUCTURAL_PARENTS = new Map([
+  ["PageHeader", new Set(["Page"])],
+  ["PageBody", new Set(["Page"])],
+  ["PageTitle", new Set(["PageHeader"])],
+  ["PageDescription", new Set(["PageHeader"])],
+  ["PageMeta", new Set(["PageHeader"])],
+  ["PageActions", new Set(["PageHeader"])],
+  ["ContentHeader", new Set(["Content"])],
+  ["ContentBody", new Set(["Content"])],
+  ["ContentTitle", new Set(["ContentHeader"])],
+  ["ContentDescription", new Set(["ContentHeader"])],
+  ["ContentMeta", new Set(["ContentHeader"])],
+  ["ContentActions", new Set(["ContentHeader"])],
+  ["CardHeader", new Set(["Card"])],
+  ["CardBody", new Set(["Card"])],
+  ["CardFooter", new Set(["Card"])],
+  ["CardTitle", new Set(["CardHeader"])],
+  ["CardDescription", new Set(["CardHeader"])],
+  ["CardAction", new Set(["CardHeader"])],
+  ["DialogHeader", new Set(["DialogContent"])],
+  ["DialogBody", new Set(["DialogContent"])],
+  ["DialogFooter", new Set(["DialogContent"])],
+  ["DialogTitle", new Set(["DialogHeader"])],
+  ["DialogDescription", new Set(["DialogHeader"])],
+  ["DrawerHeader", new Set(["DrawerContent"])],
+  ["DrawerBody", new Set(["DrawerContent"])],
+  ["DrawerFooter", new Set(["DrawerContent"])],
+  ["DrawerTitle", new Set(["DrawerHeader"])],
+  ["DrawerDescription", new Set(["DrawerHeader"])],
+  ["PaneHeader", new Set(["Pane", "Sidebar"])],
+  ["PaneBody", new Set(["Pane", "Sidebar"])],
+  ["PaneFooter", new Set(["Pane", "Sidebar"])],
+  ["AlertMedia", new Set(["Alert"])],
+  ["AlertHeader", new Set(["Alert"])],
+  ["AlertActions", new Set(["Alert"])],
+  ["AlertTitle", new Set(["AlertHeader"])],
+  ["AlertDescription", new Set(["AlertHeader"])],
+  ["ItemMedia", new Set(["Item"])],
+  ["ItemHeader", new Set(["Item"])],
+  ["ItemBody", new Set(["Item"])],
+  ["ItemContent", new Set(["Item"])],
+  ["ItemActions", new Set(["Item"])],
+  ["ItemFooter", new Set(["Item"])],
+  ["ItemTitle", new Set(["ItemHeader"])],
+  ["ItemDescription", new Set(["ItemHeader"])],
+  ["EmptyHeader", new Set(["Empty"])],
+  ["EmptyContent", new Set(["Empty"])],
+  ["EmptyMedia", new Set(["EmptyHeader"])],
+  ["EmptyTitle", new Set(["EmptyHeader"])],
+  ["EmptyDescription", new Set(["EmptyHeader"])],
+  ["AlertDialogHeader", new Set(["AlertDialogContent"])],
+  ["AlertDialogFooter", new Set(["AlertDialogContent"])],
+  ["AlertDialogMedia", new Set(["AlertDialogHeader"])],
+  ["AlertDialogTitle", new Set(["AlertDialogHeader"])],
+  ["AlertDialogDescription", new Set(["AlertDialogHeader"])],
+  ["PopoverHeader", new Set(["PopoverContent"])],
+  ["PopoverTitle", new Set(["PopoverHeader"])],
+  ["PopoverDescription", new Set(["PopoverHeader"])],
+]);
+
+const UI_STRUCTURAL_ROOTS = new Map([
+  [
+    "Page",
+    {
+      header: "PageHeader",
+      body: "PageBody",
+      shorthand: new Set(["title", "description", "count", "actions"]),
+    },
+  ],
+  [
+    "Content",
+    {
+      header: "ContentHeader",
+      body: "ContentBody",
+      shorthand: new Set(["title", "description", "meta", "actions"]),
+    },
+  ],
+]);
+
+const UI_STRICT_DIRECT_COMPONENTS = new Set([
+  "PageHeader",
+  "PageBody",
+  "PageTitle",
+  "PageDescription",
+  "PageMeta",
+  "PageActions",
+  "ContentHeader",
+  "ContentBody",
+  "ContentTitle",
+  "ContentDescription",
+  "ContentMeta",
+  "ContentActions",
+  "AlertMedia",
+  "AlertHeader",
+  "AlertActions",
+]);
+
+const UI_STRUCTURAL_HEADERS = new Map([
+  [
+    "PageHeader",
+    {
+      title: "PageTitle",
+      optional: new Set(["PageDescription", "PageMeta", "PageActions"]),
+      shorthand: new Set(),
+    },
+  ],
+  [
+    "ContentHeader",
+    {
+      title: "ContentTitle",
+      optional: new Set([
+        "ContentDescription",
+        "ContentMeta",
+        "ContentActions",
+      ]),
+      shorthand: new Set(["title", "description", "meta", "actions"]),
+    },
+  ],
+  [
+    "AlertHeader",
+    {
+      title: "AlertTitle",
+      optional: new Set(["AlertDescription"]),
+      shorthand: new Set(),
+      titleRequired: false,
+      allowOpaque: true,
+    },
+  ],
+  [
+    "ItemHeader",
+    {
+      title: "ItemTitle",
+      optional: new Set(["ItemDescription"]),
+      shorthand: new Set(),
+    },
+  ],
+]);
+
+// API semântica canônica (ADR 0006). Os aliases continuam no runtime somente para que uma
+// atualização não quebre o app antes da migração; código-fonte novo deve separar significado
+// (`context`) de tratamento visual (`variant`).
+const UI_LEGACY_VARIANTS = new Map([
+  ["Button", new Set(["default", "secondary", "destructive"])],
+  [
+    "Badge",
+    new Set([
+      "default",
+      "secondary",
+      "destructive",
+      "info",
+      "success",
+      "warning",
+      "danger",
+    ]),
+  ],
+  [
+    "DictionaryValue",
+    new Set([
+      "default",
+      "secondary",
+      "destructive",
+      "info",
+      "success",
+      "warning",
+      "danger",
+    ]),
+  ],
+  [
+    "Alert",
+    new Set([
+      "default",
+      "destructive",
+      "info",
+      "success",
+      "warning",
+      "danger",
+    ]),
+  ],
+  [
+    "Dot",
+    new Set([
+      "default",
+      "secondary",
+      "destructive",
+      "info",
+      "success",
+      "warning",
+      "danger",
+    ]),
+  ],
+  ["MetricCard", new Set()],
+  ["MenuItem", new Set(["default", "destructive"])],
+  ["ActionTrigger", new Set(["default", "secondary", "destructive"])],
+  ["AlertDialogAction", new Set(["default", "secondary", "destructive"])],
+  ["AlertDialogCancel", new Set(["default", "secondary", "destructive"])],
+]);
 
 /** Os três nomes que denotam action/contrato — o arquivo sem nenhum deles é pulado. */
-export const ACTION_MARKERS = ['defineAction', 'defineContract', 'bindAction']
+export const ACTION_MARKERS = ["defineAction", "defineContract", "bindAction"];
 
 /**
  * Extrai `defineAction`/`defineContract`/`bindAction` de um source. Puro/sintático —
@@ -88,71 +309,86 @@ export const ACTION_MARKERS = ['defineAction', 'defineContract', 'bindAction']
  * da const, se houver) e, no bindAction, `contractRef` (o identificador do 1º arg).
  */
 export function parseActions(fileName, sourceText) {
-  const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
-  const actions = []
+  const sf = ts.createSourceFile(
+    fileName,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const actions = [];
 
-  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1
+  const lineOf = (node) =>
+    sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
 
   function constIdent(callNode) {
-    const decl = callNode.parent
-    if (!decl || !ts.isVariableDeclaration(decl)) return null
-    return ts.isIdentifier(decl.name) ? decl.name.text : null
+    const decl = callNode.parent;
+    if (!decl || !ts.isVariableDeclaration(decl)) return null;
+    return ts.isIdentifier(decl.name) ? decl.name.text : null;
   }
 
   function isExported(callNode) {
     // call → VariableDeclaration → VariableDeclarationList → VariableStatement (com export)
-    const decl = callNode.parent
-    if (!decl || !ts.isVariableDeclaration(decl)) return false
-    const list = decl.parent
-    const stmt = list && list.parent
-    if (!stmt || !ts.isVariableStatement(stmt)) return false
-    return (stmt.modifiers ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    const decl = callNode.parent;
+    if (!decl || !ts.isVariableDeclaration(decl)) return false;
+    const list = decl.parent;
+    const stmt = list && list.parent;
+    if (!stmt || !ts.isVariableStatement(stmt)) return false;
+    return (stmt.modifiers ?? []).some(
+      (m) => m.kind === ts.SyntaxKind.ExportKeyword,
+    );
   }
 
   function strProp(obj, key) {
     const p = obj.properties.find(
-      (pr) => ts.isPropertyAssignment(pr) && pr.name && pr.name.getText(sf) === key,
-    )
-    if (!p || !ts.isStringLiteral(p.initializer)) return null
-    return p.initializer.text
+      (pr) =>
+        ts.isPropertyAssignment(pr) && pr.name && pr.name.getText(sf) === key,
+    );
+    if (!p || !ts.isStringLiteral(p.initializer)) return null;
+    return p.initializer.text;
   }
 
   function objKeys(obj) {
     return obj.properties
-      .filter((p) => ts.isPropertyAssignment(p) || ts.isMethodDeclaration(p) || ts.isShorthandPropertyAssignment(p))
-      .map((p) => (p.name ? p.name.getText(sf) : ''))
-      .filter(Boolean)
+      .filter(
+        (p) =>
+          ts.isPropertyAssignment(p) ||
+          ts.isMethodDeclaration(p) ||
+          ts.isShorthandPropertyAssignment(p),
+      )
+      .map((p) => (p.name ? p.name.getText(sf) : ""))
+      .filter(Boolean);
   }
 
   function visit(node) {
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
-      const callee = node.expression.text
+      const callee = node.expression.text;
 
       if (
-        (callee === 'defineAction' || callee === 'defineContract') &&
+        (callee === "defineAction" || callee === "defineContract") &&
         node.arguments.length > 0 &&
         ts.isObjectLiteralExpression(node.arguments[0])
       ) {
-        const obj = node.arguments[0]
+        const obj = node.arguments[0];
         actions.push({
           form: callee,
-          name: strProp(obj, 'name'),
-          kind: strProp(obj, 'kind'),
+          name: strProp(obj, "name"),
+          kind: strProp(obj, "kind"),
           keys: objKeys(obj),
           ident: constIdent(node),
           exported: isExported(node),
           line: lineOf(node),
-        })
+        });
       }
 
       if (
-        callee === 'bindAction' &&
+        callee === "bindAction" &&
         node.arguments.length >= 2 &&
         ts.isObjectLiteralExpression(node.arguments[1])
       ) {
-        const ref = node.arguments[0]
+        const ref = node.arguments[0];
         actions.push({
-          form: 'bindAction',
+          form: "bindAction",
           name: null,
           kind: null,
           keys: objKeys(node.arguments[1]),
@@ -160,67 +396,90 @@ export function parseActions(fileName, sourceText) {
           contractRef: ts.isIdentifier(ref) ? ref.text : ref.getText(sf),
           exported: isExported(node),
           line: lineOf(node),
-        })
+        });
       }
     }
-    ts.forEachChild(node, visit)
+    ts.forEachChild(node, visit);
   }
-  visit(sf)
-  return actions
+  visit(sf);
+  return actions;
 }
 
 /** Aplica as regras locais (por arquivo) a um item → findings. */
 export function lintAction(a) {
-  const out = []
-  const label = a.name ?? (a.form === 'bindAction' ? `bindAction(${a.contractRef})` : '(sem name)')
-  const at = (rule, message) => out.push({ rule, level: 'error', action: label, line: a.line, message })
+  const out = [];
+  const label =
+    a.name ??
+    (a.form === "bindAction" ? `bindAction(${a.contractRef})` : "(sem name)");
+  const at = (rule, message) =>
+    out.push({ rule, level: "error", action: label, line: a.line, message });
 
-  if (a.form === 'bindAction') {
+  if (a.form === "bindAction") {
     // O binding não repete name/kind/ordem — quem carrega isso é o contrato.
-    if (!a.exported) at('export', 'bindAction precisa ser `export const` (senão não dá pra registrar)')
-    return out
+    if (!a.exported)
+      at(
+        "export",
+        "bindAction precisa ser `export const` (senão não dá pra registrar)",
+      );
+    return out;
   }
 
-  if (!a.name) at('action-name', `${a.form} sem \`name\``)
-  else if (!ACTION_NAME_RE.test(a.name)) at('action-name', `name "${a.name}" não é <resource>.<verb> (minúsculo, ponto)`)
+  if (!a.name) at("action-name", `${a.form} sem \`name\``);
+  else if (!ACTION_NAME_RE.test(a.name))
+    at(
+      "action-name",
+      `name "${a.name}" não é <resource>.<verb> (minúsculo, ponto)`,
+    );
 
-  if (!a.kind) at('kind', `${a.form} sem \`kind\``)
-  else if (!KINDS.has(a.kind)) at('kind', `kind "${a.kind}" inválido (use simple|form|list|view)`)
+  if (!a.kind) at("kind", `${a.form} sem \`kind\``);
+  else if (!KINDS.has(a.kind))
+    at("kind", `kind "${a.kind}" inválido (use simple|form|list|view)`);
 
   // field-order: os campos conhecidos devem ter group-index não-decrescente
-  let lastGroup = -1
-  let lastKey = ''
+  let lastGroup = -1;
+  let lastKey = "";
   for (const k of a.keys) {
-    const g = FIELD_GROUP[k]
-    if (g === undefined) continue // kind-específico/desconhecido → lenient
+    const g = FIELD_GROUP[k];
+    if (g === undefined) continue; // kind-específico/desconhecido → lenient
     if (g < lastGroup) {
-      at('field-order', `campo "${k}" fora de ordem (depois de "${lastKey}") — siga identidade→docs→input/output→authorize→handler→comportamento`)
-      break
+      at(
+        "field-order",
+        `campo "${k}" fora de ordem (depois de "${lastKey}") — siga identidade→docs→input/output→authorize→handler→comportamento`,
+      );
+      break;
     }
-    lastGroup = g
-    lastKey = k
+    lastGroup = g;
+    lastKey = k;
   }
 
-  if (!a.exported) at('export', `${a.form} precisa ser \`export const\` (senão não dá pra registrar)`)
+  if (!a.exported)
+    at(
+      "export",
+      `${a.form} precisa ser \`export const\` (senão não dá pra registrar)`,
+    );
 
   // requires sem authorize: no defineAction o par mora no mesmo objeto — acusa direto.
   // No defineContract a regra é cross-file (o bind pode trazer o authorize row-level);
   // fica pro join do checkProject.
-  if (a.form === 'defineAction' && a.keys.includes('requires') && !a.keys.includes('authorize')) {
+  if (
+    a.form === "defineAction" &&
+    a.keys.includes("requires") &&
+    !a.keys.includes("authorize")
+  ) {
     at(
-      'requires-sem-authorize',
-      '`requires` é declarativo (o runtime não o executa) — sem `authorize`, a action fica ABERTA. Declare o authorize.',
-    )
+      "requires-sem-authorize",
+      "`requires` é declarativo (o runtime não o executa) — sem `authorize`, a action fica ABERTA. Declare o authorize.",
+    );
   }
 
-  return out
+  return out;
 }
 
 /** Checa um source isolado → { actions, findings }. Regras cross-file: checkProject. */
 export function checkSource(fileName, sourceText) {
-  const actions = parseActions(fileName, sourceText)
-  const findings = actions.flatMap(lintAction)
-  return { actions, findings }
+  const actions = parseActions(fileName, sourceText);
+  const findings = actions.flatMap(lintAction);
+  return { actions, findings };
 }
 
 /**
@@ -231,343 +490,877 @@ export function checkSource(fileName, sourceText) {
  * Referência não encontrada ou identificador duplicado não acusa.
  */
 export function checkProject(sources) {
-  let actions = 0
-  let contracts = 0
-  const findings = []
-  const contractsByIdent = new Map() // ident → item | 'ambiguous'
-  const binds = [] // { item, file }
+  let actions = 0;
+  let contracts = 0;
+  const findings = [];
+  const contractsByIdent = new Map(); // ident → item | 'ambiguous'
+  const binds = []; // { item, file }
 
   for (const { file, text } of sources) {
     for (const item of parseActions(file, text)) {
-      if (item.form === 'bindAction') {
-        actions += 1
-        binds.push({ item, file })
-      } else if (item.form === 'defineContract') {
-        contracts += 1
+      if (item.form === "bindAction") {
+        actions += 1;
+        binds.push({ item, file });
+      } else if (item.form === "defineContract") {
+        contracts += 1;
         if (item.ident !== null) {
-          contractsByIdent.set(item.ident, contractsByIdent.has(item.ident) ? 'ambiguous' : item)
+          contractsByIdent.set(
+            item.ident,
+            contractsByIdent.has(item.ident) ? "ambiguous" : item,
+          );
         }
       } else {
-        actions += 1
+        actions += 1;
       }
-      for (const f of lintAction(item)) findings.push({ ...f, file })
+      for (const f of lintAction(item)) findings.push({ ...f, file });
     }
   }
 
   for (const { item, file } of binds) {
-    const contract = contractsByIdent.get(item.contractRef)
-    if (contract === undefined || contract === 'ambiguous') continue
-    const protectedSomewhere = contract.keys.includes('authorize') || item.keys.includes('authorize')
-    if (contract.keys.includes('requires') && !protectedSomewhere) {
+    const contract = contractsByIdent.get(item.contractRef);
+    if (contract === undefined || contract === "ambiguous") continue;
+    const protectedSomewhere =
+      contract.keys.includes("authorize") || item.keys.includes("authorize");
+    if (contract.keys.includes("requires") && !protectedSomewhere) {
       findings.push({
-        rule: 'requires-sem-authorize',
-        level: 'error',
+        rule: "requires-sem-authorize",
+        level: "error",
         action: contract.name ?? item.contractRef,
         line: item.line,
         file,
         message:
-          '`requires` do contrato é declarativo (o runtime não o executa) — sem `authorize` no contrato ou no binding, a action fica ABERTA.',
-      })
+          "`requires` do contrato é declarativo (o runtime não o executa) — sem `authorize` no contrato ou no binding, a action fica ABERTA.",
+      });
     }
   }
 
-  return { actions, contracts, findings }
+  return { actions, contracts, findings };
 }
 
 /** Migrações de UI que falhariam apenas visualmente. Linhas que são só comentário não
  * contam; documentação vive fora do sourceRoot e também não entra no walk. */
 function stripComments(text) {
-  let output = ''
-  let state = 'code'
-  let escaped = false
+  let output = "";
+  let state = "code";
+  let escaped = false;
   for (let index = 0; index < text.length; index += 1) {
-    const char = text[index]
-    const next = text[index + 1]
-    if (state === 'line-comment') {
-      if (char === '\n') { state = 'code'; output += char } else output += ' '
-      continue
+    const char = text[index];
+    const next = text[index + 1];
+    if (state === "line-comment") {
+      if (char === "\n") {
+        state = "code";
+        output += char;
+      } else output += " ";
+      continue;
     }
-    if (state === 'block-comment') {
-      if (char === '*' && next === '/') { output += '  '; index += 1; state = 'code' }
-      else output += char === '\n' ? '\n' : ' '
-      continue
+    if (state === "block-comment") {
+      if (char === "*" && next === "/") {
+        output += "  ";
+        index += 1;
+        state = "code";
+      } else output += char === "\n" ? "\n" : " ";
+      continue;
     }
-    if (state === 'html-comment') {
-      if (char === '-' && text.slice(index, index + 3) === '-->') {
-        output += '   '; index += 2; state = 'code'
-      } else output += char === '\n' ? '\n' : ' '
-      continue
+    if (state === "html-comment") {
+      if (char === "-" && text.slice(index, index + 3) === "-->") {
+        output += "   ";
+        index += 2;
+        state = "code";
+      } else output += char === "\n" ? "\n" : " ";
+      continue;
     }
-    if (state === 'code' && text.slice(index, index + 4) === '<!--') {
-      output += '    '; index += 3; state = 'html-comment'; continue
+    if (state === "code" && text.slice(index, index + 4) === "<!--") {
+      output += "    ";
+      index += 3;
+      state = "html-comment";
+      continue;
     }
-    if (state === 'code' && char === '/' && next === '/') {
-      output += '  '; index += 1; state = 'line-comment'; continue
+    if (state === "code" && char === "/" && next === "/") {
+      output += "  ";
+      index += 1;
+      state = "line-comment";
+      continue;
     }
-    if (state === 'code' && char === '/' && next === '*') {
-      output += '  '; index += 1; state = 'block-comment'; continue
+    if (state === "code" && char === "/" && next === "*") {
+      output += "  ";
+      index += 1;
+      state = "block-comment";
+      continue;
     }
-    if (state === 'code' && (char === "'" || char === '"' || char === '`')) {
-      state = char; output += char; escaped = false; continue
+    if (state === "code" && (char === "'" || char === '"' || char === "`")) {
+      state = char;
+      output += char;
+      escaped = false;
+      continue;
     }
-    if (state !== 'code') {
-      output += char
-      if (escaped) escaped = false
-      else if (char === '\\') escaped = true
-      else if (char === state) state = 'code'
-      continue
+    if (state !== "code") {
+      output += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === state) state = "code";
+      continue;
     }
-    output += char
+    output += char;
   }
-  return output
+  return output;
 }
 
 function quotedValues(text) {
-  const values = []
-  let line = 1
+  const values = [];
+  let line = 1;
   const startsRegex = (index) => {
-    const before = text.slice(0, index).trimEnd()
-    if (before === '') return true
-    const previous = before.at(-1)
-    return /[=(:,![{;?&|+*%^~<>-]/.test(previous) ||
-      /\b(?:return|case|throw|typeof|instanceof|in|of|yield|await)\s*$/.test(before)
-  }
+    const before = text.slice(0, index).trimEnd();
+    if (before === "") return true;
+    const previous = before.at(-1);
+    return (
+      /[=(:,![{;?&|+*%^~<>-]/.test(previous) ||
+      /\b(?:return|case|throw|typeof|instanceof|in|of|yield|await)\s*$/.test(
+        before,
+      )
+    );
+  };
   for (let index = 0; index < text.length; index += 1) {
-    const quote = text[index]
-    if (quote === '\n') { line += 1; continue }
-    if (quote === '/' && startsRegex(index)) {
-      let escaped = false
-      let inCharacterClass = false
+    const quote = text[index];
+    if (quote === "\n") {
+      line += 1;
+      continue;
+    }
+    if (quote === "/" && startsRegex(index)) {
+      let escaped = false;
+      let inCharacterClass = false;
       for (index += 1; index < text.length; index += 1) {
-        const char = text[index]
-        if (char === '\n') line += 1
-        if (escaped) { escaped = false; continue }
-        if (char === '\\') { escaped = true; continue }
-        if (char === '[') { inCharacterClass = true; continue }
-        if (char === ']') { inCharacterClass = false; continue }
-        if (char === '/' && !inCharacterClass) break
+        const char = text[index];
+        if (char === "\n") line += 1;
+        if (escaped) {
+          escaped = false;
+          continue;
+        }
+        if (char === "\\") {
+          escaped = true;
+          continue;
+        }
+        if (char === "[") {
+          inCharacterClass = true;
+          continue;
+        }
+        if (char === "]") {
+          inCharacterClass = false;
+          continue;
+        }
+        if (char === "/" && !inCharacterClass) break;
       }
-      while (/[a-z]/i.test(text[index + 1] ?? '')) index += 1
-      continue
+      while (/[a-z]/i.test(text[index + 1] ?? "")) index += 1;
+      continue;
     }
-    if (quote !== "'" && quote !== '"' && quote !== '`') continue
-    let value = ''
-    let escaped = false
-    const startLine = line
-    const startIndex = index
+    if (quote !== "'" && quote !== '"' && quote !== "`") continue;
+    let value = "";
+    let escaped = false;
+    const startLine = line;
+    const startIndex = index;
     for (index += 1; index < text.length; index += 1) {
-      const char = text[index]
-      if (char === '\n') line += 1
-      if (escaped) { value += char; escaped = false; continue }
-      if (char === '\\') { value += char; escaped = true; continue }
-      if (char === quote) break
-      value += char
+      const char = text[index];
+      if (char === "\n") line += 1;
+      if (escaped) {
+        value += char;
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        value += char;
+        escaped = true;
+        continue;
+      }
+      if (char === quote) break;
+      value += char;
     }
-    values.push({ value, startLine, startIndex, endIndex: index })
+    values.push({ value, startLine, startIndex, endIndex: index });
   }
-  return values
+  return values;
 }
 
-const SIMPLE_TAILWIND_CLASSES = new Set(['flex', 'grid', 'block', 'inline', 'hidden', 'border', 'shadow', 'ring'])
+const SIMPLE_TAILWIND_CLASSES = new Set([
+  "flex",
+  "grid",
+  "block",
+  "inline",
+  "hidden",
+  "border",
+  "shadow",
+  "ring",
+]);
 
 function looksLikeUtilityValue(value, token, matchesToken) {
-  if (!matchesToken(value, token)) return false
-  const parts = value.trim().split(/\s+/).filter(Boolean)
-  return parts.length > 1 && parts.every((part) =>
-    matchesToken(part, token) || SIMPLE_TAILWIND_CLASSES.has(part) || /[-:[\]/!@.%]/.test(part),
-  )
+  if (!matchesToken(value, token)) return false;
+  const parts = value.trim().split(/\s+/).filter(Boolean);
+  return (
+    parts.length > 1 &&
+    parts.every(
+      (part) =>
+        matchesToken(part, token) ||
+        SIMPLE_TAILWIND_CLASSES.has(part) ||
+        /[-:[\]/!@.%]/.test(part),
+    )
+  );
 }
 
 function isInsideUtilityHelper(beforeValue) {
-  const matches = [...beforeValue.matchAll(/\b(?:cn|cva|clsx|twMerge)\s*\(/g)]
+  const matches = [...beforeValue.matchAll(/\b(?:cn|cva|clsx|twMerge)\s*\(/g)];
   for (const match of matches.reverse()) {
-    const call = beforeValue.slice(match.index)
-    let depth = 0
-    let quote = null
-    let escaped = false
+    const call = beforeValue.slice(match.index);
+    let depth = 0;
+    let quote = null;
+    let escaped = false;
     for (const char of call) {
       if (quote !== null) {
-        if (escaped) escaped = false
-        else if (char === '\\') escaped = true
-        else if (char === quote) quote = null
-        continue
+        if (escaped) escaped = false;
+        else if (char === "\\") escaped = true;
+        else if (char === quote) quote = null;
+        continue;
       }
-      if (char === "'" || char === '"' || char === '`') { quote = char; continue }
-      if (char === '(') depth += 1
-      else if (char === ')') depth -= 1
+      if (char === "'" || char === '"' || char === "`") {
+        quote = char;
+        continue;
+      }
+      if (char === "(") depth += 1;
+      else if (char === ")") depth -= 1;
+    }
+    if (depth > 0) return true;
+  }
+  return false;
+}
+
+function uiImports(sourceFile) {
+  const imports = new Map();
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.moduleSpecifier.text !== "@softize/opus/ui/react"
+    )
+      continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) {
+      imports.set(
+        element.name.text,
+        element.propertyName?.text ?? element.name.text,
+      );
     }
-    if (depth > 0) return true
   }
-  return false
+  return imports;
+}
+
+function jsxLocalName(node) {
+  const tag = ts.isJsxElement(node)
+    ? node.openingElement.tagName
+    : node.tagName;
+  return ts.isIdentifier(tag) ? tag.text : null;
+}
+
+function jsxOpening(node) {
+  return ts.isJsxElement(node) ? node.openingElement : node;
+}
+
+function directJsxParentName(node, imports) {
+  let parent = node.parent;
+  while (
+    ts.isParenthesizedExpression(parent) ||
+    ts.isConditionalExpression(parent) ||
+    ts.isBinaryExpression(parent) ||
+    ts.isJsxExpression(parent)
+  ) {
+    parent = parent.parent;
+  }
+  if (!ts.isJsxElement(parent)) return null;
+  const local = jsxLocalName(parent);
+  return local === null ? null : (imports.get(local) ?? null);
+}
+
+function structuralJsxAncestorName(node, imports) {
+  let current = node.parent;
+  while (current !== undefined) {
+    if (ts.isJsxElement(current) || ts.isJsxSelfClosingElement(current)) {
+      const local = jsxLocalName(current);
+      const imported = local === null ? undefined : imports.get(local);
+      if (
+        imported !== undefined &&
+        (UI_STRUCTURAL_ROOTS.has(imported) ||
+          UI_STRUCTURAL_PARENTS.has(imported) ||
+          [...UI_STRUCTURAL_PARENTS.values()].some((parents) =>
+            parents.has(imported),
+          ))
+      )
+        return imported;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+function directStructuralChildren(node, imports) {
+  if (!ts.isJsxElement(node)) return { names: [], hasOpaque: false };
+  const names = [];
+  let hasOpaque = false;
+  for (const child of node.children) {
+    if (ts.isJsxText(child) && child.text.trim() === "") continue;
+    if (ts.isJsxExpression(child) && child.expression === undefined) continue;
+    if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
+      const local = jsxLocalName(child);
+      const imported = local === null ? null : imports.get(local);
+      if (imported !== undefined) names.push(imported);
+      else hasOpaque = true;
+      continue;
+    }
+    hasOpaque = true;
+  }
+  return { names, hasOpaque };
+}
+
+/** Verifica a anatomia JSX pública definida na ADR 0005. */
+export function checkUiStructure(file, text) {
+  if (!/\.[cm]?[jt]sx$/.test(file)) return [];
+  const sourceFile = ts.createSourceFile(
+    file,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  const imports = uiImports(sourceFile);
+  if (imports.size === 0) return [];
+  const findings = [];
+  const lineOf = (node) =>
+    sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line +
+    1;
+  const add = (node, action, message, rule = "ui-structure") =>
+    findings.push({
+      rule,
+      level: "error",
+      action,
+      line: lineOf(node),
+      file,
+      message,
+    });
+
+  const visit = (node) => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const local = jsxLocalName(node);
+      const component = local === null ? null : imports.get(local);
+      const parents =
+        component === null ? undefined : UI_STRUCTURAL_PARENTS.get(component);
+      if (parents !== undefined) {
+        const strict = UI_STRICT_DIRECT_COMPONENTS.has(component);
+        const parent = strict
+          ? directJsxParentName(node, imports)
+          : structuralJsxAncestorName(node, imports);
+        // Slots das famílias históricas podem ser a raiz de um componente wrapper. Quando há
+        // uma superfície estrutural visível no mesmo JSX, porém, ela precisa ser a família certa.
+        if (
+          (strict || parent !== null) &&
+          (parent === null || !parents.has(parent))
+        ) {
+          add(
+            node,
+            component,
+            `${component} deve estar ${strict ? "como filho direto" : "dentro"} de ${[...parents].join(" ou ")}.`,
+          );
+        }
+      }
+
+      const header =
+        component === null ? undefined : UI_STRUCTURAL_HEADERS.get(component);
+      if (header !== undefined) {
+        const opening = jsxOpening(node);
+        const attributes = new Set(
+          opening.attributes.properties.flatMap((attribute) =>
+            ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name)
+              ? [attribute.name.text]
+              : [],
+          ),
+        );
+        const shorthand = [...header.shorthand].some((attribute) =>
+          attributes.has(attribute),
+        );
+        const children = directStructuralChildren(node, imports);
+        const structural =
+          children.names.includes(header.title) ||
+          children.names.some((name) => header.optional.has(name));
+        if (shorthand && structural) {
+          add(
+            node,
+            component,
+            `${component} não permite misturar propriedades de shorthand com seus slots explícitos.`,
+            "ui-structure-mode",
+          );
+        } else if (!shorthand) {
+          const titles = children.names.filter(
+            (name) => name === header.title,
+          ).length;
+          const unexpected = children.names.some(
+            (name) => name !== header.title && !header.optional.has(name),
+          );
+          const duplicatedOptional = [...header.optional].some(
+            (name) =>
+              children.names.filter((child) => child === name).length > 1,
+          );
+          const titleValid =
+            header.titleRequired === false ? titles <= 1 : titles === 1;
+          const recognizedContent =
+            titles +
+            children.names.filter((name) => header.optional.has(name)).length;
+          if (
+            !titleValid ||
+            (header.titleRequired === false &&
+              recognizedContent === 0 &&
+              !(header.allowOpaque && children.hasOpaque)) ||
+            unexpected ||
+            duplicatedOptional ||
+            (children.hasOpaque && !header.allowOpaque)
+          ) {
+            add(
+              node,
+              component,
+              `${component} explícito ${header.titleRequired === false ? `aceita no máximo um ${header.title}` : `exige um ${header.title}`} e aceita no máximo um de cada slot opcional como filhos diretos.`,
+            );
+          }
+        }
+      }
+
+      const root =
+        component === null ? undefined : UI_STRUCTURAL_ROOTS.get(component);
+      if (root !== undefined) {
+        const opening = jsxOpening(node);
+        const attributes = new Set(
+          opening.attributes.properties.flatMap((attribute) =>
+            ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name)
+              ? [attribute.name.text]
+              : [],
+          ),
+        );
+        const shorthand = [...root.shorthand].some((attribute) =>
+          attributes.has(attribute),
+        );
+        const children = directStructuralChildren(node, imports);
+        const structural =
+          children.names.includes(root.header) ||
+          children.names.includes(root.body);
+        if (shorthand && structural) {
+          add(
+            node,
+            component,
+            `${component} não permite misturar propriedades de shorthand com ${root.header}/${root.body}.`,
+            "ui-structure-mode",
+          );
+        } else if (!shorthand) {
+          const headers = children.names.filter(
+            (name) => name === root.header,
+          ).length;
+          const bodies = children.names.filter(
+            (name) => name === root.body,
+          ).length;
+          const unexpected = children.names.some(
+            (name) => name !== root.header && name !== root.body,
+          );
+          if (
+            headers !== 1 ||
+            bodies !== 1 ||
+            unexpected ||
+            children.hasOpaque
+          ) {
+            add(
+              node,
+              component,
+              `${component} explícito exige exatamente um ${root.header} e um ${root.body} como filhos diretos.`,
+            );
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return findings;
+}
+
+function jsxAttribute(opening, name) {
+  return opening.attributes.properties.find(
+    (candidate) =>
+      ts.isJsxAttribute(candidate) &&
+      ts.isIdentifier(candidate.name) &&
+      candidate.name.text === name,
+  );
+}
+
+function jsxStringAttributeValues(opening, name) {
+  const attribute = jsxAttribute(opening, name);
+  if (!attribute || !ts.isJsxAttribute(attribute) || !attribute.initializer)
+    return [];
+  if (ts.isStringLiteral(attribute.initializer))
+    return [attribute.initializer.text];
+  if (!ts.isJsxExpression(attribute.initializer)) return [];
+  const values = [];
+  const collect = (node) => {
+    if (ts.isStringLiteral(node)) values.push(node.text);
+    else ts.forEachChild(node, collect);
+  };
+  if (attribute.initializer.expression)
+    collect(attribute.initializer.expression);
+  return [...new Set(values)];
+}
+
+/** Reprova aliases de migração da API semântica e `tone` em novos dicionários. */
+export function checkUiSemantics(file, text) {
+  if (!/\.[cm]?[jt]sx?$/.test(file)) return [];
+  const sourceFile = ts.createSourceFile(
+    file,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  );
+  const imports = uiImports(sourceFile);
+  const schemaAliases = new Set();
+  const variableInitializers = new Map();
+  for (const statement of sourceFile.statements) {
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && declaration.initializer)
+          variableInitializers.set(
+            declaration.name.text,
+            declaration.initializer,
+          );
+      }
+    }
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.moduleSpecifier.text !== "@softize/opus/schema/zod"
+    )
+      continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) {
+      if ((element.propertyName?.text ?? element.name.text) === "t")
+        schemaAliases.add(element.name.text);
+    }
+  }
+
+  const findings = [];
+  const lineOf = (node) =>
+    sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line +
+    1;
+  const add = (node, action, message) =>
+    findings.push({
+      rule: "ui-semantic-api",
+      level: "error",
+      action,
+      line: lineOf(node),
+      file,
+      message,
+    });
+
+  const visit = (node) => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const local = jsxLocalName(node);
+      const component = local === null ? null : imports.get(local);
+      if (component !== null && UI_LEGACY_VARIANTS.has(component)) {
+        const opening = jsxOpening(node);
+        if (jsxAttribute(opening, "tone") !== undefined) {
+          add(
+            opening,
+            `${component}.tone`,
+            `${component} usa \`context\` para significado semântico; \`tone\` é apenas um alias temporário.`,
+          );
+        }
+        const legacyVariants = jsxStringAttributeValues(
+          opening,
+          "variant",
+        ).filter((variant) => UI_LEGACY_VARIANTS.get(component).has(variant));
+        for (const variant of legacyVariants) {
+          add(
+            opening,
+            `${component}.variant=${variant}`,
+            "Separe o significado em `context` e use `variant` somente para tratamento visual.",
+          );
+        }
+      }
+    }
+
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      schemaAliases.has(node.expression.expression.getText(sourceFile)) &&
+      node.expression.name.text === "dict"
+    ) {
+      const argument = node.arguments[0];
+      const entries =
+        argument && ts.isIdentifier(argument)
+          ? variableInitializers.get(argument.text)
+          : argument;
+      if (entries) {
+        const inspectEntry = (candidate) => {
+          if (
+            ts.isPropertyAssignment(candidate) &&
+            candidate.name.getText(sourceFile).replaceAll(/["']/g, "") ===
+              "tone"
+          ) {
+            add(
+              candidate,
+              "t.dict.tone",
+              "Entradas de status e estágio usam `context`; `tone` é apenas um alias temporário.",
+            );
+          }
+          ts.forEachChild(candidate, inspectEntry);
+        };
+        inspectEntry(entries);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return findings;
 }
 
 export function checkUiMigrations(file, text) {
-  const findings = []
-  const seen = new Set()
+  const findings = [];
+  const seen = new Set();
   const matchesToken = (line, token) => {
-    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    return new RegExp(`(^|[^A-Za-z0-9_-])${escaped}(?=$|[^A-Za-z0-9_-])`).test(line)
-  }
-  const extension = path.extname(file)
-  const source = stripComments(text)
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[^A-Za-z0-9_-])${escaped}(?=$|[^A-Za-z0-9_-])`).test(
+      line,
+    );
+  };
+  const extension = path.extname(file);
+  const source = stripComments(text);
   const addFinding = (token, replacement, line) => {
-    seen.add(token)
+    seen.add(token);
     findings.push({
-      rule: 'removed-ui-token',
-      level: 'error',
+      rule: "removed-ui-token",
+      level: "error",
       action: token,
       line,
       file,
       message: `token removido — ${replacement}.`,
-    })
-  }
+    });
+  };
   for (const [index, raw] of source.split(/\r?\n/).entries()) {
-    const line = raw.trim()
-    if (line === '') continue
+    const line = raw.trim();
+    if (line === "") continue;
     for (const [token, replacement] of REMOVED_UI_TOKENS) {
-      if (seen.has(token)) continue
-      const inStylesheet = extension === '.css' && matchesToken(line, token)
-      const inSvelteDirective = extension === '.svelte' && new RegExp(`\\bclass:${token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[=\\s]|$)`).test(line)
-      if (inStylesheet || inSvelteDirective) addFinding(token, replacement, index + 1)
+      if (seen.has(token)) continue;
+      const inStylesheet = extension === ".css" && matchesToken(line, token);
+      const inSvelteDirective =
+        extension === ".svelte" &&
+        new RegExp(
+          `\\bclass:${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?=[=\\s]|$)`,
+        ).test(line);
+      if (inStylesheet || inSvelteDirective)
+        addFinding(token, replacement, index + 1);
     }
   }
-  for (const { value, startLine, startIndex, endIndex } of quotedValues(source)) {
-    const beforeValue = source.slice(Math.max(0, startIndex - 500), startIndex)
-    const classAttribute = /\bclass(?:Name)?\s*=\s*\{?\s*$/.test(beforeValue)
-    const classExpression = /\bclass(?:Name)?\s*=\s*\{[^{}]*$/.test(beforeValue)
-    const utilityHelper = isInsideUtilityHelper(beforeValue)
-    const propertyKey = /^\s*:/.test(source.slice(endIndex + 1, endIndex + 12))
-    const classBinding = /\b(?:class(?:Name|Names)?|classes|\w+(?:Class|Classes))\s*=\s*[^;\n]*$/.test(beforeValue)
-    const objectProperty = /\b(?!aria(?:Label|Description)\b|label\b|title\b|description\b|text\b|message\b|note\b|content\b)[A-Za-z_$][\w$-]*\s*:\s*$/.test(beforeValue)
-    const classListCall = /\bclassList\.(?:add|remove|toggle|replace|contains)\s*\([^)]*$/.test(beforeValue)
-    const stylePropertyCall = /\b(?:style\.)?setProperty\s*\([^)]*$/.test(beforeValue)
-    const utilityContext = classAttribute || classExpression || utilityHelper || classBinding || objectProperty || classListCall
-    const utilities = value.trim().split(/\s+/).filter(Boolean)
+  for (const { value, startLine, startIndex, endIndex } of quotedValues(
+    source,
+  )) {
+    const beforeValue = source.slice(Math.max(0, startIndex - 500), startIndex);
+    const classAttribute = /\bclass(?:Name)?\s*=\s*\{?\s*$/.test(beforeValue);
+    const classExpression = /\bclass(?:Name)?\s*=\s*\{[^{}]*$/.test(
+      beforeValue,
+    );
+    const utilityHelper = isInsideUtilityHelper(beforeValue);
+    const propertyKey = /^\s*:/.test(source.slice(endIndex + 1, endIndex + 12));
+    const classBinding =
+      /\b(?:class(?:Name|Names)?|classes|\w+(?:Class|Classes))\s*=\s*[^;\n]*$/.test(
+        beforeValue,
+      );
+    const objectProperty =
+      /\b(?!aria(?:Label|Description)\b|label\b|title\b|description\b|text\b|message\b|note\b|content\b)[A-Za-z_$][\w$-]*\s*:\s*$/.test(
+        beforeValue,
+      );
+    const classListCall =
+      /\bclassList\.(?:add|remove|toggle|replace|contains)\s*\([^)]*$/.test(
+        beforeValue,
+      );
+    const stylePropertyCall = /\b(?:style\.)?setProperty\s*\([^)]*$/.test(
+      beforeValue,
+    );
+    const utilityContext =
+      classAttribute ||
+      classExpression ||
+      utilityHelper ||
+      classBinding ||
+      objectProperty ||
+      classListCall;
+    const utilities = value.trim().split(/\s+/).filter(Boolean);
     for (const [background, foreground] of UI_SURFACE_PAIRS) {
-      const pairKey = `surface:${background}`
-      const hasUtility = (expected) => utilities.some((utility) => {
-        const normalized = utility.replace(/^!/, '').replace(/!$/, '')
-        return normalized === expected || normalized.startsWith(`${expected}/`)
-      })
-      const hasBackground = hasUtility(background)
-      const hasForeground = hasUtility(foreground)
-      if (!seen.has(pairKey) && utilityContext && hasBackground && !hasForeground) {
-        seen.add(pairKey)
+      const pairKey = `surface:${background}`;
+      const hasUtility = (expected) =>
+        utilities.some((utility) => {
+          const normalized = utility.replace(/^!/, "").replace(/!$/, "");
+          return (
+            normalized === expected || normalized.startsWith(`${expected}/`)
+          );
+        });
+      const hasBackground = hasUtility(background);
+      const hasForeground = hasUtility(foreground);
+      if (
+        !seen.has(pairKey) &&
+        utilityContext &&
+        hasBackground &&
+        !hasForeground
+      ) {
+        seen.add(pairKey);
         findings.push({
-          rule: 'unpaired-ui-surface',
-          level: 'error',
+          rule: "unpaired-ui-surface",
+          level: "error",
           action: background,
           line: startLine,
           file,
           message: `superfície sem o foreground correspondente — use \`${background} ${foreground}\` no mesmo fragmento de classes.`,
-        })
+        });
       }
     }
     for (const [token, replacement] of REMOVED_UI_TOKENS) {
-      const usedAsUtility = matchesToken(value, token) && (
-        classAttribute || classExpression || utilityHelper || classBinding || objectProperty ||
-        (classListCall && !token.startsWith('--')) ||
-        (stylePropertyCall && token.startsWith('--')) ||
-        (propertyKey && token.startsWith('--')) ||
-        looksLikeUtilityValue(value, token, matchesToken)
-      )
-      if (seen.has(token) || !usedAsUtility) continue
-      const tokenIndex = value.indexOf(token)
-      const tokenLine = startLine + value.slice(0, tokenIndex).split('\n').length - 1
-      addFinding(token, replacement, tokenLine)
+      const usedAsUtility =
+        matchesToken(value, token) &&
+        (classAttribute ||
+          classExpression ||
+          utilityHelper ||
+          classBinding ||
+          objectProperty ||
+          (classListCall && !token.startsWith("--")) ||
+          (stylePropertyCall && token.startsWith("--")) ||
+          (propertyKey && token.startsWith("--")) ||
+          looksLikeUtilityValue(value, token, matchesToken));
+      if (seen.has(token) || !usedAsUtility) continue;
+      const tokenIndex = value.indexOf(token);
+      const tokenLine =
+        startLine + value.slice(0, tokenIndex).split("\n").length - 1;
+      addFinding(token, replacement, tokenLine);
     }
   }
-  return findings.sort((left, right) => left.line - right.line)
+  findings.push(...checkUiStructure(file, text));
+  findings.push(...checkUiSemantics(file, text));
+  return findings.sort((left, right) => left.line - right.line);
 }
 
-const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', 'coverage'])
-const UI_SKIP_DIRS = new Set([...SKIP_DIRS, '__tests__', '__fixtures__', 'fixtures', 'test', 'tests'])
-const UI_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.css', '.html', '.svelte', '.vue'])
+const SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  ".next",
+  "coverage",
+]);
+const UI_SKIP_DIRS = new Set([
+  ...SKIP_DIRS,
+  "__tests__",
+  "__fixtures__",
+  "fixtures",
+  "test",
+  "tests",
+]);
+const UI_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".css",
+  ".html",
+  ".svelte",
+  ".vue",
+]);
 
 export async function walkTsFiles(dir, acc = []) {
-  const root = canonicalProjectDirectory(dir)
-  const walk = (local = '.') => {
-    const entries = readProjectDirectory(root, local).entries
+  const root = canonicalProjectDirectory(dir);
+  const walk = (local = ".") => {
+    const entries = readProjectDirectory(root, local).entries;
     for (const e of entries) {
-      if (e.name.startsWith('.') && e.name !== '.') continue
-      if (SKIP_DIRS.has(e.name)) continue
-      const relative = path.join(local, e.name)
-      const full = path.join(root, relative)
+      if (e.name.startsWith(".") && e.name !== ".") continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const relative = path.join(local, e.name);
+      const full = path.join(root, relative);
       if (e.isSymbolicLink()) {
         // Dirent não revela se o link aponta para arquivo ou diretório. Ignorá-lo pela
         // extensão permitiria ocultar uma árvore de sources sob um nome de asset.
-        safeProjectPath(root, relative, { mustExist: true })
+        safeProjectPath(root, relative, { mustExist: true });
       }
       if (e.isDirectory()) {
-        safeProjectPath(root, relative, { mustExist: true })
-        walk(relative)
+        safeProjectPath(root, relative, { mustExist: true });
+        walk(relative);
       } else if (
-        (e.name.endsWith('.ts') || e.name.endsWith('.tsx')) &&
-        !e.name.endsWith('.d.ts') &&
-        !e.name.endsWith('.test.ts')
+        (e.name.endsWith(".ts") || e.name.endsWith(".tsx")) &&
+        !e.name.endsWith(".d.ts") &&
+        !e.name.endsWith(".test.ts")
       ) {
-        safeProjectPath(root, relative, { mustExist: true })
-        acc.push(full)
+        safeProjectPath(root, relative, { mustExist: true });
+        acc.push(full);
       }
     }
-  }
-  walk()
-  return acc
+  };
+  walk();
+  return acc;
 }
 
 async function walkUiFiles(dir, acc = []) {
-  const root = canonicalProjectDirectory(dir)
-  const walk = (local = '.') => {
-    const entries = readProjectDirectory(root, local).entries
+  const root = canonicalProjectDirectory(dir);
+  const walk = (local = ".") => {
+    const entries = readProjectDirectory(root, local).entries;
     for (const e of entries) {
-      if (e.name.startsWith('.')) continue
-      if (UI_SKIP_DIRS.has(e.name)) continue
-      const relative = path.join(local, e.name)
-      const full = path.join(root, relative)
+      if (e.name.startsWith(".")) continue;
+      if (UI_SKIP_DIRS.has(e.name)) continue;
+      const relative = path.join(local, e.name);
+      const full = path.join(root, relative);
       if (e.isSymbolicLink()) {
         // Um link com nome de asset ainda pode esconder um diretório com UI analisável.
-        safeProjectPath(root, relative, { mustExist: true })
+        safeProjectPath(root, relative, { mustExist: true });
       }
       if (e.isDirectory()) {
-        safeProjectPath(root, relative, { mustExist: true })
-        walk(relative)
-      } else if (UI_EXTENSIONS.has(path.extname(e.name)) && !/\.(?:test|spec)\.[^.]+$/.test(e.name)) {
-        safeProjectPath(root, relative, { mustExist: true })
-        acc.push(full)
+        safeProjectPath(root, relative, { mustExist: true });
+        walk(relative);
+      } else if (
+        UI_EXTENSIONS.has(path.extname(e.name)) &&
+        !/\.(?:test|spec)\.[^.]+$/.test(e.name)
+      ) {
+        safeProjectPath(root, relative, { mustExist: true });
+        acc.push(full);
       }
     }
-  }
-  walk()
-  return acc
+  };
+  walk();
+  return acc;
 }
 
 /** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
  *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
 export async function scanDir(rootDir) {
-  rootDir = canonicalProjectDirectory(rootDir)
-  const files = await walkTsFiles(rootDir)
-  const sources = []
+  rootDir = canonicalProjectDirectory(rootDir);
+  const files = await walkTsFiles(rootDir);
+  const sources = [];
   for (const file of files) {
-    const text = readProjectFile(rootDir, path.relative(rootDir, file)).content
-    if (!ACTION_MARKERS.some((m) => text.includes(m))) continue
-    sources.push({ file: path.relative(rootDir, file), text })
+    const text = readProjectFile(rootDir, path.relative(rootDir, file)).content;
+    if (!ACTION_MARKERS.some((m) => text.includes(m))) continue;
+    sources.push({ file: path.relative(rootDir, file), text });
   }
-  const checked = checkProject(sources)
-  const uiFindings = []
+  const checked = checkProject(sources);
+  const uiFindings = [];
   // UI pode morar em src/, app/, pages/ ou na raiz. O walk cobre o projeto inteiro e
   // exclui dependências, builds, testes e fixtures para não interpretar exemplos como uso.
   for (const file of await walkUiFiles(rootDir)) {
-    const text = readProjectFile(rootDir, path.relative(rootDir, file)).content
-    uiFindings.push(...checkUiMigrations(path.relative(rootDir, file), text))
+    const text = readProjectFile(rootDir, path.relative(rootDir, file)).content;
+    uiFindings.push(...checkUiMigrations(path.relative(rootDir, file), text));
   }
-  const hasMarker = safeProjectPath(rootDir, 'opus.json').exists
+  const hasMarker = safeProjectPath(rootDir, "opus.json").exists;
   return {
     files: files.length,
     actions: checked.actions,
     contracts: checked.contracts,
     findings: [...checked.findings, ...uiFindings],
     hasMarker,
-  }
+  };
 }
 
 /**
@@ -579,11 +1372,11 @@ export async function scanDir(rootDir) {
  */
 export function emptyScanVerdict({ hasMarker, contracts }) {
   if (hasMarker) {
-    return { ok: true, message: 'projeto opus sem actions — nada a checar.' }
+    return { ok: true, message: "projeto opus sem actions — nada a checar." };
   }
   const hint =
     contracts > 0
       ? `${contracts} contrato(s) (defineContract) sem bindAction no diretório — o check roda na raiz do app, onde os binds moram.`
-      : `procuro defineAction, defineContract e bindAction — confira o diretório.`
-  return { ok: false, message: hint }
+      : `procuro defineAction, defineContract e bindAction — confira o diretório.`;
+  return { ok: false, message: hint };
 }