@softize/opus 11.1.1 → 12.0.1

package/bin/lib/copy.mjs

@@ -0,0 +1,2202 @@
+/**
+ * Inventário semântico de copy dos contratos Opus.
+ *
+ * O Opus conhece o papel dos textos declarados em defineAction/defineContract;
+ * a @softize/base continua dona da política e da validação editorial. Este módulo
+ * apenas projeta o protocolo JSON v2 sem executar código do consumidor.
+ */
+
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  ensureProjectDirectory,
+  projectPathErrorMessage,
+  readProjectDirectory,
+  readProjectFile,
+  removeProjectFileIfUnchanged,
+  safeProjectPath,
+  writeProjectFileAtomically,
+} from '@softize/base/project-path'
+import ts from 'typescript'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+const PACKAGE = JSON.parse(readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+
+export const COPY_INVENTORY_SCHEMA_VERSION = 2
+export const DEFAULT_COPY_INVENTORY = '.base/copy-inventory.json'
+const COPY_COVERAGE_PROTOCOL = 'source-manifest-v1'
+
+const SOURCE_EXTENSIONS = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx'])
+const IGNORED_DIRECTORIES = new Set([
+  '.base',
+  '.agents',
+  '.claude',
+  '.git',
+  '.github',
+  '.githooks',
+  '.maestro',
+  '.next',
+  '.opus',
+  'build',
+  'coverage',
+  'dist',
+  'fixtures',
+  'node_modules',
+  'test',
+  'tests',
+  '__tests__',
+])
+const IGNORED_FILE = /(?:\.d|\.spec|\.test|\.stories)\.[cm]?[jt]sx?$/u
+// O Opus garante somente o namespace e o shape do identificador. O catálogo de regras,
+// inclusive adições futuras, pertence à versão instalada da Base.
+const COPY_RULE_ID = /^COPY\d{3}$/u
+const CONTRACT_MODULES = new Set(['@softize/opus', '@softize/opus/core'])
+const CONTRACT_FACTORIES = new Set(['defineAction', 'defineContract'])
+const ACTION_BINDING_KEYS = new Set(['authorize', 'background', 'emits', 'handler', 'idempotency', 'loads'])
+
+// Somente exports Opus cujo papel textual é estável por contrato do componente.
+// Tags nativas, wrappers locais e bibliotecas de terceiros ficam deliberadamente fora.
+const JSX_CHILD_ROLES = new Map([
+  ['ActionForm', 'message'],
+  ['ActionFormCard', 'message'],
+  ['ActionFormDialog', 'message'],
+  ['AlertDescription', 'message'],
+  ['AlertDialogAction', 'button'],
+  ['AlertDialogCancel', 'button'],
+  ['AlertDialogDescription', 'dialog-body'],
+  ['AlertDialogTitle', 'title'],
+  ['AlertTitle', 'title'],
+  ['Badge', 'badge'],
+  ['BreadcrumbLink', 'breadcrumb'],
+  ['BreadcrumbPage', 'breadcrumb'],
+  ['Button', 'button'],
+  ['CardDescription', 'description'],
+  ['CardTitle', 'title'],
+  ['CommandEmpty', 'empty-state'],
+  ['CommandItem', 'menu-item'],
+  ['DialogDescription', 'dialog-body'],
+  ['DialogTitle', 'title'],
+  ['DrawerDescription', 'dialog-body'],
+  ['DrawerTitle', 'title'],
+  ['EmptyDescription', 'empty-state'],
+  ['EmptyTitle', 'title'],
+  ['FieldDescription', 'helper-text'],
+  ['FieldError', 'error'],
+  ['FieldLabel', 'label'],
+  ['FieldLegend', 'heading'],
+  ['FieldTitle', 'heading'],
+  ['ItemDescription', 'description'],
+  ['ItemTitle', 'title'],
+  ['Label', 'label'],
+  ['MenuCheckboxItem', 'menu-item'],
+  ['MenuItem', 'menu-item'],
+  ['MenuLabel', 'label'],
+  ['MenuRadioItem', 'menu-item'],
+  ['PopoverDescription', 'description'],
+  ['PopoverTitle', 'title'],
+  ['TableCaption', 'description'],
+  ['TableHead', 'heading'],
+  ['TabsTrigger', 'tab'],
+])
+
+const OPTIONAL_CHILD_COMPONENTS = new Set(['ActionForm', 'ActionFormCard', 'ActionFormDialog'])
+const JSX_ACTION_CONSUMERS = new Set([
+  'ActionForm', 'ActionFormCard', 'ActionFormDialog', 'ActionList', 'ActionListDialog', 'ActionTrigger', 'ActionView',
+])
+const ACTION_HOOK_CONSUMERS = new Set([
+  'useAction', 'useFormAction', 'useListAction', 'useLookupAction', 'useTriggerAction', 'useViewAction',
+])
+const OPAQUE_SLOT_PROPS = new Map([
+  ['ActionForm', ['body', 'footer']],
+  ['ActionFormDialog', ['body', 'footer']],
+])
+
+const JSX_PROP_ROLES = new Map([
+  ['ActionForm', new Map([['submitLabel', 'button'], ['cancelLabel', 'button']])],
+  ['ActionFormCard', new Map([['title', 'title'], ['description', 'description'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
+  ['ActionFormDialog', new Map([['title', 'title'], ['description', 'dialog-body'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
+  // `itemLabel` identifica o dado alvo (por exemplo, `customer.name`); não é
+  // microcopy estável e, por isso, não pertence ao inventário editorial.
+  ['ActionTrigger', new Map([['label', 'button']])],
+  ['Alert', new Map([['title', 'title'], ['description', 'message']])],
+  ['CommandInput', new Map([['placeholder', 'placeholder']])],
+  ['DataState', new Map([['emptyText', 'empty-state'], ['errorText', 'error']])],
+  ['Input', new Map([['placeholder', 'placeholder']])],
+  ['InputGroupInput', new Map([['placeholder', 'placeholder']])],
+  ['InputGroupTextarea', new Map([['placeholder', 'placeholder']])],
+  ['Page', new Map([['title', 'title'], ['description', 'description']])],
+  ['Select', new Map([
+    ['placeholder', 'placeholder'],
+    ['searchPlaceholder', 'placeholder'],
+    ['emptyText', 'empty-state'],
+  ])],
+  ['Textarea', new Map([['placeholder', 'placeholder']])],
+])
+
+const JSX_OBJECT_PROP_ROLES = new Map([
+  ['ActionTrigger', new Map([
+    ['confirm', new Map([
+      ['title', 'title'],
+      ['description', 'dialog-body'],
+      ['actionLabel', 'button'],
+      ['cancelLabel', 'button'],
+    ])],
+  ])],
+])
+
+const JSX_ARRAY_PROP_ROLES = new Map([
+  ['Select', new Map([
+    ['options', new Map([
+      ['label', 'menu-item'],
+      ['hint', 'label'],
+      ['triggerLabel', 'label'],
+      ['group', 'heading'],
+      ['content', 'menu-item'],
+    ])],
+  ])],
+])
+
+// Prop de classe que alcança cada superfície textual. A lista acompanha a implementação
+// real dos componentes: `className` do ActionFormCard vai para o form, enquanto
+// `cardClassName` envolve o título; o menu do Select custom vive em portal e não herda a
+// classe do gatilho.
+const JSX_PROP_CLASS = new Map([
+  ['ActionForm', new Map([['submitLabel', 'className'], ['cancelLabel', 'className']])],
+  ['ActionFormCard', new Map([
+    ['title', 'cardClassName'], ['description', 'cardClassName'],
+    ['submitLabel', 'className'], ['cancelLabel', 'className'],
+  ])],
+  ['ActionTrigger', new Map([['label', 'className']])],
+  ['Alert', new Map([['title', 'className'], ['description', 'className']])],
+  ['CommandInput', new Map([['placeholder', 'className']])],
+  ['Input', new Map([['placeholder', 'className']])],
+  ['InputGroupInput', new Map([['placeholder', 'className']])],
+  ['InputGroupTextarea', new Map([['placeholder', 'className']])],
+  ['Page', new Map([['title', 'className'], ['description', 'className']])],
+  ['Select', new Map([['placeholder', 'className']])],
+  ['Textarea', new Map([['placeholder', 'className']])],
+])
+
+// Somente componentes cuja API repassa `style` até o nó visual dessa copy. Page,
+// Select e os wrappers de form não expõem style; inferir ali criaria uma garantia falsa.
+const JSX_PROP_STYLE = new Map([
+  ['ActionTrigger', new Map([['label', 'style']])],
+  ['Alert', new Map([['title', 'style'], ['description', 'style']])],
+  ['CommandInput', new Map([['placeholder', 'style']])],
+  ['Input', new Map([['placeholder', 'style']])],
+  ['InputGroupInput', new Map([['placeholder', 'style']])],
+  ['InputGroupTextarea', new Map([['placeholder', 'style']])],
+  ['Textarea', new Map([['placeholder', 'style']])],
+])
+
+const JSX_PORTAL_BOUNDARIES = new Set([
+  'AlertDialogContent', 'DialogContent', 'DrawerContent', 'MenuContent', 'MenuSubContent',
+  'PopoverContent', 'TooltipContent',
+])
+
+const digest = (content) => createHash('sha256').update(content).digest('hex')
+const portable = (value) => value.split(path.sep).join('/')
+
+function safeInventoryPath(root, inventory) {
+  try {
+    return safeProjectPath(root, inventory).path
+  } catch (error) {
+    throw new Error(`base.json: copy.inventory inseguro: ${projectPathErrorMessage(error)}`)
+  }
+}
+
+function uiModule(value) {
+  return value === '@softize/opus/ui' || value.startsWith('@softize/opus/ui/')
+}
+
+/**
+ * Cria apenas o binder/type-checker de um source virtual. Não resolve módulos nem carrega
+ * libs: precisamos da identidade lexical das declarações, não de executar ou tipar o app.
+ */
+function parseSource(file, sourceText) {
+  const virtual = path.resolve('/__opus_copy__', portable(file))
+  const parsed = ts.createSourceFile(virtual, sourceText, ts.ScriptTarget.Latest, true)
+  const host = {
+    getSourceFile: (name) => (name === virtual ? parsed : undefined),
+    getDefaultLibFileName: () => '',
+    writeFile: () => {},
+    getCurrentDirectory: () => path.dirname(virtual),
+    getDirectories: () => [],
+    fileExists: (name) => name === virtual,
+    readFile: (name) => (name === virtual ? sourceText : undefined),
+    getCanonicalFileName: (name) => name,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => '\n',
+  }
+  const program = ts.createProgram({
+    rootNames: [virtual],
+    options: { allowJs: true, jsx: ts.JsxEmit.Preserve, noLib: true, noResolve: true },
+    host,
+  })
+  return { sourceFile: program.getSourceFile(virtual) ?? parsed, checker: program.getTypeChecker() }
+}
+
+function importDeclaration(node) {
+  let current = node
+  while (current !== undefined && !ts.isSourceFile(current)) {
+    if (ts.isImportDeclaration(current)) return current
+    current = current.parent
+  }
+  return null
+}
+
+function importBinding(identifier, checker) {
+  const symbol = checker.getSymbolAtLocation(identifier)
+  const declaration = symbol?.declarations?.find(
+    (item) => ts.isImportSpecifier(item) || ts.isNamespaceImport(item) || ts.isImportClause(item),
+  )
+  if (declaration === undefined) return null
+  const statement = importDeclaration(declaration)
+  if (statement === null || !ts.isStringLiteral(statement.moduleSpecifier)) return null
+  if (
+    (ts.isImportSpecifier(declaration) && declaration.isTypeOnly) ||
+    (statement.importClause?.isTypeOnly ?? false)
+  ) return null
+  if (ts.isImportSpecifier(declaration)) {
+    return { kind: 'named', imported: declaration.propertyName?.text ?? declaration.name.text, module: statement.moduleSpecifier.text }
+  }
+  if (ts.isNamespaceImport(declaration)) {
+    return { kind: 'namespace', module: statement.moduleSpecifier.text }
+  }
+  return { kind: 'default', imported: 'default', module: statement.moduleSpecifier.text }
+}
+
+function propertyValue(candidate) {
+  return ts.isPropertyAssignment(candidate) ? candidate.initializer : candidate.name
+}
+
+function unwrap(node) {
+  let current = node
+  while (
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
+    ts.isParenthesizedExpression(current) ||
+    ts.isNonNullExpression(current)
+  ) {
+    current = current.expression
+  }
+  return current
+}
+
+function bindingSymbol(identifier, checker) {
+  return ts.isShorthandPropertyAssignment(identifier.parent)
+    ? checker.getShorthandAssignmentValueSymbol(identifier.parent)
+    : checker.getSymbolAtLocation(identifier)
+}
+
+function sameBinding(identifier, symbol, checker) {
+  const candidate = bindingSymbol(identifier, checker)
+  if (candidate === symbol) return true
+  if (candidate !== undefined && (candidate.flags & ts.SymbolFlags.Alias) !== 0) {
+    try {
+      return checker.getAliasedSymbol(candidate) === symbol
+    } catch {
+      return false
+    }
+  }
+  return false
+}
+
+function constInitializer(identifier, checker) {
+  const symbol = bindingSymbol(identifier, checker)
+  const declaration = symbol?.declarations?.find(
+    (item) =>
+      ts.isVariableDeclaration(item) &&
+      ts.isIdentifier(item.name) &&
+      item.initializer !== undefined &&
+      ts.isVariableDeclarationList(item.parent) &&
+      (item.parent.flags & ts.NodeFlags.Const) !== 0,
+  )
+  return declaration === undefined ? null : { symbol, declaration, initializer: declaration.initializer }
+}
+
+function assignmentTarget(node) {
+  const parent = node.parent
+  return (
+    (ts.isBinaryExpression(parent) && parent.left === node && ts.isAssignmentOperator(parent.operatorToken.kind)) ||
+    ((ts.isPrefixUnaryExpression(parent) || ts.isPostfixUnaryExpression(parent)) &&
+      [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(parent.operator)) ||
+    (ts.isDeleteExpression(parent) && parent.expression === node)
+  )
+}
+
+function containingVariableStatement(node) {
+  let current = node
+  while (current !== undefined && !ts.isSourceFile(current)) {
+    if (ts.isVariableStatement(current)) return current
+    current = current.parent
+  }
+  return null
+}
+
+function declarationIdentifier(node, symbol) {
+  return symbol.declarations?.some((declaration) => declaration === node || declaration.name === node) ?? false
+}
+
+function bindingNames(name, checker) {
+  const names = []
+  const collect = (current) => {
+    if (ts.isIdentifier(current)) names.push(current)
+    else for (const element of current.elements) if (!ts.isOmittedExpression(element)) collect(element.name)
+  }
+  collect(name)
+  return names
+    .map((identifier) => ({ name: identifier, symbol: bindingSymbol(identifier, checker) }))
+    .filter((item) => item.symbol !== undefined)
+}
+
+function transparentCarrier(node) {
+  let current = node
+  while (
+    ts.isParenthesizedExpression(current.parent) || ts.isAsExpression(current.parent) ||
+    ts.isSatisfiesExpression(current.parent) || ts.isNonNullExpression(current.parent) ||
+    ts.isTypeAssertionExpression(current.parent)
+  ) current = current.parent
+  return current
+}
+
+function importedMemberName(node, checker, modulePredicate) {
+  const value = resolveBinding(node, checker)
+  if (ts.isIdentifier(value)) {
+    const binding = importBinding(value, checker)
+    if (binding?.kind === 'named' && modulePredicate(binding.module)) return binding.imported
+    return destructuredNamespaceMember(value, checker, modulePredicate)
+  }
+  if (ts.isPropertyAccessExpression(value) || ts.isElementAccessExpression(value)) {
+    const owner = resolveBinding(value.expression, checker)
+    if (!ts.isIdentifier(owner)) return null
+    const binding = importBinding(owner, checker)
+    if (binding?.kind !== 'namespace' || !modulePredicate(binding.module)) return null
+    if (ts.isPropertyAccessExpression(value)) return value.name.text
+    return value.argumentExpression === undefined ? null : staticText(value.argumentExpression, checker)?.text ?? null
+  }
+  return null
+}
+
+function knownContractFactory(call, checker) {
+  const name = importedMemberName(call.expression, checker, (module) => CONTRACT_MODULES.has(module))
+  return name !== null && CONTRACT_FACTORIES.has(name)
+}
+
+function knownBindAction(call, checker) {
+  return importedMemberName(call.expression, checker, (module) => CONTRACT_MODULES.has(module)) === 'bindAction'
+}
+
+function safeBindActionBinding(call, checker) {
+  if (call.arguments.length < 2) return false
+  const binding = unwrap(call.arguments[1])
+  if (!ts.isObjectLiteralExpression(binding)) return false
+  return binding.properties.every((item) => {
+    if (
+      !ts.isPropertyAssignment(item) && !ts.isShorthandPropertyAssignment(item) &&
+      !ts.isMethodDeclaration(item)
+    ) return false
+    const name = item.name === undefined ? null : propertyName(item.name, item.getSourceFile(), checker)
+    return name !== null && ACTION_BINDING_KEYS.has(name)
+  })
+}
+
+function jsxOpeningFromAttribute(attribute) {
+  const opening = attribute.parent?.parent
+  return ts.isJsxOpeningElement(opening) || ts.isJsxSelfClosingElement(opening) ? opening : null
+}
+
+function knownJsxAggregateConsumer(expression, checker, mode) {
+  const jsx = expression.parent
+  if (!ts.isJsxExpression(jsx)) return false
+  if (ts.isJsxAttribute(jsx.parent)) {
+    const opening = jsxOpeningFromAttribute(jsx.parent)
+    if (opening === null) return false
+    const prop = jsx.parent.name.getText(expression.getSourceFile())
+    const component = importedMemberName(opening.tagName, checker, uiModule)
+    if (component === null) {
+      return ts.isIdentifier(opening.tagName) && /^[a-z]/u.test(opening.tagName.text) &&
+        mode === 'aggregate' && ['style', 'dangerouslySetInnerHTML'].includes(prop)
+    }
+    if (mode === 'factory-result' || mode === 'bound-result') {
+      return prop === 'action' && JSX_ACTION_CONSUMERS.has(component)
+    }
+    return (
+      JSX_PROP_ROLES.get(component)?.has(prop) === true ||
+      JSX_OBJECT_PROP_ROLES.get(component)?.has(prop) === true ||
+      JSX_ARRAY_PROP_ROLES.get(component)?.has(prop) === true ||
+      [...(JSX_PROP_CLASS.get(component)?.values() ?? [])].includes(prop) ||
+      [...(JSX_PROP_STYLE.get(component)?.values() ?? [])].includes(prop) ||
+      (JSX_CHILD_ROLES.has(component) && ['className', 'style'].includes(prop))
+    )
+  }
+  const element = jsx.parent
+  if (!ts.isJsxElement(element)) return false
+  const component = importedMemberName(element.openingElement.tagName, checker, uiModule)
+  if (component === null) {
+    return mode === 'aggregate' && ts.isIdentifier(element.openingElement.tagName) && /^[a-z]/u.test(element.openingElement.tagName.text)
+  }
+  return mode === 'aggregate' && JSX_CHILD_ROLES.has(component)
+}
+
+function exportedUse(node) {
+  const carrier = transparentCarrier(node)
+  return ts.isExportSpecifier(carrier.parent) || ts.isExportAssignment(carrier.parent)
+}
+
+function stableFactoryResult(call, checker, stack) {
+  return stableExpressionUse(call, checker, 'factory-result', stack)
+}
+
+function stableBoundResult(call, checker, stack) {
+  return stableExpressionUse(call, checker, 'bound-result', stack)
+}
+
+function stableComposition(node, checker, stack) {
+  let current = transparentCarrier(node)
+  for (;;) {
+    const parent = current.parent
+    if (
+      (ts.isPropertyAssignment(parent) && parent.initializer === current) ||
+      ts.isShorthandPropertyAssignment(parent) || ts.isSpreadAssignment(parent) ||
+      ts.isSpreadElement(parent) || ts.isArrayLiteralExpression(parent) ||
+      ts.isObjectLiteralExpression(parent)
+    ) {
+      current = parent
+      continue
+    }
+    return stableExpressionUse(current, checker, 'aggregate', stack)
+  }
+}
+
+function stableExpressionUse(node, checker, mode, stack) {
+  let carrier = transparentCarrier(node)
+  let sharedProperty = false
+  while (
+    (ts.isPropertyAccessExpression(carrier.parent) || ts.isElementAccessExpression(carrier.parent)) &&
+    carrier.parent.expression === carrier
+  ) {
+    sharedProperty = true
+    carrier = transparentCarrier(carrier.parent)
+  }
+  // defineContract retorna a própria entrada e bindAction faz clone raso. Qualquer
+  // subobjeto alcançado pelo resultado continua compartilhado com a copy declarada.
+  const consumerMode = sharedProperty && (mode === 'factory-result' || mode === 'bound-result')
+    ? 'aggregate'
+    : mode
+  const parent = carrier.parent
+
+  if (assignmentTarget(carrier)) return false
+  if (ts.isVariableDeclaration(parent) && parent.initializer === carrier) {
+    if (!ts.isVariableDeclarationList(parent.parent) || (parent.parent.flags & ts.NodeFlags.Const) === 0) return false
+    const aliases = bindingNames(parent.name, checker)
+    return aliases.length > 0 && aliases.every((alias) => stableReferences(alias, checker, consumerMode, stack))
+  }
+  if (
+    ts.isShorthandPropertyAssignment(parent) ||
+    (ts.isPropertyAssignment(parent) && parent.initializer === carrier) ||
+    ts.isSpreadAssignment(parent) || ts.isSpreadElement(parent) || ts.isArrayLiteralExpression(parent)
+  ) return consumerMode === 'aggregate' && stableComposition(carrier, checker, stack)
+  if (ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === carrier)) {
+    if (consumerMode === 'aggregate') return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
+    if (
+      consumerMode === 'factory-result' && parent.arguments[0] === carrier &&
+      knownBindAction(parent, checker) && safeBindActionBinding(parent, checker)
+    ) return stableBoundResult(parent, checker, stack)
+    const consumer = importedMemberName(parent.expression, checker, uiModule)
+    return (consumerMode === 'factory-result' || consumerMode === 'bound-result') &&
+      parent.arguments[0] === carrier && consumer !== null && ACTION_HOOK_CONSUMERS.has(consumer)
+  }
+  if (ts.isJsxExpression(parent)) return knownJsxAggregateConsumer(carrier, checker, consumerMode)
+  if (ts.isExpressionStatement(parent)) return true
+  if ((consumerMode === 'factory-result' || consumerMode === 'bound-result') && exportedUse(carrier)) return true
+  if ((ts.isTypeOfExpression(parent) || ts.isVoidExpression(parent)) && parent.expression === carrier) return true
+  return false
+}
+
+function stableReferences(binding, checker, mode, stack) {
+  if (stack.has(binding.symbol)) return false
+  const nextStack = new Set([...stack, binding.symbol])
+  const statement = containingVariableStatement(binding.name)
+  if (
+    mode === 'aggregate' &&
+    statement?.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)
+  ) return false
+
+  let stable = true
+  const visit = (node) => {
+    if (!stable) return
+    if (
+      ts.isIdentifier(node) && sameBinding(node, binding.symbol, checker) &&
+      !declarationIdentifier(node, binding.symbol)
+    ) stable = stableExpressionUse(node, checker, mode, nextStack)
+    ts.forEachChild(node, visit)
+  }
+  visit(binding.name.getSourceFile())
+  return stable
+}
+
+/**
+ * Objetos e arrays `const` continuam mutáveis. A extração só faz fold quando cada uso
+ * está numa allowlist observável: composição `const` igualmente estável, factory Opus
+ * cujo resultado não sofre mutação/escape, ou prop/children conhecidos de DOM/Opus.
+ */
+function stableAggregateBinding(binding, checker, stack = new Set()) {
+  const initial = unwrap(binding.initializer)
+  if (!ts.isObjectLiteralExpression(initial) && !ts.isArrayLiteralExpression(initial)) return true
+  return stableReferences({ name: binding.declaration.name, symbol: binding.symbol }, checker, 'aggregate', stack)
+}
+
+/** Avalia somente bindings `const` da declaração lexical correta; nunca executa o source. */
+function resolveBinding(node, checker, seen = new Set()) {
+  const value = unwrap(node)
+  if (ts.isIdentifier(value)) {
+    const binding = constInitializer(value, checker)
+    if (binding === null || seen.has(binding.symbol) || !stableAggregateBinding(binding, checker)) return value
+    return resolveBinding(binding.initializer, checker, new Set([...seen, binding.symbol]))
+  }
+  if (ts.isPropertyAccessExpression(value) || ts.isElementAccessExpression(value)) {
+    const owner = resolveBinding(value.expression, checker, seen)
+    const key = ts.isPropertyAccessExpression(value)
+      ? value.name.text
+      : value.argumentExpression === undefined ? null : staticText(value.argumentExpression, checker)?.text ?? null
+    if (key === null) return value
+    if (ts.isObjectLiteralExpression(owner)) {
+      const resolved = property(owner, key, value.getSourceFile(), checker)
+      if (resolved.opaque === undefined && resolved.candidate !== undefined) {
+        return resolveBinding(propertyValue(resolved.candidate), checker, seen)
+      }
+    }
+    if (ts.isArrayLiteralExpression(owner) && /^\d+$/u.test(key)) {
+      const target = Number(key)
+      const flattened = []
+      for (const element of owner.elements) {
+        if (!ts.isSpreadElement(element)) flattened.push(element)
+        else {
+          const spread = resolveBinding(element.expression, checker, seen)
+          if (!ts.isArrayLiteralExpression(spread)) return value
+          flattened.push(...spread.elements)
+        }
+      }
+      if (target < flattened.length && !ts.isSpreadElement(flattened[target])) {
+        return resolveBinding(flattened[target], checker, seen)
+      }
+    }
+  }
+  return value
+}
+
+function staticText(node, checker) {
+  const value = resolveBinding(node, checker)
+  if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) {
+    return { text: value.text, node: value }
+  }
+  if (
+    ts.isBinaryExpression(value) &&
+    value.operatorToken.kind === ts.SyntaxKind.PlusToken
+  ) {
+    const left = staticText(value.left, checker)
+    const right = staticText(value.right, checker)
+    if (left !== null && right !== null) return { text: left.text + right.text, node: value }
+  }
+  return null
+}
+
+const JSX_ENTITY_CACHE = new Map()
+
+/**
+ * Usa o próprio transform JSX do TypeScript como tabela de entidades. Assim a extração
+ * acompanha exatamente o conjunto completo aceito pelo parser/emit instalado, sem uma
+ * allowlist parcial que possa divergir do texto entregue ao React.
+ */
+function namedJsxEntity(entity) {
+  if (JSX_ENTITY_CACHE.has(entity)) return JSX_ENTITY_CACHE.get(entity)
+  const output = ts.transpileModule(`const __softize = <i>${entity}</i>`, {
+    compilerOptions: { jsx: ts.JsxEmit.React, target: ts.ScriptTarget.ES2022 },
+  }).outputText
+  const emitted = ts.createSourceFile('__softize-entity.js', output, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS)
+  let decoded = null
+  const visit = (node) => {
+    if (
+      decoded === null &&
+      ts.isCallExpression(node) &&
+      node.arguments.length >= 3 &&
+      ts.isStringLiteral(node.arguments[2])
+    ) decoded = node.arguments[2].text
+    ts.forEachChild(node, visit)
+  }
+  visit(emitted)
+  const result = decoded !== null && decoded !== entity ? decoded : null
+  JSX_ENTITY_CACHE.set(entity, result)
+  return result
+}
+
+/**
+ * Decodifica somente entidades completas que o JSX instalado realmente transforma.
+ * Entidade desconhecida ou código Unicode inválido é opaco: inventariar o source cru
+ * como se fosse a copy renderizada criaria uma garantia falsa.
+ */
+function decodeJsxEntities(text) {
+  let valid = true
+  const decoded = text.replace(/&(?:#([^;\s<>]+)|([a-z][a-z0-9]*));/giu, (entity, numeric) => {
+    if (numeric !== undefined) {
+      const hexadecimal = /^[xX][0-9a-f]+$/u.test(numeric)
+      const decimal = /^\d+$/u.test(numeric)
+      const point = hexadecimal
+        ? Number.parseInt(numeric.slice(1), 16)
+        : decimal ? Number.parseInt(numeric, 10) : Number.NaN
+      if (Number.isInteger(point) && point > 0 && point <= 0x10ffff && !(point >= 0xd800 && point <= 0xdfff)) {
+        return String.fromCodePoint(point)
+      }
+      valid = false
+      return entity
+    }
+    const value = namedJsxEntity(entity)
+    if (value !== null) return value
+    valid = false
+    return entity
+  })
+  for (const match of text.matchAll(/&(#(?:[xX][0-9a-fA-F]+|\d+)|[A-Za-z][A-Za-z0-9]*)(?![A-Za-z0-9;])/gu)) {
+    if (match[1].startsWith('#') || namedJsxEntity(`&${match[1]};`) !== null) valid = false
+  }
+  return valid ? decoded : null
+}
+
+function constVariableDeclaration(node) {
+  if (!ts.isVariableDeclaration(node) || node.initializer === undefined) return false
+  return ts.isVariableDeclarationList(node.parent) && (node.parent.flags & ts.NodeFlags.Const) !== 0
+}
+
+/** Resolve `const { Button: B } = Opus` sem aceitar destructuring mutável ou homônimo local. */
+function destructuredNamespaceMember(identifier, checker, modulePredicate) {
+  const symbol = checker.getSymbolAtLocation(identifier)
+  const declaration = symbol?.declarations?.find(
+    (item) => ts.isBindingElement(item) && ts.isIdentifier(item.name) && item.name.text === identifier.text,
+  )
+  if (
+    declaration === undefined ||
+    declaration.dotDotDotToken !== undefined ||
+    !ts.isObjectBindingPattern(declaration.parent) ||
+    !constVariableDeclaration(declaration.parent.parent)
+  ) return null
+
+  const memberNode = declaration.propertyName ?? declaration.name
+  const member = propertyName(memberNode, identifier.getSourceFile(), checker)
+  if (member === null) return null
+  const owner = resolveBinding(declaration.parent.parent.initializer, checker)
+  if (!ts.isIdentifier(owner)) return null
+  const binding = importBinding(owner, checker)
+  return binding?.kind === 'namespace' && modulePredicate(binding.module) ? member : null
+}
+
+function propertyName(node, sourceFile, checker) {
+  if (ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node)) return node.text
+  if (ts.isComputedPropertyName(node)) return staticText(node.expression, checker)?.text ?? null
+  void sourceFile
+  return null
+}
+
+/**
+ * Resolve uma chave conforme a ordem real do objeto. Um spread/computed opaco só deixa
+ * de importar quando uma propriedade explícita posterior prova o valor final da chave.
+ */
+function property(object, name, sourceFile, checker, seen = new Set()) {
+  if (seen.has(object)) return { candidate: undefined, opaque: object }
+  const nextSeen = new Set([...seen, object])
+  let candidate
+  let opaque
+  for (const item of object.properties) {
+    if (ts.isSpreadAssignment(item)) {
+      const spread = resolveBinding(item.expression, checker)
+      if (!ts.isObjectLiteralExpression(spread)) {
+        candidate = undefined
+        opaque = item
+        continue
+      }
+      const nested = property(spread, name, sourceFile, checker, nextSeen)
+      if (nested.opaque !== undefined) {
+        candidate = undefined
+        opaque = nested.opaque
+      } else if (nested.candidate !== undefined) {
+        candidate = nested.candidate
+        opaque = undefined
+      }
+      continue
+    }
+    const itemName = item.name === undefined ? null : propertyName(item.name, sourceFile, checker)
+    if (itemName === null) {
+      candidate = undefined
+      opaque = item
+      continue
+    }
+    if (itemName !== name) continue
+    if (ts.isPropertyAssignment(item) || ts.isShorthandPropertyAssignment(item)) {
+      candidate = item
+      opaque = undefined
+    } else {
+      candidate = undefined
+      opaque = item
+    }
+  }
+  return { candidate, opaque }
+}
+
+/** Enumera propriedades nomeadas; spreads estáticos são mesclados na ordem do runtime. */
+function properties(object, sourceFile, checker, seen = new Set()) {
+  if (seen.has(object)) {
+    return {
+      items: new Map(),
+      opaque: [object],
+      unknownOpaque: [object],
+      namedOpaque: new Map(),
+    }
+  }
+  const nextSeen = new Set([...seen, object])
+  const items = new Map()
+  const unknownOpaque = []
+  const namedOpaque = new Map()
+  for (const item of object.properties) {
+    if (ts.isSpreadAssignment(item)) {
+      const spread = resolveBinding(item.expression, checker)
+      if (!ts.isObjectLiteralExpression(spread)) {
+        // Um spread opaco pode acrescentar qualquer chave; nenhuma lista finita de
+        // overrides posteriores prova que o mapa completo ficou conhecido.
+        unknownOpaque.push(item)
+        continue
+      }
+      const nested = properties(spread, sourceFile, checker, nextSeen)
+      unknownOpaque.push(...nested.unknownOpaque)
+      for (const [name, candidate] of nested.items) {
+        items.set(name, candidate)
+        namedOpaque.delete(name)
+      }
+      for (const [name, opaque] of nested.namedOpaque) {
+        items.delete(name)
+        namedOpaque.set(name, opaque)
+      }
+      continue
+    }
+    const name = item.name === undefined ? null : propertyName(item.name, sourceFile, checker)
+    if (name === null) {
+      unknownOpaque.push(item)
+      continue
+    }
+    if (ts.isPropertyAssignment(item) || ts.isShorthandPropertyAssignment(item)) {
+      items.set(name, item)
+      namedOpaque.delete(name)
+    } else {
+      items.delete(name)
+      namedOpaque.set(name, item)
+    }
+  }
+  return {
+    items,
+    opaque: [...unknownOpaque, ...namedOpaque.values()],
+    unknownOpaque,
+    namedOpaque,
+  }
+}
+
+function i18nText(node, sourceFile, checker) {
+  const value = resolveBinding(node, checker)
+  const direct = staticText(value, checker)
+  if (direct !== null) return direct
+  if (!ts.isObjectLiteralExpression(value)) return null
+  const fallback = property(value, 'default', sourceFile, checker)
+  return fallback.opaque !== undefined || fallback.candidate === undefined
+    ? null
+    : staticText(propertyValue(fallback.candidate), checker)
+}
+
+function objects(node, checker, seen = new Set()) {
+  const value = resolveBinding(node, checker)
+  if (ts.isObjectLiteralExpression(value)) return { values: [value], opaque: [] }
+  if (ts.isArrayLiteralExpression(value)) {
+    if (seen.has(value)) return { values: [], opaque: [value] }
+    const values = []
+    const opaque = []
+    const nextSeen = new Set([...seen, value])
+    for (const element of value.elements) {
+      if (ts.isSpreadElement(element)) {
+        const nested = objects(element.expression, checker, nextSeen)
+        values.push(...nested.values)
+        opaque.push(...nested.opaque)
+        continue
+      }
+      const item = resolveBinding(element, checker)
+      if (ts.isObjectLiteralExpression(item)) values.push(item)
+      else opaque.push(element)
+    }
+    return { values, opaque }
+  }
+  return { values: [], opaque: [node] }
+}
+
+function lineOf(sourceFile, node) {
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1
+}
+
+function diagnostic(file, sourceFile, node, field) {
+  return {
+    source: file,
+    line: lineOf(sourceFile, node),
+    message:
+      `não foi possível extrair \`${field}\` estaticamente; use texto literal, concatenação ` +
+      'de literais, constante local ou I18nRef com `default` literal.',
+  }
+}
+
+/**
+ * Extrai as superfícies humanas de um source isolado.
+ *
+ * O retorno distingue arquivo sem contrato de contrato sem copy. Essa diferença é
+ * necessária para hashear todo contrato e detectar a adição posterior de um texto.
+ */
+export function extractCopyFromSource(file, sourceText) {
+  const { sourceFile, checker } = parseSource(file, sourceText)
+  const entries = []
+  const diagnostics = []
+  let hasContract = false
+  const hasUiImport = sourceFile.statements.some(
+    (statement) =>
+      ts.isImportDeclaration(statement) &&
+      ts.isStringLiteral(statement.moduleSpecifier) &&
+      uiModule(statement.moduleSpecifier.text) &&
+      statement.importClause !== undefined &&
+      !statement.importClause.isTypeOnly,
+  )
+
+  const add = (node, role, field) => {
+    const extracted = i18nText(node, sourceFile, checker)
+    if (extracted === null) diagnostics.push(diagnostic(file, sourceFile, node, field))
+    else {
+      const entry = { source: file, line: lineOf(sourceFile, extracted.node), role, text: extracted.text }
+      entries.push(entry)
+      return entry
+    }
+    return null
+  }
+
+  const addProperty = (object, name, role, prefix = '') => {
+    const resolved = property(object, name, sourceFile, checker)
+    if (resolved.opaque !== undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, resolved.opaque, `${prefix}${name}`))
+    } else if (resolved.candidate !== undefined) {
+      add(propertyValue(resolved.candidate), role, `${prefix}${name}`)
+    }
+  }
+
+  const nestedObject = (object, name, visitor, prefix = '') => {
+    const resolved = property(object, name, sourceFile, checker)
+    if (resolved.opaque !== undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, resolved.opaque, `${prefix}${name}`))
+      return
+    }
+    if (resolved.candidate === undefined) return
+    const candidateValue = propertyValue(resolved.candidate)
+    const value = resolveBinding(candidateValue, checker)
+    if (ts.isObjectLiteralExpression(value)) {
+      visitor(value, `${prefix}${name}.`)
+      return
+    }
+    if (ts.isArrayLiteralExpression(value)) {
+      const listed = objects(value, checker)
+      for (const [index, item] of listed.values.entries()) visitor(item, `${prefix}${name}[${index}].`)
+      for (const item of listed.opaque) diagnostics.push(diagnostic(file, sourceFile, item, `${prefix}${name}`))
+      return
+    }
+    diagnostics.push(diagnostic(file, sourceFile, candidateValue, `${prefix}${name}`))
+  }
+
+  const namedObjects = (object, name, visitor) => {
+    nestedObject(object, name, (container, prefix) => {
+      const listed = properties(container, sourceFile, checker)
+      for (const item of listed.opaque) diagnostics.push(diagnostic(file, sourceFile, item, prefix.slice(0, -1)))
+      for (const [itemName, item] of listed.items) {
+        const listedValues = objects(propertyValue(item), checker)
+        for (const opaque of listedValues.opaque) diagnostics.push(diagnostic(file, sourceFile, opaque, `${prefix}${itemName}`))
+        if (listedValues.values.length === 0 && listedValues.opaque.length === 0) {
+          diagnostics.push(diagnostic(file, sourceFile, propertyValue(item), `${prefix}${itemName}`))
+        }
+        for (const value of listedValues.values) visitor(value, `${prefix}${itemName}.`)
+      }
+    })
+  }
+
+  const optionItems = (object, prefix) => {
+    const kind = property(object, 'kind', sourceFile, checker)
+    if (kind.opaque !== undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, kind.opaque, `${prefix}kind`))
+      return
+    }
+    if (kind.candidate === undefined) return
+    const kindText = staticText(propertyValue(kind.candidate), checker)?.text
+    if (kindText === undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, propertyValue(kind.candidate), `${prefix}kind`))
+      return
+    }
+    if (kindText !== 'static') return
+    nestedObject(object, 'items', (item, itemPrefix) => addProperty(item, 'label', 'menu-item', itemPrefix), prefix)
+  }
+
+  const field = (object, prefix) => {
+    addProperty(object, 'label', 'label', prefix)
+    addProperty(object, 'placeholder', 'placeholder', prefix)
+    addProperty(object, 'hint', 'helper-text', prefix)
+    addProperty(object, 'help', 'helper-text', prefix)
+    nestedObject(object, 'options', optionItems, prefix)
+  }
+
+  const filter = (object, prefix) => {
+    addProperty(object, 'label', 'label', prefix)
+    addProperty(object, 'placeholder', 'placeholder', prefix)
+    nestedObject(object, 'options', optionItems, prefix)
+  }
+
+  function extractContract(object) {
+    addProperty(object, 'label', 'button')
+    addProperty(object, 'title', 'title')
+    addProperty(object, 'summary', 'description')
+    addProperty(object, 'description', 'description')
+
+    nestedObject(object, 'messages', (messages, prefix) => {
+      addProperty(messages, 'success', 'success', prefix)
+      addProperty(messages, 'error', 'error', prefix)
+      addProperty(messages, 'confirmation', 'message', prefix)
+    })
+    nestedObject(object, 'confirm', (confirm, prefix) => {
+      addProperty(confirm, 'title', 'title', prefix)
+      addProperty(confirm, 'message', 'dialog-body', prefix)
+      addProperty(confirm, 'confirmLabel', 'button', prefix)
+      addProperty(confirm, 'cancelLabel', 'button', prefix)
+    })
+    namedObjects(object, 'fields', field)
+    namedObjects(object, 'filters', filter)
+    nestedObject(object, 'columns', (column, prefix) => addProperty(column, 'label', 'heading', prefix))
+    nestedObject(object, 'periods', (period, prefix) => addProperty(period, 'label', 'tab', prefix))
+    nestedObject(object, 'text', (text, prefix) => addProperty(text, 'placeholder', 'placeholder', prefix))
+    namedObjects(object, 'expand', (expand, prefix) => addProperty(expand, 'description', 'description', prefix))
+    nestedObject(object, 'examples', (example, prefix) => {
+      addProperty(example, 'name', 'title', prefix)
+      addProperty(example, 'description', 'description', prefix)
+    })
+    nestedObject(object, 'errors', (error, prefix) => addProperty(error, 'description', 'error', prefix))
+  }
+
+  function importedMember(node, modulePredicate) {
+    return importedMemberName(node, checker, modulePredicate)
+  }
+
+  function contractFactory(expression) {
+    const name = importedMember(expression, (module) => CONTRACT_MODULES.has(module))
+    return name !== null && CONTRACT_FACTORIES.has(name) ? name : null
+  }
+
+  function opusComponent(tagName) {
+    return importedMember(tagName, uiModule)
+  }
+
+  function attribute(attributes, name) {
+    let candidate
+    let opaque
+    for (const item of attributes.properties) {
+      if (ts.isJsxAttribute(item)) {
+        if (item.name.getText(sourceFile) === name) {
+          candidate = { kind: 'jsx', item }
+          opaque = undefined
+        }
+        continue
+      }
+      const spread = resolveBinding(item.expression, checker)
+      if (!ts.isObjectLiteralExpression(spread)) {
+        candidate = undefined
+        opaque = item
+        continue
+      }
+      const nested = property(spread, name, sourceFile, checker)
+      if (nested.opaque !== undefined) {
+        candidate = undefined
+        opaque = nested.opaque
+      } else if (nested.candidate !== undefined) {
+        candidate = { kind: 'value', item: propertyValue(nested.candidate) }
+        opaque = undefined
+      }
+    }
+    return { candidate, opaque }
+  }
+
+  function attributeValue(resolved) {
+    if (resolved.opaque !== undefined || resolved.candidate === undefined) return null
+    if (resolved.candidate.kind === 'value') return resolved.candidate.item
+    const item = resolved.candidate.item
+    if (item.initializer === undefined) return null
+    if (ts.isStringLiteral(item.initializer)) return item.initializer
+    if (ts.isJsxExpression(item.initializer) && item.initializer.expression !== undefined) {
+      return item.initializer.expression
+    }
+    return null
+  }
+
+  function attributeText(resolved) {
+    if (
+      resolved.opaque === undefined &&
+      resolved.candidate?.kind === 'jsx' &&
+      ts.isStringLiteral(resolved.candidate.item.initializer)
+    ) {
+      const text = decodeJsxEntities(resolved.candidate.item.initializer.text)
+      if (text === null) return null
+      return {
+        text,
+        node: resolved.candidate.item.initializer,
+      }
+    }
+    const value = attributeValue(resolved)
+    return value === null ? null : staticText(value, checker)
+  }
+
+  function attributeBoolean(resolved) {
+    if (resolved.opaque !== undefined || resolved.candidate === undefined) return null
+    if (resolved.candidate.kind === 'jsx' && resolved.candidate.item.initializer === undefined) return true
+    const raw = attributeValue(resolved)
+    if (raw === null) return null
+    const value = resolveBinding(raw, checker)
+    if (value.kind === ts.SyntaxKind.TrueKeyword) return true
+    if (value.kind === ts.SyntaxKind.FalseKeyword) return false
+    const text = staticText(value, checker)?.text
+    return text === 'true' ? true : text === 'false' ? false : null
+  }
+
+  const transformDiagnostics = new Set()
+
+  function transformDiagnostic(node, field) {
+    const key = `${node.pos}:${node.end}:${field}`
+    if (transformDiagnostics.has(key)) return
+    transformDiagnostics.add(key)
+    diagnostics.push(diagnostic(file, sourceFile, node, field))
+  }
+
+  function tailwindTransform(token) {
+    let normalized = token
+    let important = false
+    if (normalized.startsWith('!')) {
+      important = true
+      normalized = normalized.slice(1)
+    }
+    let bracketDepth = 0
+    let separator = -1
+    for (let index = 0; index < normalized.length; index += 1) {
+      if (normalized[index] === '[') bracketDepth += 1
+      else if (normalized[index] === ']') bracketDepth = Math.max(0, bracketDepth - 1)
+      else if (normalized[index] === ':' && bracketDepth === 0) separator = index
+    }
+    let utility = normalized.slice(separator + 1)
+    if (utility.startsWith('!')) {
+      important = true
+      utility = utility.slice(1)
+    }
+    if (utility.endsWith('!')) {
+      important = true
+      utility = utility.slice(0, -1)
+    }
+    if (utility === 'uppercase' || utility === '[text-transform:uppercase]') {
+      return { kind: 'uppercase', conditional: separator !== -1, important }
+    }
+    if (
+      utility === 'normal-case' ||
+      utility === 'lowercase' ||
+      utility === 'capitalize' ||
+      /^\[text-transform:(?:none|lowercase|capitalize)\]$/u.test(utility)
+    ) return { kind: 'other', conditional: separator !== -1, important }
+    return null
+  }
+
+  function classTransformState(attributes, name, field, diagnose = true) {
+    if (name === null) return { opaque: false, transforms: [] }
+    const resolved = attribute(attributes, name)
+    if (resolved.opaque !== undefined) {
+      if (diagnose) transformDiagnostic(resolved.opaque, field)
+      return { opaque: true, transforms: [] }
+    }
+    if (resolved.candidate === undefined) return { opaque: false, transforms: [] }
+    const text = attributeText(resolved)
+    if (text === null) {
+      if (diagnose) transformDiagnostic(attributeValue(resolved) ?? attributes, field)
+      return { opaque: true, transforms: [] }
+    }
+    return {
+      opaque: false,
+      transforms: text.text.split(/\s+/u).filter(Boolean).map(tailwindTransform).filter((item) => item !== null),
+    }
+  }
+
+  function styleTransformState(attributes, name, field, diagnose = true) {
+    if (name === null) return { kind: 'absent' }
+    const style = attribute(attributes, name)
+    if (style.opaque !== undefined) {
+      if (diagnose) transformDiagnostic(style.opaque, field)
+      return { kind: 'opaque' }
+    }
+    if (style.candidate === undefined) return { kind: 'absent' }
+    const raw = attributeValue(style)
+    const object = raw === null ? null : resolveBinding(raw, checker)
+    if (!ts.isObjectLiteralExpression(object)) {
+      if (diagnose) transformDiagnostic(raw ?? attributes, field)
+      return { kind: 'opaque' }
+    }
+    const textTransform = property(object, 'textTransform', sourceFile, checker)
+    if (textTransform.opaque !== undefined) {
+      if (diagnose) transformDiagnostic(textTransform.opaque, `${field}.textTransform`)
+      return { kind: 'opaque' }
+    }
+    if (textTransform.candidate === undefined) return { kind: 'absent' }
+    const value = staticText(propertyValue(textTransform.candidate), checker)?.text
+    if (value === 'uppercase') return { kind: 'uppercase' }
+    if (['none', 'lowercase', 'capitalize'].includes(value)) return { kind: 'other' }
+    if (diagnose) transformDiagnostic(propertyValue(textTransform.candidate), `${field}.textTransform`)
+    return { kind: 'opaque' }
+  }
+
+  function transformFacts(transforms) {
+    return {
+      importantUppercase: transforms.some((item) => item.important && item.kind === 'uppercase'),
+      importantOtherAlways: transforms.some((item) => item.important && item.kind === 'other' && !item.conditional),
+      uppercase: transforms.some((item) => item.kind === 'uppercase'),
+      otherAlways: transforms.some((item) => item.kind === 'other' && !item.conditional),
+    }
+  }
+
+  /** Retorna se a superfície pode aparecer em uppercase em qualquer estado/viewport. */
+  function visualTransform(attributes, className, styleName, inheritedUppercase, field) {
+    const classes = classTransformState(attributes, className, `${field}.${className}`)
+    const facts = transformFacts(classes.transforms)
+    const style = styleTransformState(attributes, styleName, `${field}.${styleName}`)
+
+    // Utility `!important` vence style inline normal. Se a classe é dinâmica, ela
+    // também pode conter important; portanto style conhecido não a neutraliza.
+    if (classes.opaque) return { opaque: true, uppercase: false }
+    if (facts.importantUppercase) return { opaque: false, uppercase: true }
+    if (facts.importantOtherAlways) return { opaque: false, uppercase: false }
+    if (style.kind === 'opaque') return { opaque: true, uppercase: false }
+    if (style.kind === 'uppercase') return { opaque: false, uppercase: true }
+    if (style.kind === 'other') return { opaque: false, uppercase: false }
+    if (facts.uppercase) return { opaque: false, uppercase: true }
+    if (facts.otherAlways) return { opaque: false, uppercase: false }
+    return { opaque: false, uppercase: inheritedUppercase }
+  }
+
+  function localTransformOverridesInheritance(attributes, className, styleName) {
+    const classes = classTransformState(attributes, className, '', false)
+    if (classes.opaque) return false
+    const facts = transformFacts(classes.transforms)
+    if (facts.importantUppercase || facts.importantOtherAlways) return true
+    const style = styleTransformState(attributes, styleName, '', false)
+    if (style.kind === 'uppercase' || style.kind === 'other') return true
+    if (style.kind === 'opaque') return false
+    return classes.transforms.some((item) => !item.conditional)
+  }
+
+  function intrinsicElement(tagName) {
+    return ts.isIdentifier(tagName) && /^[a-z]/u.test(tagName.text)
+  }
+
+  function transformableElement(opening, component) {
+    if (component !== null) return true
+    return intrinsicElement(opening.tagName)
+  }
+
+  function ancestorTransform(element) {
+    const ancestors = []
+    for (let parent = element.parent; parent !== undefined; parent = parent.parent) {
+      if (ts.isJsxElement(parent)) ancestors.push(parent.openingElement)
+    }
+    let result = { opaque: false, uppercase: false }
+    for (const opening of ancestors.reverse()) {
+      const component = opusComponent(opening.tagName)
+      if (component !== null && JSX_PORTAL_BOUNDARIES.has(component)) result = { opaque: false, uppercase: false }
+      if (component === 'ActionFormDialog' || component === 'Select' || component === 'ActionTrigger') continue
+      if (component === 'ActionFormCard') {
+        result = visualTransform(opening.attributes, 'cardClassName', null, result.uppercase, '<ActionFormCard>')
+        if (result.opaque) return result
+        result = visualTransform(opening.attributes, 'className', null, result.uppercase, '<ActionFormCard>')
+      } else if (transformableElement(opening, component)) {
+        const acceptsStyle = component === null || !['ActionForm', 'Page'].includes(component)
+        result = visualTransform(opening.attributes, 'className', acceptsStyle ? 'style' : null, result.uppercase, `<${component ?? opening.tagName.getText(sourceFile)}>`)
+      }
+      if (result.opaque) return result
+    }
+    return result
+  }
+
+  function noRenderedValue(node) {
+    const value = resolveBinding(node, checker)
+    if (
+      value.kind === ts.SyntaxKind.NullKeyword ||
+      value.kind === ts.SyntaxKind.TrueKeyword ||
+      value.kind === ts.SyntaxKind.FalseKeyword ||
+      ts.isVoidExpression(value)
+    ) return true
+    if (ts.isIdentifier(value) && value.text === 'undefined') {
+      return checker.getSymbolAtLocation(value) === undefined
+    }
+    return false
+  }
+
+  function numericLiteral(node) {
+    if (ts.isNumericLiteral(node)) return { value: Number(node.text), text: node.text }
+    if (
+      ts.isPrefixUnaryExpression(node) &&
+      (node.operator === ts.SyntaxKind.PlusToken || node.operator === ts.SyntaxKind.MinusToken) &&
+      ts.isNumericLiteral(node.operand)
+    ) {
+      const value = Number(node.operand.text) * (node.operator === ts.SyntaxKind.MinusToken ? -1 : 1)
+      return { value, text: Object.is(value, -0) ? '0' : String(value) }
+    }
+    return null
+  }
+
+  function staticTruthiness(node) {
+    const value = resolveBinding(node, checker)
+    if (value.kind === ts.SyntaxKind.TrueKeyword) return true
+    if (value.kind === ts.SyntaxKind.FalseKeyword || value.kind === ts.SyntaxKind.NullKeyword || ts.isVoidExpression(value)) return false
+    if (ts.isIdentifier(value) && value.text === 'undefined' && checker.getSymbolAtLocation(value) === undefined) return false
+    const numeric = numericLiteral(value)
+    if (numeric !== null) return numeric.value !== 0 && !Number.isNaN(numeric.value)
+    const text = staticText(value, checker)
+    if (text !== null) return text.text !== ''
+    if (ts.isObjectLiteralExpression(value) || ts.isArrayLiteralExpression(value) || ts.isArrowFunction(value) || ts.isFunctionExpression(value)) return true
+    return null
+  }
+
+  function mergeChildResults(results) {
+    const rendered = []
+    for (const result of results) {
+      if (result.kind === 'opaque') return result
+      if (result.kind !== 'decorative') rendered.push(result)
+    }
+    if (rendered.length === 0) return { kind: 'decorative' }
+    // Inserir espaço cegamente entre fragmentos muda copy como
+    // `Excluir <strong>agora</strong>!`. Sem modelar o layout/nome acessível completo,
+    // múltiplos fragmentos permanecem opacos; uma única expressão (inclusive uma
+    // união finita de branches) é inequívoca.
+    if (rendered.length > 1) return { kind: 'opaque', node: rendered[1].node ?? rendered[1].values[0].node }
+    return rendered[0]
+  }
+
+  function alternateTexts(...results) {
+    const values = []
+    for (const result of results) {
+      if (result.kind === 'text') values.push(result)
+      else if (result.kind === 'alternatives') values.push(...result.values)
+      else return null
+    }
+    const unique = new Map()
+    for (const value of values) {
+      const previous = unique.get(value.text)
+      unique.set(value.text, previous === undefined ? value : { ...previous, uppercase: previous.uppercase || value.uppercase })
+    }
+    const alternatives = [...unique.values()]
+    if (alternatives.length === 1) return alternatives[0]
+    return { kind: 'alternatives', values: alternatives, node: alternatives[0].node }
+  }
+
+  function childExpression(expression, inheritedUppercase = false, hiddenAncestor = false) {
+    const value = resolveBinding(expression, checker)
+    if (noRenderedValue(value)) return { kind: 'decorative' }
+    const text = staticText(value, checker)
+    if (text !== null) {
+      return text.text.trim() === ''
+        ? { kind: 'decorative' }
+        : { kind: 'text', ...text, uppercase: inheritedUppercase }
+    }
+    if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value) || ts.isJsxFragment(value)) {
+      return childNode(value, inheritedUppercase, hiddenAncestor)
+    }
+    if (ts.isArrayLiteralExpression(value)) {
+      return mergeChildResults(value.elements.map((element) => childExpression(element, inheritedUppercase, hiddenAncestor)))
+    }
+    if (ts.isConditionalExpression(value)) {
+      const condition = resolveBinding(value.condition, checker)
+      const truthy = staticTruthiness(condition)
+      if (truthy === true) {
+        return childExpression(value.whenTrue, inheritedUppercase, hiddenAncestor)
+      }
+      if (truthy === false) {
+        return childExpression(value.whenFalse, inheritedUppercase, hiddenAncestor)
+      }
+      const yes = childExpression(value.whenTrue, inheritedUppercase, hiddenAncestor)
+      const no = childExpression(value.whenFalse, inheritedUppercase, hiddenAncestor)
+      if (yes.kind === 'decorative' && no.kind === 'decorative') return { kind: 'decorative' }
+      if (yes.kind === 'text' && no.kind === 'decorative') return yes
+      if (no.kind === 'text' && yes.kind === 'decorative') return no
+      const alternatives = alternateTexts(yes, no)
+      if (alternatives !== null) return alternatives
+    }
+    if (ts.isBinaryExpression(value) && value.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+      const condition = resolveBinding(value.left, checker)
+      const truthy = staticTruthiness(condition)
+      if (truthy === true) return childExpression(value.right, inheritedUppercase, hiddenAncestor)
+      const numeric = numericLiteral(condition)
+      if (numeric !== null) {
+        if (numeric.value === 0 || Number.isNaN(numeric.value)) {
+          return { kind: 'text', text: numeric.text, node: condition, uppercase: inheritedUppercase }
+        }
+      }
+      if (truthy === false) return { kind: 'decorative' }
+      return { kind: 'opaque', node: condition }
+    }
+    return { kind: 'opaque', node: value }
+  }
+
+  function childNode(child, inheritedUppercase = false, hiddenAncestor = false) {
+    if (ts.isJsxText(child)) {
+      const decoded = decodeJsxEntities(child.text)
+      if (decoded === null) return { kind: 'opaque', node: child }
+      const text = decoded.replace(/\s+/gu, ' ').trim()
+      return text === '' ? { kind: 'decorative' } : { kind: 'text', text, node: child, uppercase: inheritedUppercase }
+    }
+    if (ts.isJsxExpression(child)) {
+      return child.expression === undefined
+        ? { kind: 'decorative' }
+        : childExpression(child.expression, inheritedUppercase, hiddenAncestor)
+    }
+    if (ts.isJsxFragment(child)) return childList(child.children, inheritedUppercase, hiddenAncestor)
+    if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
+      const opening = ts.isJsxElement(child) ? child.openingElement : child
+      const component = opusComponent(opening.tagName)
+      const provenElement = transformableElement(opening, component)
+      const hidden = attribute(opening.attributes, 'aria-hidden')
+      if (hidden.opaque !== undefined) return { kind: 'opaque', node: hidden.opaque }
+      const hiddenValue = attributeBoolean(hidden)
+      if (hidden.candidate !== undefined && hiddenValue === null) return { kind: 'opaque', node: attributeValue(hidden) ?? opening }
+      // `aria-hidden` removes a subtree from the accessibility tree, not from the
+      // rendered UI. It is therefore enough to classify a leaf icon as decorative,
+      // but it must never hide visual text from the copy inventory.
+      const subtreeHidden = hiddenAncestor || hiddenValue === true
+      const dangerous = attribute(opening.attributes, 'dangerouslySetInnerHTML')
+      if (dangerous.opaque !== undefined || dangerous.candidate !== undefined) {
+        return { kind: 'opaque', node: dangerous.opaque ?? attributeValue(dangerous) ?? opening }
+      }
+      // Props de um componente local/terceiro não provam nada sobre o DOM que ele
+      // renderiza. Preserve a herança conhecida e recurse seus children, mas não use
+      // className/style/aria-hidden locais para cancelar ou inventar transformação.
+      if (!provenElement) {
+        if (subtreeHidden) {
+          if (ts.isJsxSelfClosingElement(child)) return { kind: 'decorative' }
+          if (!child.children.some(hasRuntimeChild)) return { kind: 'decorative' }
+          return childList(child.children, inheritedUppercase, true)
+        }
+        if (ts.isJsxSelfClosingElement(child)) return { kind: 'opaque', node: child }
+        if (!child.children.some(hasRuntimeChild)) return { kind: 'opaque', node: child }
+        return childList(child.children, inheritedUppercase, false)
+      }
+      if (subtreeHidden) {
+        if (ts.isJsxSelfClosingElement(child)) return { kind: 'decorative' }
+        if (!child.children.some(hasRuntimeChild)) return { kind: 'decorative' }
+        const transformed = visualTransform(opening.attributes, 'className', 'style', inheritedUppercase, opening.tagName.getText(sourceFile))
+        if (transformed.opaque) return { kind: 'opaque', node: attributeValue(attribute(opening.attributes, 'className')) ?? opening }
+        return childList(child.children, transformed.uppercase, true)
+      }
+      if (ts.isJsxSelfClosingElement(child)) return { kind: 'opaque', node: child }
+      if (!child.children.some(hasRuntimeChild)) return { kind: 'opaque', node: child }
+      const transformed = visualTransform(opening.attributes, 'className', 'style', inheritedUppercase, opening.tagName.getText(sourceFile))
+      if (transformed.opaque) return { kind: 'opaque', node: attributeValue(attribute(opening.attributes, 'className')) ?? opening }
+      return childList(child.children, transformed.uppercase, false)
+    }
+    return { kind: 'opaque', node: child }
+  }
+
+  function childList(children, inheritedUppercase = false, hiddenAncestor = false) {
+    return mergeChildResults(children.map((child) => childNode(child, inheritedUppercase, hiddenAncestor)))
+  }
+
+  function hasRuntimeChild(child) {
+    if (ts.isJsxText(child)) return child.text.replace(/\s+/gu, ' ').trim() !== ''
+    if (ts.isJsxExpression(child)) return child.expression !== undefined
+    return true
+  }
+
+  function addVisualObjectProperty(object, name, role, prefix, inheritedUppercase = false) {
+    const resolved = property(object, name, sourceFile, checker)
+    if (resolved.opaque !== undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, resolved.opaque, `${prefix}${name}`))
+      return null
+    }
+    if (resolved.candidate === undefined) return null
+    const raw = propertyValue(resolved.candidate)
+    const value = resolveBinding(raw, checker)
+    if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value) || ts.isJsxFragment(value) || ts.isArrayLiteralExpression(value)) {
+      const child = childExpression(value, inheritedUppercase)
+      if (child.kind === 'opaque') diagnostics.push(diagnostic(file, sourceFile, child.node, `${prefix}${name}`))
+      const texts = child.kind === 'text' ? [child] : child.kind === 'alternatives' ? child.values : []
+      for (const text of texts) {
+        const entry = { source: file, line: lineOf(sourceFile, text.node), role, text: text.text }
+        if (text.uppercase) entry.transform = 'uppercase'
+        entries.push(entry)
+      }
+      return texts[0] ?? null
+    }
+    const entry = add(raw, role, `${prefix}${name}`)
+    if (entry !== null && inheritedUppercase) entry.transform = 'uppercase'
+    return entry
+  }
+
+  function actionTriggerIconState(opening) {
+    const icon = attribute(opening.attributes, 'icon')
+    if (icon.opaque !== undefined) return { kind: 'unknown', node: icon.opaque }
+    if (icon.candidate === undefined) return { kind: 'absent' }
+    const raw = attributeValue(icon)
+    // O componente usa `icon !== undefined`: null/false também ativam o tooltip, e o
+    // rótulo deixa de ser descendente do botão. Só `undefined` comprovado mantém texto.
+    if (raw === null) return { kind: 'present' }
+    const value = resolveBinding(raw, checker)
+    if (ts.isVoidExpression(value)) return { kind: 'absent' }
+    if (ts.isIdentifier(value) && value.text === 'undefined' && checker.getSymbolAtLocation(value) === undefined) {
+      return { kind: 'absent' }
+    }
+    if (ts.isConditionalExpression(value)) {
+      const yes = actionTriggerIconValueState(value.whenTrue)
+      const no = actionTriggerIconValueState(value.whenFalse)
+      if (yes === no && yes !== 'unknown') return { kind: yes }
+    }
+    if (actionTriggerIconValueState(value) === 'present') return { kind: 'present' }
+    return { kind: 'unknown', node: value }
+  }
+
+  function actionTriggerIconValueState(node) {
+    const value = resolveBinding(node, checker)
+    if (ts.isVoidExpression(value)) return 'absent'
+    if (ts.isIdentifier(value) && value.text === 'undefined' && checker.getSymbolAtLocation(value) === undefined) return 'absent'
+    if (
+      value.kind === ts.SyntaxKind.NullKeyword ||
+      value.kind === ts.SyntaxKind.TrueKeyword ||
+      value.kind === ts.SyntaxKind.FalseKeyword ||
+      ts.isStringLiteralLike(value) ||
+      ts.isNumericLiteral(value) ||
+      ts.isBigIntLiteral(value) ||
+      ts.isObjectLiteralExpression(value) ||
+      ts.isArrayLiteralExpression(value) ||
+      ts.isJsxElement(value) ||
+      ts.isJsxSelfClosingElement(value) ||
+      ts.isJsxFragment(value) ||
+      ts.isArrowFunction(value) ||
+      ts.isFunctionExpression(value)
+    ) return 'present'
+    return 'unknown'
+  }
+
+  function actionTriggerLabelTransform(opening, inheritedUppercase = false) {
+    const icon = actionTriggerIconState(opening)
+    if (icon.kind === 'present') return { opaque: false, uppercase: false }
+    const transformed = visualTransform(opening.attributes, 'className', 'style', inheritedUppercase, '<ActionTrigger>')
+    if (icon.kind === 'absent' || transformed.opaque || !transformed.uppercase) return transformed
+    // O label pode estar no botão (herda a classe) ou no tooltip (portal). Sem resolver
+    // o discriminador, marcar uppercase seria uma garantia falsa; o gate pede explicitação.
+    transformDiagnostic(icon.node, '<ActionTrigger>.icon')
+    return { opaque: true, uppercase: false }
+  }
+
+  function selectMode(opening, component) {
+    if (component !== 'Select') return null
+    const native = attribute(opening.attributes, 'native')
+    if (native.opaque !== undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, native.opaque, '<Select>.native'))
+      return 'opaque'
+    }
+    if (native.candidate === undefined) return 'custom'
+    const value = attributeBoolean(native)
+    if (value === null) {
+      diagnostics.push(diagnostic(file, sourceFile, attributeValue(native) ?? opening, '<Select>.native'))
+      return 'opaque'
+    }
+    return value ? 'native' : 'custom'
+  }
+
+  function extractJsx(element) {
+    const opening = ts.isJsxElement(element) ? element.openingElement : element
+    const component = opusComponent(opening.tagName)
+    if (component === null) return
+    let inherited
+    const inheritedFor = (className, styleName, portal = false) => {
+      if (portal || localTransformOverridesInheritance(opening.attributes, className, styleName)) return false
+      inherited ??= ancestorTransform(element)
+      return inherited.opaque ? false : inherited.uppercase
+    }
+    const actionFormCardBodyTransform = () => {
+      // O form é descendente do Card. Uma transformação incondicional no próprio form
+      // corta toda herança anterior; caso contrário, cardClassName participa primeiro.
+      if (localTransformOverridesInheritance(opening.attributes, 'className', null)) {
+        return visualTransform(opening.attributes, 'className', null, false, '<ActionFormCard>')
+      }
+      const card = visualTransform(
+        opening.attributes,
+        'cardClassName',
+        null,
+        inheritedFor('cardClassName', null),
+        '<ActionFormCard>',
+      )
+      if (card.opaque) return card
+      return visualTransform(opening.attributes, 'className', null, card.uppercase, '<ActionFormCard>')
+    }
+    const mode = selectMode(opening, component)
+
+    for (const name of OPAQUE_SLOT_PROPS.get(component) ?? []) {
+      const slot = attribute(opening.attributes, name)
+      if (slot.opaque !== undefined) diagnostics.push(diagnostic(file, sourceFile, slot.opaque, `<${component}>.${name}`))
+      else if (slot.candidate !== undefined) {
+        const raw = attributeValue(slot)
+        if (raw === null || !noRenderedValue(raw)) diagnostics.push(diagnostic(file, sourceFile, raw ?? opening, `<${component}>.${name}`))
+      }
+    }
+
+    const props = JSX_PROP_ROLES.get(component)
+    for (const [name, role] of props ?? []) {
+      if (component === 'Select' && mode === 'native' && name !== 'placeholder') continue
+      const item = attribute(opening.attributes, name)
+      if (item.opaque !== undefined) diagnostics.push(diagnostic(file, sourceFile, item.opaque, `<${component}>.${name}`))
+      else if (item.candidate === undefined) continue
+      else {
+        const classProp = JSX_PROP_CLASS.get(component)?.get(name)
+        const styleProp = JSX_PROP_STYLE.get(component)?.get(name) ?? null
+        const inheritedForSurface = component === 'ActionFormCard' && classProp === 'className'
+          ? false
+          : inheritedFor(
+            classProp ?? null,
+            styleProp,
+            component === 'ActionFormDialog' || (component === 'Select' && name !== 'placeholder'),
+          )
+        const transformed = component === 'ActionTrigger' && name === 'label'
+          ? actionTriggerLabelTransform(opening, inheritedForSurface)
+          : component === 'ActionFormCard' && classProp === 'className'
+            ? actionFormCardBodyTransform()
+            : classProp === undefined
+              ? { opaque: false, uppercase: inheritedForSurface }
+              : visualTransform(
+                opening.attributes,
+                classProp,
+                styleProp,
+                inheritedForSurface,
+                `<${component}>`,
+              )
+        const raw = attributeValue(item)
+        const resolved = raw === null ? null : resolveBinding(raw, checker)
+        if (resolved !== null && (ts.isJsxElement(resolved) || ts.isJsxSelfClosingElement(resolved) || ts.isJsxFragment(resolved) || ts.isArrayLiteralExpression(resolved))) {
+          const child = childExpression(resolved, transformed.uppercase)
+          if (child.kind === 'opaque') diagnostics.push(diagnostic(file, sourceFile, child.node, `<${component}>.${name}`))
+          else {
+            const texts = child.kind === 'text' ? [child] : child.kind === 'alternatives' ? child.values : []
+            for (const text of texts) {
+              const entry = { source: file, line: lineOf(sourceFile, text.node), role, text: text.text }
+              if (text.uppercase) entry.transform = 'uppercase'
+              entries.push(entry)
+            }
+          }
+        } else {
+          const value = attributeText(item)
+          if (value === null) diagnostics.push(diagnostic(file, sourceFile, raw ?? opening, `<${component}>.${name}`))
+          else {
+            const entry = { source: file, line: lineOf(sourceFile, value.node), role, text: value.text }
+            if (transformed.uppercase) entry.transform = 'uppercase'
+            entries.push(entry)
+          }
+        }
+      }
+    }
+
+    if (component === 'ActionTrigger') {
+      const label = attribute(opening.attributes, 'label')
+      if (label.candidate === undefined && label.opaque === undefined) {
+        const transformed = actionTriggerLabelTransform(
+          opening,
+          inheritedFor('className', 'style'),
+        )
+        if (transformed.uppercase) {
+          diagnostics.push(diagnostic(file, sourceFile, opening, '<ActionTrigger>.label herdado do contrato sob uppercase'))
+        }
+      }
+    }
+
+    for (const [name, nestedRoles] of JSX_OBJECT_PROP_ROLES.get(component) ?? []) {
+      const item = attribute(opening.attributes, name)
+      if (item.opaque !== undefined) diagnostics.push(diagnostic(file, sourceFile, item.opaque, `<${component}>.${name}`))
+      else if (item.candidate !== undefined) {
+        const raw = attributeValue(item)
+        const object = raw === null ? null : resolveBinding(raw, checker)
+        if (object?.kind === ts.SyntaxKind.NullKeyword || (ts.isIdentifier(object) && object.text === 'undefined')) continue
+        if (!ts.isObjectLiteralExpression(object)) diagnostics.push(diagnostic(file, sourceFile, raw ?? opening, `<${component}>.${name}`))
+        else for (const [nestedName, role] of nestedRoles) addProperty(object, nestedName, role, `<${component}>.${name}.`)
+      }
+    }
+
+    for (const [name, optionRoles] of JSX_ARRAY_PROP_ROLES.get(component) ?? []) {
+      const item = attribute(opening.attributes, name)
+      if (item.opaque !== undefined) diagnostics.push(diagnostic(file, sourceFile, item.opaque, `<${component}>.${name}`))
+      else if (item.candidate !== undefined) {
+        const raw = attributeValue(item)
+        const listed = raw === null ? { values: [], opaque: [opening] } : objects(raw, checker)
+        for (const opaque of listed.opaque) diagnostics.push(diagnostic(file, sourceFile, opaque, `<${component}>.${name}`))
+        for (const [index, option] of listed.values.entries()) {
+          for (const [optionName, role] of optionRoles) {
+            if (mode === 'native' && !['label', 'group'].includes(optionName)) continue
+            const affectsTrigger = optionName === 'label' || (mode === 'custom' && optionName === 'triggerLabel')
+            const affectsNative = mode === 'native' && (optionName === 'label' || optionName === 'group')
+            const transformed = affectsTrigger || affectsNative
+              ? visualTransform(
+                opening.attributes,
+                'className',
+                null,
+                inheritedFor('className', null),
+                `<${component}>`,
+              )
+              : { opaque: false, uppercase: false }
+            addVisualObjectProperty(
+              option,
+              optionName,
+              role,
+              `<${component}>.${name}[${index}].`,
+              transformed.uppercase,
+            )
+          }
+        }
+      }
+    }
+
+    const ariaLabelAttribute = attribute(opening.attributes, 'aria-label')
+    let hasStaticAriaLabel = false
+    if (ariaLabelAttribute.opaque !== undefined) {
+      diagnostics.push(diagnostic(file, sourceFile, ariaLabelAttribute.opaque, `<${component}>.aria-label`))
+    } else if (ariaLabelAttribute.candidate !== undefined) {
+      const ariaLabel = attributeText(ariaLabelAttribute)
+      if (ariaLabel === null) diagnostics.push(diagnostic(file, sourceFile, attributeValue(ariaLabelAttribute) ?? opening, `<${component}>.aria-label`))
+      if (ariaLabel !== null) {
+        hasStaticAriaLabel = true
+        entries.push({ source: file, line: lineOf(sourceFile, ariaLabel.node), role: 'label', text: ariaLabel.text })
+      }
+    }
+
+    const childRole = JSX_CHILD_ROLES.get(component)
+    if (childRole !== undefined) {
+      const childValue = (inheritedUppercase) => {
+      // Quebras/indentação puras não viram `children` no JSX emitido e, portanto,
+      // não sobrescrevem uma prop `children="..."` explícita.
+        if (ts.isJsxElement(element) && element.children.some(hasRuntimeChild)) {
+          if (
+            OPTIONAL_CHILD_COMPONENTS.has(component) &&
+            element.children.some((item) => ts.isJsxElement(item) || ts.isJsxSelfClosingElement(item) || ts.isJsxFragment(item))
+          ) return { kind: 'opaque', node: element.children.find((item) => ts.isJsxElement(item) || ts.isJsxSelfClosingElement(item) || ts.isJsxFragment(item)) }
+          return childList(element.children, inheritedUppercase)
+        }
+        const children = attribute(opening.attributes, 'children')
+        if (children.opaque !== undefined) return { kind: 'opaque', node: children.opaque }
+        if (children.candidate === undefined) return { kind: 'decorative' }
+        const raw = attributeValue(children)
+        return raw === null ? { kind: 'opaque', node: opening } : childExpression(raw, inheritedUppercase)
+      }
+      const inheritedUppercase = component === 'ActionFormDialog'
+        ? false
+        : component === 'ActionFormCard'
+          ? actionFormCardBodyTransform().uppercase
+          : inheritedFor('className', 'style')
+      let value = childValue(inheritedUppercase)
+      if (value.kind === 'text' || value.kind === 'alternatives') {
+        const transformed = component === 'ActionFormDialog'
+          ? { opaque: false, uppercase: false }
+          : component === 'ActionFormCard'
+            ? actionFormCardBodyTransform()
+            : visualTransform(opening.attributes, 'className', 'style', inheritedUppercase, `<${component}>`)
+        value = transformed.opaque ? { kind: 'opaque', node: attributeValue(attribute(opening.attributes, 'className')) ?? opening } : childValue(transformed.uppercase)
+      }
+      if (value.kind === 'opaque') diagnostics.push(diagnostic(file, sourceFile, value.node, `<${component}> children`))
+      else if (value.kind === 'decorative') {
+        if (!hasStaticAriaLabel && !OPTIONAL_CHILD_COMPONENTS.has(component)) diagnostics.push(diagnostic(file, sourceFile, element, `<${component}> children`))
+      } else {
+        const texts = value.kind === 'text' ? [value] : value.values
+        for (const text of texts) {
+          const entry = { source: file, line: lineOf(sourceFile, text.node), role: childRole, text: text.text }
+          if (text.uppercase) entry.transform = 'uppercase'
+          entries.push(entry)
+        }
+      }
+    }
+  }
+
+  function visit(node) {
+    const factory = ts.isCallExpression(node) ? contractFactory(node.expression) : null
+    if (ts.isCallExpression(node) && factory !== null && node.arguments.length > 0) {
+      hasContract = true
+      if (!stableFactoryResult(node, checker, new Set())) {
+        diagnostics.push(diagnostic(file, sourceFile, node, `${factory}(...) result`))
+      } else {
+        const object = resolveBinding(node.arguments[0], checker)
+        if (ts.isObjectLiteralExpression(object)) extractContract(object)
+        else diagnostics.push(diagnostic(file, sourceFile, node.arguments[0], `${factory}(...)`))
+      }
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) extractJsx(node)
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+
+  return { hasContract, hasCopySurface: hasContract || hasUiImport, entries, diagnostics }
+}
+
+function globRegex(pattern) {
+  const escaped = portable(pattern)
+    .split('**')
+    .map((part) => part.split('*').map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*'))
+    .join('.*')
+  return new RegExp(`^${escaped}$`)
+}
+
+function sourceFiles(root, excluded = []) {
+  const output = []
+  const diagnostics = []
+  const walk = (directory = '.') => {
+    let listing
+    try {
+      listing = readProjectDirectory(root, directory)
+    } catch (error) {
+      diagnostics.push({
+        source: portable(directory),
+        line: 1,
+        message: `diretório de source inseguro ou instável: ${projectPathErrorMessage(error)}`,
+      })
+      return
+    }
+    for (const item of listing.entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const target = path.join(directory, item.name)
+      const source = portable(target === '.' ? item.name : target)
+      if (IGNORED_DIRECTORIES.has(item.name)) continue
+      if (item.isSymbolicLink()) {
+        if (!excluded.some((pattern) => globRegex(pattern).test(source))) {
+          diagnostics.push({
+            source,
+            line: 1,
+            message: 'link simbólico dentro do escopo percorrido pode ocultar um diretório de sources; remova-o ou exclua o caminho explicitamente em copy.exclude.',
+          })
+        }
+        continue
+      }
+      if (item.isDirectory()) {
+        let inspected
+        try {
+          inspected = safeProjectPath(root, target, { mustExist: true })
+        } catch (error) {
+          diagnostics.push({ source, line: 1, message: `diretório de source inseguro: ${projectPathErrorMessage(error)}` })
+          continue
+        }
+        if (inspected.kind !== 'directory') {
+          diagnostics.push({ source, line: 1, message: 'entrada de source deixou de ser diretório durante a descoberta.' })
+          continue
+        }
+        walk(target)
+      } else if (
+        item.isFile() &&
+        SOURCE_EXTENSIONS.has(path.extname(item.name)) &&
+        !IGNORED_FILE.test(item.name) &&
+        !excluded.some((pattern) => globRegex(pattern).test(source))
+      ) {
+        try {
+          const inspected = safeProjectPath(root, target, { mustExist: true })
+          if (inspected.kind !== 'file') {
+            diagnostics.push({ source, line: 1, message: 'source deixou de ser arquivo regular durante a descoberta.' })
+          } else {
+            output.push(source)
+          }
+        } catch (error) {
+          diagnostics.push({ source, line: 1, message: `source inseguro: ${projectPathErrorMessage(error)}` })
+        }
+      }
+    }
+  }
+  walk()
+  return { files: output, diagnostics }
+}
+
+export function copyInventoryPath(root) {
+  return copyConfiguration(root).inventoryPath
+}
+
+function copyConfiguration(root) {
+  let file
+  try {
+    file = readProjectFile(root, 'base.json', { allowMissing: true })
+  } catch (error) {
+    throw new Error(`base.json: ${projectPathErrorMessage(error)}`)
+  }
+  if (!file.exists) {
+    const inventoryPath = safeInventoryPath(root, DEFAULT_COPY_INVENTORY)
+    return {
+      configFile: file,
+      inventory: portable(path.relative(safeProjectPath(root, '.').root, inventoryPath)),
+      inventoryPath,
+      exemptions: [],
+      transforms: [],
+      exclude: [],
+    }
+  }
+  let config
+  try {
+    config = JSON.parse(file.content).copy
+  } catch {
+    throw new Error('base.json não é JSON válido.')
+  }
+  const inventory = config?.inventory ?? DEFAULT_COPY_INVENTORY
+  if (typeof inventory !== 'string' || inventory.trim() === '') {
+    throw new Error('base.json: copy.inventory deve ser um caminho não vazio.')
+  }
+  const target = safeInventoryPath(root, inventory)
+  return {
+    configFile: file,
+    inventory: portable(path.relative(safeProjectPath(root, '.').root, target)),
+    inventoryPath: target,
+    exemptions: config?.exemptions ?? [],
+    transforms: config?.transforms ?? [],
+    exclude: config?.exclude ?? [],
+  }
+}
+
+function selectorDiagnostic(message) {
+  return { source: 'base.json', line: 1, message }
+}
+
+function sameProjectFile(left, right) {
+  return (
+    left.exists === right.exists &&
+    (!left.exists ||
+      (left.identity.dev === right.identity.dev &&
+        left.identity.ino === right.identity.ino &&
+        left.mode === right.mode &&
+        left.modifiedAtMs === right.modifiedAtMs &&
+        left.content === right.content))
+  )
+}
+
+function verifyConfiguration(root, expected) {
+  let current
+  try {
+    current = readProjectFile(root, 'base.json', { allowMissing: true })
+  } catch (error) {
+    throw new Error(`base.json: ${projectPathErrorMessage(error)}`)
+  }
+  if (!sameProjectFile(expected, current)) throw new Error('base.json mudou durante a extração de copy.')
+}
+
+function verifyCopyInputs(root, consistency) {
+  verifyConfiguration(root, consistency.configFile)
+  const discovered = sourceFiles(root, consistency.excluded)
+  if (discovered.diagnostics.length > 0) {
+    const first = discovered.diagnostics[0]
+    throw new Error(`${first.source}: ${first.message}`)
+  }
+  if (JSON.stringify(discovered.files) !== JSON.stringify(consistency.discoveredSources)) {
+    throw new Error('o conjunto de sources mudou durante a geração do inventário de copy.')
+  }
+  for (const snapshot of consistency.sourceSnapshots) {
+    const current = readProjectFile(root, snapshot.source)
+    if (!sameProjectFile(snapshot.file, current)) {
+      throw new Error(`${snapshot.source}: source mudou durante a geração do inventário de copy.`)
+    }
+  }
+  verifyConfiguration(root, consistency.configFile)
+}
+
+function findEntry(entries, selector) {
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .filter(({ entry }) =>
+      entry.source === selector.source &&
+      entry.line === selector.line &&
+      entry.role === selector.role &&
+      (selector.text === undefined || entry.text === selector.text),
+    )
+}
+
+function applyProjectMetadata(config, entries, diagnostics) {
+  if (!Array.isArray(config.exemptions)) {
+    diagnostics.push(selectorDiagnostic('copy.exemptions deve ser uma lista.'))
+  } else {
+    for (const [index, exemption] of config.exemptions.entries()) {
+      if (
+        exemption === null ||
+        typeof exemption !== 'object' ||
+        typeof exemption.source !== 'string' ||
+        !Number.isInteger(exemption.line) ||
+        typeof exemption.role !== 'string' ||
+        typeof exemption.ruleId !== 'string' ||
+        !COPY_RULE_ID.test(exemption.ruleId) ||
+        typeof exemption.kind !== 'string' ||
+        exemption.kind.trim() === '' ||
+        typeof exemption.reason !== 'string' ||
+        exemption.reason.trim().length < 12 ||
+        typeof exemption.reference !== 'string' ||
+        exemption.reference.trim() === ''
+      ) {
+        diagnostics.push(selectorDiagnostic(`copy.exemptions[${index}] exige seletor, ruleId, kind, reason e reference válidos.`))
+        continue
+      }
+      const matches = findEntry(entries, exemption)
+      if (matches.length !== 1) {
+        diagnostics.push(selectorDiagnostic(`copy.exemptions[${index}] deve selecionar exatamente um texto; encontrou ${matches.length}.`))
+        continue
+      }
+      const target = entries[matches[0].index]
+      target.exemptions ??= []
+      if (target.exemptions.some((item) => item.ruleId === exemption.ruleId)) {
+        diagnostics.push(selectorDiagnostic(`copy.exemptions[${index}] repete ${exemption.ruleId} no mesmo texto.`))
+        continue
+      }
+      target.exemptions.push({
+        ruleId: exemption.ruleId,
+        kind: exemption.kind.trim(),
+        reason: exemption.reason.trim(),
+        reference: exemption.reference.trim(),
+      })
+    }
+  }
+
+  if (!Array.isArray(config.transforms)) {
+    diagnostics.push(selectorDiagnostic('copy.transforms deve ser uma lista.'))
+  } else {
+    // Metadata declarativa complementa o que o extrator não consegue observar; ela
+    // nunca pode enfraquecer um `uppercase` comprovado no JSX.
+    const transformed = new Set(
+      entries
+        .map((entry, index) => (entry.transform === undefined ? null : index))
+        .filter((index) => index !== null),
+    )
+    for (const [index, transform] of config.transforms.entries()) {
+      if (
+        transform === null ||
+        typeof transform !== 'object' ||
+        typeof transform.source !== 'string' ||
+        !Number.isInteger(transform.line) ||
+        typeof transform.role !== 'string' ||
+        !['none', 'lowercase', 'uppercase'].includes(transform.transform)
+      ) {
+        diagnostics.push(selectorDiagnostic(`copy.transforms[${index}] tem seletor ou transform inválido.`))
+        continue
+      }
+      const matches = findEntry(entries, transform)
+      if (matches.length !== 1) {
+        diagnostics.push(selectorDiagnostic(`copy.transforms[${index}] deve selecionar exatamente um texto; encontrou ${matches.length}.`))
+        continue
+      }
+      const entryIndex = matches[0].index
+      if (transformed.has(entryIndex)) {
+        diagnostics.push(selectorDiagnostic(`copy.transforms[${index}] tenta sobrescrever um texto já transformado.`))
+        continue
+      }
+      transformed.add(entryIndex)
+      entries[entryIndex].transform = transform.transform
+    }
+  }
+}
+
+export function extractCopyInventory(root) {
+  const target = path.resolve(root)
+  const config = copyConfiguration(target)
+  const sources = []
+  const sourceSnapshots = []
+  const entries = []
+  const diagnostics = []
+
+  if (!Array.isArray(config.exclude) || config.exclude.some((pattern) => typeof pattern !== 'string' || pattern.trim() === '')) {
+    diagnostics.push(selectorDiagnostic('copy.exclude deve ser uma lista de globs não vazios.'))
+  }
+  const excluded = Array.isArray(config.exclude) ? config.exclude.filter((pattern) => typeof pattern === 'string') : []
+  const discovered = sourceFiles(target, excluded)
+  diagnostics.push(...discovered.diagnostics)
+  for (const source of discovered.files) {
+    let file
+    try {
+      file = readProjectFile(target, source)
+    } catch (error) {
+      diagnostics.push({ source, line: 1, message: `source inseguro ou instável: ${projectPathErrorMessage(error)}` })
+      continue
+    }
+    const content = file.content
+    const extracted = extractCopyFromSource(source, content)
+    // `sources` é o manifesto observável do escopo realmente submetido ao parser,
+    // inclusive quando um arquivo não contém contrato/allowlist ou produz zero copy.
+    sources.push({ path: source, sha256: digest(content) })
+    sourceSnapshots.push({ source, file })
+    entries.push(...extracted.entries)
+    diagnostics.push(...extracted.diagnostics)
+  }
+  for (const snapshot of sourceSnapshots) {
+    try {
+      const current = readProjectFile(target, snapshot.source)
+      if (!sameProjectFile(snapshot.file, current)) {
+        diagnostics.push({ source: snapshot.source, line: 1, message: 'source mudou durante a extração de copy.' })
+      }
+    } catch (error) {
+      diagnostics.push({
+        source: snapshot.source,
+        line: 1,
+        message: `source mudou ou se tornou inseguro durante a extração: ${projectPathErrorMessage(error)}`,
+      })
+    }
+  }
+  try {
+    verifyConfiguration(target, config.configFile)
+  } catch (error) {
+    diagnostics.push(selectorDiagnostic(error.message))
+  }
+  if (sources.length === 0) {
+    diagnostics.push(selectorDiagnostic(
+      'nenhum arquivo JavaScript/TypeScript elegível foi analisado; o inventário v2 exige ao menos uma fonte rastreável.',
+    ))
+  }
+  applyProjectMetadata(config, entries, diagnostics)
+
+  const coveredSources = new Set(entries.map((entry) => entry.source)).size
+
+  const result = {
+    inventory: {
+      schemaVersion: COPY_INVENTORY_SCHEMA_VERSION,
+      generator: { name: PACKAGE.name, version: PACKAGE.version },
+      coverage: {
+        protocol: COPY_COVERAGE_PROTOCOL,
+        analyzedFiles: sources.length,
+        coveredSources,
+        extractedEntries: entries.length,
+      },
+      sources,
+      entries,
+    },
+    diagnostics,
+  }
+  Object.defineProperties(result, {
+    configuration: { value: config },
+    consistency: {
+      value: {
+        configFile: config.configFile,
+        discoveredSources: [...discovered.files],
+        excluded: [...excluded],
+        sourceSnapshots,
+      },
+    },
+  })
+  return result
+}
+
+export function renderCopyInventory(inventory) {
+  return `${JSON.stringify(inventory, null, 2)}\n`
+}
+
+function ensureCopyParents(root, destination) {
+  const pending = []
+  let parent = path.dirname(destination)
+  while (parent !== '.') {
+    pending.unshift(parent)
+    const next = path.dirname(parent)
+    if (next === parent) throw new Error('copy.inventory deve ser relativo ao projeto.')
+    parent = next
+  }
+  for (const directory of pending) ensureProjectDirectory(root, directory)
+}
+
+/** Grava no mesmo diretório e renomeia; uma falha nunca deixa JSON parcial. */
+export function writeCopyInventory(root) {
+  const targetRoot = path.resolve(root)
+  const result = extractCopyInventory(targetRoot)
+  if (result.diagnostics.length > 0) return { ok: false, changed: false, ...result }
+
+  const destination = result.configuration.inventory
+  const target = result.configuration.inventoryPath
+  const rendered = renderCopyInventory(result.inventory)
+  let current
+  try {
+    current = readProjectFile(targetRoot, destination, { allowMissing: true })
+    verifyCopyInputs(targetRoot, result.consistency)
+  } catch (error) {
+    throw new Error(`copy.inventory: ${projectPathErrorMessage(error) === 'operação de arquivo recusada por segurança.' ? error.message : projectPathErrorMessage(error)}`)
+  }
+  if (current.exists && current.content === rendered) {
+    return { ok: true, changed: false, path: target, ...result }
+  }
+
+  let written = null
+  try {
+    ensureCopyParents(targetRoot, destination)
+    writeProjectFileAtomically(
+      targetRoot,
+      destination,
+      rendered,
+      { exists: current.exists, content: current.content },
+    )
+    written = readProjectFile(targetRoot, destination)
+    verifyCopyInputs(targetRoot, result.consistency)
+  } catch (error) {
+    if (written !== null) {
+      try {
+        if (current.exists) {
+          const rollbackCurrent = readProjectFile(targetRoot, destination)
+          if (!sameProjectFile(written, rollbackCurrent)) {
+            throw new Error('inventário mudou antes da reversão.')
+          }
+          writeProjectFileAtomically(
+            targetRoot,
+            destination,
+            current.content,
+            { exists: true, content: written.content },
+            { mode: current.mode },
+          )
+        } else {
+          removeProjectFileIfUnchanged(targetRoot, destination, written)
+        }
+      } catch (rollbackError) {
+        throw new Error(
+          `copy.inventory: as entradas mudaram e a reversão segura falhou: ${projectPathErrorMessage(rollbackError) === 'operação de arquivo recusada por segurança.' ? rollbackError.message : projectPathErrorMessage(rollbackError)}`,
+        )
+      }
+    }
+    throw new Error(`copy.inventory: ${projectPathErrorMessage(error) === 'operação de arquivo recusada por segurança.' ? error.message : projectPathErrorMessage(error)}`)
+  }
+  return { ok: true, changed: true, path: target, ...result }
+}
+
+export function checkCopyInventory(root) {
+  const targetRoot = path.resolve(root)
+  const result = extractCopyInventory(targetRoot)
+  if (result.diagnostics.length > 0) return { ok: false, reason: 'unsupported', ...result }
+  const destination = result.configuration.inventory
+  const target = result.configuration.inventoryPath
+  let current
+  try {
+    current = readProjectFile(targetRoot, destination, { allowMissing: true })
+  } catch (error) {
+    return {
+      ...result,
+      ok: false,
+      reason: 'unsafe',
+      path: target,
+      diagnostics: [
+        ...result.diagnostics,
+        selectorDiagnostic(`copy.inventory inseguro ou instável: ${projectPathErrorMessage(error) === 'operação de arquivo recusada por segurança.' ? error.message : projectPathErrorMessage(error)}`),
+      ],
+    }
+  }
+  if (!current.exists) return { ok: false, reason: 'missing', path: target, ...result }
+  const expected = renderCopyInventory(result.inventory)
+  const actual = current.content
+  if (actual !== expected) return { ok: false, reason: 'stale', path: target, ...result }
+  try {
+    verifyCopyInputs(targetRoot, result.consistency)
+  } catch (error) {
+    return {
+      ...result,
+      ok: false,
+      reason: 'unsafe',
+      path: target,
+      diagnostics: [
+        ...result.diagnostics,
+        selectorDiagnostic(`sources ou configuração mudaram antes da confirmação final: ${projectPathErrorMessage(error) === 'operação de arquivo recusada por segurança.' ? error.message : projectPathErrorMessage(error)}`),
+      ],
+    }
+  }
+  return { ok: true, reason: 'current', path: target, ...result }
+}