@softize/opus 28.0.0 → 30.0.0

package/CHANGELOG.md

@@ -7,6 +7,85 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 30.0.0 — 2026-10-16
+
+PageMeta, DrawerMeta, DialogMeta e SurfaceMeta organizam badges, datas e autoria em
+faixa própria sob o título e a descrição. Page e Surface também aceitam a prop `meta`.
+
+### Breaking
+
+**Migração:** SurfaceMeta deixa de ocupar a linha do título. Contadores explícitos usam
+SurfaceCount; a prop `count` conserva o comportamento anterior. Metadados contextuais
+existentes permanecem em SurfaceMeta e passam para a faixa inferior. Revise manualmente
+os usos existentes de SurfaceMeta: os gates não distinguem um contador de metadados.
+Descrições textuais usam SurfaceDescription. DialogMeta não se aplica ao modo de alerta.
+
+Tabelas quebram texto entre palavras, preservando palavras curtas inteiras, e ActionList
+mantém a rolagem dentro dos resultados,
+sem alargar a superfície. Filtros inline podem ocupar mais de uma linha. Colunas `fit`
+preservam os valores sem quebra; a distribuição automática considera também os cabeçalhos,
+que podem quebrar quando falta espaço. Colunas de dados não recebem largura mínima forçada;
+seleção, ações de linha e células contendo apenas um switch permanecem compactas. Em tabelas
+compostas diretamente, use `whitespace-nowrap` para valores que devem permanecer inteiros.
+
+## 29.0.0 — 2026-10-15
+
+O `CLAUDE.md` passa a importar o `AGENTS.md`, e as declarações de copy passam a ser ancoradas pelo
+conteúdo, não pela linha. A seção **Breaking** traz a única migração obrigatória, que atinge só quem
+mantém instruções no `CLAUDE.md` que não estão no `AGENTS.md`.
+
+### Breaking
+
+`opus setup` mantém o bloco do Opus só no `AGENTS.md` e grava o `CLAUDE.md` como a linha
+`@AGENTS.md`, que importa as instruções para o Claude Code (ADR 0061, no mesmo formato da ADR 0006 da
+Base). Na conversão, o `setup` remove do `CLAUDE.md` o bloco do Opus e descarta o texto do projeto
+que repete o do `AGENTS.md`. Texto que só existe no `CLAUDE.md` é preservado, e o `setup` e o
+`opus pre-push materialization` reprovam até que ele vá para o `AGENTS.md`. Blocos de outros
+pacotes ficam depois do import até que o pacote dono os remova: com uma Base anterior à ADR 0006, o
+`CLAUDE.md` fica com o import e o bloco da Base.
+
+Migre movendo para o `AGENTS.md` as instruções que estão só no `CLAUDE.md` e rodando `opus setup`.
+
+### Âncora de copy pelo conteúdo
+
+- **`copy.dynamic` por trecho.** A declaração seleciona o diagnóstico por `source`, `field` e
+  `expression`, o trecho de código que o extrator não resolveu, e continua válida quando linhas
+  entram ou saem acima dela. Espaços e quebras de linha do trecho são normalizados e a vírgula
+  final antes de `)`, `]` ou `}` é ignorada, para a âncora sobreviver à reformatação. A declaração
+  vale para toda ocorrência do mesmo trecho no mesmo campo do arquivo, e `dynamicSurfaces` registra
+  as linhas atuais de cada uma. O diagnóstico de conteúdo traz o `field` e a `expression` prontos
+  para a declaração.
+- **`copy.exemptions` e `copy.transforms` por texto.** Sem `line`, `source`, `role` e `text`
+  selecionam toda ocorrência desse texto com esse papel no arquivo.
+- **Seletores por linha continuam aceitos.** Eles selecionam exatamente um alvo, são aplicados
+  antes dos seletores por conteúdo e geram um aviso no `opus copy`. `opus copy --reanchor` converte
+  o `base.json` agrupando as declarações por arquivo e campo, ou por arquivo, papel e texto. Um
+  grupo só é convertido quando tem uma declaração para cada alvo, para que a âncora por conteúdo não
+  cubra um alvo que ninguém declarou; dentro dele, declarações e alvos são pareados em ordem de
+  linha, e as que mudaram de linha são listadas para revisão. Declarações idênticas se fundem, e
+  duas com motivos diferentes para o mesmo conteúdo continuam por linha, já corrigida. Os seletores
+  gravados passam na extração do `opus copy`; a política da Base não é avaliada, então rode
+  `opus copy --check` e `base copy check` depois e revise o diff.
+- **`dynamicSurfaces` no inventário.** Uma declaração por conteúdo aparece com `expression` e
+  `lines`, as linhas atuais de cada ocorrência, no lugar de `line`. Uma lista `lines` que cresce no
+  diff indica que o trecho passou a cobrir uma ocorrência nova.
+- **Erros que dizem onde.** Cada seletor que deixa de encontrar seu alvo aparece na mesma execução,
+  com o arquivo, o campo, o trecho e os diagnósticos daquele campo ainda sem declaração, ou com o
+  aviso de que o arquivo não existe mais no escopo.
+
+### Instruções, documentação e changelog
+
+- A instrução gerenciada do Opus passa a dizer que o inventário de copy guarda o hash de todo
+  arquivo JS/TS do escopo, inclusive scripts sem copy como `scripts/*.mjs`, e que alterar qualquer
+  um deles também exige `opus copy`.
+- Os exemplos da documentação usam identificadores, nomes de action, domínios, eventos e permissões
+  em inglês (`ledger.close`, `ledger:close`, `invoice.issued`); rótulos, mensagens e comentários
+  continuam em pt-BR. O padrão editorial e a lista de verificação da skill `maintain-opus-docs`
+  passam a exigir isso, e um teste do repositório reprova identificadores com palavra em português.
+- Entradas do changelog que já estão na `origin/main` do Opus não mudam mais: uma correção de
+  informação publicada entra como entrada nova. O pre-push e o `pnpm release` do repositório
+  reprovam a alteração.
+
 ## 28.0.0 — 2026-10-13
 
 ### Breaking

package/bin/cli.mjs

@@ -15,7 +15,7 @@ import { cmdGen, helpGen } from './lib/gen.mjs'
 import { cmdDb } from './lib/db.mjs'
 import { scanDir, emptyScanVerdict } from './lib/check.mjs'
 import { log } from './lib/cli-shared.mjs'
-import { checkCopyInventory, writeCopyInventory } from './lib/copy.mjs'
+import { checkCopyInventory, reanchorCopySelectors, writeCopyInventory } from './lib/copy.mjs'
 import { createMonorepo, createProject } from './lib/create.mjs'
 import { initProject, repoRootOf, setupUiFoundation } from './lib/init.mjs'
 import { introspect } from './lib/introspect.mjs'
@@ -63,9 +63,9 @@ async function cmdCheck(dir) {
     log('error', `✗ opus check: nenhuma action encontrada em ${rel} (${files} arquivos .ts); ${verdict.message}`)
     process.exit(1)
   }
-  const viaContrato = contracts > 0 ? ` (${contracts} contrato(s))` : ''
+  const contractSuffix = contracts > 0 ? ` (${contracts} contrato(s))` : ''
   if (findings.length === 0) {
-    log('success', `✓ opus check: ${actions} action(s)${viaContrato}; nenhuma violação encontrada.`)
+    log('success', `✓ opus check: ${actions} action(s)${contractSuffix}; nenhuma violação encontrada.`)
     return
   }
 
@@ -97,10 +97,28 @@ async function cmdMaterializationCheck() {
 async function cmdCopy(dir, flags) {
   const selected = path.resolve(process.cwd(), dir ?? '.')
   const root = (await repoRootOf(selected)) ?? selected
+  if (flags.reanchor) {
+    if (flags.check) {
+      log('error', '✗ opus copy: --reanchor grava o base.json e não combina com --check.')
+      process.exitCode = 1
+      return
+    }
+    if (!reportReanchor(reanchorCopySelectors(root))) {
+      process.exitCode = 1
+      return
+    }
+  }
   const result = flags.check ? checkCopyInventory(root) : writeCopyInventory(root)
   for (const diagnostic of result.diagnostics) {
     log('error', `✗ opus copy: ${diagnostic.source}:${diagnostic.line} — ${diagnostic.message}`)
   }
+  if (result.legacySelectors > 0) {
+    log(
+      'warn',
+      `! opus copy: ${result.legacySelectors} seletor(es) em base.json ainda usam \`line\`, que quebra a cada edição acima dele; ` +
+        'rode `opus copy --reanchor` para ancorá-los pelo conteúdo.',
+    )
+  }
   if (!result.ok) {
     if (result.reason === 'missing') {
       log('error', `✗ opus copy: inventário ausente em ${path.relative(root, result.path)}; rode \`opus copy\` e versione o resultado.`)
@@ -121,6 +139,40 @@ async function cmdCopy(dir, flags) {
   else log('success', `✓ opus copy: ${location} já estava atualizado (${summary}).`)
 }
 
+function reportReanchor(result) {
+  if (!result.ok) {
+    for (const diagnostic of result.diagnostics) {
+      log('error', `✗ opus copy --reanchor: ${diagnostic.source}:${diagnostic.line} — ${diagnostic.message}`)
+    }
+    log('error', '✗ opus copy --reanchor: resolva os problemas de leitura acima antes de reancorar; base.json não foi alterado.')
+    return false
+  }
+  const { converted, realigned, relined, merged, unresolved } = result.report
+  const anchor = (item) => (item.anchor.expression === undefined ? `"${item.anchor.text}"` : `\`${item.anchor.expression}\``)
+  if (converted.length > 0) log('success', `✓ opus copy --reanchor: ${converted.length} seletor(es) passaram a ser ancorados pelo conteúdo.`)
+  // copy.dynamic identifica o alvo pelo campo; exceções e transformações, pelo papel do texto.
+  const target = (item) => (item.list === 'dynamic' ? `\`${item.selector.field}\`` : `(${item.selector.role})`)
+  if (realigned.length > 0) {
+    log('warn', `! opus copy --reanchor: ${realigned.length} âncora(s) quebradas pela mudança de linha foram convertidas; revise cada uma no diff:`)
+    for (const item of realigned) {
+      console.log(`    copy.${item.list}[${item.index}] ${item.selector.source} ${target(item)} linha ${item.from} → ${item.to}: ${anchor(item)}`)
+    }
+  }
+  if (relined.length > 0) {
+    log('warn', `! opus copy --reanchor: ${relined.length} seletor(es) continuam por linha, com a linha corrigida; revise cada um no diff:`)
+    for (const item of relined) {
+      console.log(`    copy.${item.list}[${item.index}] ${item.selector.source} linha ${item.from} → ${item.to}: ${item.reason}`)
+    }
+  }
+  if (merged.length > 0) log('success', `✓ opus copy --reanchor: ${merged.length} declaração(ões) repetida(s) fundida(s) com a idêntica.`)
+  if (unresolved.length > 0) {
+    log('warn', `! opus copy --reanchor: ${unresolved.length} seletor(es) continuam por linha:`)
+    for (const item of unresolved) console.log(`    copy.${item.list}[${item.index}]: ${item.reason}`)
+  }
+  if (!result.changed) log('success', '✓ opus copy --reanchor: nada a converter em base.json.')
+  return true
+}
+
 async function cmdCreate(dir, flags) {
   if (!dir) {
     log('error', 'Uso: opus create <dir> — o nome do diretório vira o nome do app (--monorepo: a raiz do workspace).')
@@ -273,6 +325,10 @@ function parseArgs(argv) {
       flags.json = true
       continue
     }
+    if (arg === '--reanchor') {
+      flags.reanchor = true
+      continue
+    }
     if (arg === '--monorepo') {
       flags.monorepo = true
       continue
@@ -334,6 +390,7 @@ Flags
   --help, -h         Ajuda do comando.
   --check            (copy) Compara sem escrever; falha se o inventário estiver ausente ou
                      desatualizado.
+  --reanchor         (copy) Ancora pelo conteúdo os seletores do base.json que usam linha.
   --json             (introspect, seed) Saída estruturada em JSON.
   --monorepo         (create) Cria a raiz do workspace em vez de um app.
   --config <path>    (gen, db, seed) Caminho do opus.config.ts. Default: ./opus.config.ts.
@@ -483,6 +540,14 @@ comprova que o extrator executou sobre uma fonte.
 
 Flags:
   --check          Compara sem escrever; falha em ausência, drift ou copy dinâmica
+                   sem declaração.
+  --reanchor       Converte os seletores de copy.dynamic, copy.exemptions e
+                   copy.transforms que ainda usam \`line\` para seletores pelo
+                   conteúdo, grava o base.json e regenera o inventário. Só
+                   converte quando há uma declaração para cada alvo, para não
+                   ampliar nenhuma; as que mudaram de linha são listadas para
+                   revisão, e o que não dá para converter com segurança fica
+                   como está. Depois, rode base copy check e revise o diff.
 `)
       return
     }

package/bin/lib/check.mjs

@@ -159,6 +159,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageFooter", new Set(["Page"])],
   ["PageTitle", new Set(["PageHeader", "PageIntro"])],
   ["PageDescription", new Set(["PageHeader", "PageIntro"])],
+  ["PageMeta", new Set(["PageHeader", "PageIntro"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
@@ -171,6 +172,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["SurfaceTitle", new Set(["SurfaceHeader"])],
   ["SurfaceDescription", new Set(["SurfaceHeader"])],
   ["SurfaceMeta", new Set(["SurfaceHeader"])],
+  ["SurfaceCount", new Set(["SurfaceHeader"])],
   ["SurfaceActions", new Set(["SurfaceHeader"])],
   ["DialogHeader", new Set(["DialogContent"])],
   ["DialogBody", new Set(["DialogContent"])],
@@ -181,6 +183,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DialogMedia", new Set(["DialogHeader"])],
   ["DialogTitle", new Set(["DialogHeader", "DialogIntro"])],
   ["DialogDescription", new Set(["DialogHeader", "DialogIntro"])],
+  ["DialogMeta", new Set(["DialogHeader", "DialogIntro"])],
   ["DialogActions", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
   ["DrawerBody", new Set(["DrawerContent"])],
@@ -191,6 +194,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DrawerMedia", new Set(["DrawerHeader"])],
   ["DrawerTitle", new Set(["DrawerHeader", "DrawerIntro"])],
   ["DrawerDescription", new Set(["DrawerHeader", "DrawerIntro"])],
+  ["DrawerMeta", new Set(["DrawerHeader", "DrawerIntro"])],
   ["DrawerActions", new Set(["DrawerHeader"])],
   ["AlertMedia", new Set(["Alert"])],
   ["AlertHeader", new Set(["Alert"])],
@@ -224,7 +228,7 @@ const UI_STRUCTURAL_ROOTS = new Map([
       body: "PageBody",
       footer: "PageFooter",
       headerRequired: false,
-      shorthand: new Set(["title", "description", "actions"]),
+      shorthand: new Set(["title", "description", "meta", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
       // prop removida é cobrada aqui, nas duas formas de composição.
@@ -242,7 +246,14 @@ const UI_STRUCTURAL_ROOTS = new Map([
       // Cada região é opcional, a forma curta convive com SurfaceBody e SurfaceFooter, e sem
       // região nenhuma a Surface é uma caixa de filhos livres (ADR 0045).
       flexible: true,
-      shorthand: new Set(["title", "media", "description", "count", "actions"]),
+      shorthand: new Set([
+        "title",
+        "media",
+        "description",
+        "meta",
+        "count",
+        "actions",
+      ]),
     },
   ],
 ]);
@@ -260,6 +271,10 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "SurfaceTitle",
   "SurfaceDescription",
   "SurfaceMeta",
+  "SurfaceCount",
+  "PageMeta",
+  "DrawerMeta",
+  "DialogMeta",
   "SurfaceActions",
   "AlertMedia",
   "AlertHeader",
@@ -289,10 +304,6 @@ const UI_REMOVED_PROPS = new Map([
       ["layout", "use `Surface` para anatomia visual contínua ou seccionada"],
     ]),
   ],
-  [
-    "Surface",
-    new Map([["meta", "use `count` para o total ao lado do título"]]),
-  ],
   [
     "DialogMedia",
     new Map([
@@ -340,7 +351,7 @@ const UI_REMOVED_COMPONENTS = new Map([
   ],
   ["ContentTitle", "use `SurfaceTitle`"],
   ["ContentDescription", "use `SurfaceDescription`"],
-  ["ContentMeta", "use `SurfaceMeta`"],
+  ["ContentMeta", "use `SurfaceCount`"],
   ["ContentActions", "use `SurfaceActions`"],
   ["ContentBody", "use `SurfaceBody`"],
   ["Card", 'use `Surface framed elevation="raised"`'],
@@ -364,7 +375,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageIntro",
     {
       title: "PageTitle",
-      optional: new Set(["PageIntroActions", "PageDescription"]),
+      optional: new Set(["PageIntroActions", "PageDescription", "PageMeta"]),
       shorthand: new Set(),
     },
   ],
@@ -372,7 +383,11 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "DialogIntro",
     {
       title: "DialogTitle",
-      optional: new Set(["DialogIntroActions", "DialogDescription"]),
+      optional: new Set([
+        "DialogIntroActions",
+        "DialogDescription",
+        "DialogMeta",
+      ]),
       shorthand: new Set(),
     },
   ],
@@ -380,7 +395,11 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "DrawerIntro",
     {
       title: "DrawerTitle",
-      optional: new Set(["DrawerIntroActions", "DrawerDescription"]),
+      optional: new Set([
+        "DrawerIntroActions",
+        "DrawerDescription",
+        "DrawerMeta",
+      ]),
       shorthand: new Set(),
     },
   ],
@@ -393,6 +412,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
         "PageNavigation",
         "PageActions",
         "PageDescription",
+        "PageMeta",
       ]),
       exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
@@ -407,6 +427,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
         "SurfaceMedia",
         "SurfaceDescription",
         "SurfaceMeta",
+        "SurfaceCount",
         "SurfaceActions",
       ]),
       shorthand: new Set(),
@@ -2116,6 +2137,30 @@ export function checkUiStructure(file, text) {
           "ui-structure-removed-component",
         );
       }
+      if (component === "DialogMeta") {
+        let ancestor = node.parent;
+        while (ancestor !== undefined) {
+          if (
+            ts.isJsxElement(ancestor) &&
+            imports.get(jsxLocalName(ancestor)) === "Dialog"
+          ) {
+            const modes = jsxStringAttributeValues(
+              jsxOpening(ancestor),
+              "mode",
+            );
+            if (modes.length === 1 && modes[0] === "alert") {
+              add(
+                node,
+                component,
+                'DialogMeta não está disponível em Dialog com mode="alert"; coloque as informações no corpo do alerta.',
+                "ui-structure-meta",
+              );
+            }
+            break;
+          }
+          ancestor = ancestor.parent;
+        }
+      }
       const parents =
         component === null ? undefined : UI_STRUCTURAL_PARENTS.get(component);
       if (parents !== undefined) {
@@ -2234,6 +2279,37 @@ export function checkUiStructure(file, text) {
         }
       }
 
+      if (
+        [
+          "PageHeader",
+          "PageIntro",
+          "DialogHeader",
+          "DialogIntro",
+          "DrawerHeader",
+          "DrawerIntro",
+          "SurfaceHeader",
+        ].includes(component)
+      ) {
+        const family = component.replace(/(?:Header|Intro)$/, "");
+        const children = directStructuralChildren(node, imports);
+        const metas = children.names.filter(
+          (name) => name === `${family}Meta`,
+        ).length;
+        if (
+          metas > 1 ||
+          (metas > 0 &&
+            !children.names.includes(`${family}Title`) &&
+            !children.hasOpaque)
+        ) {
+          add(
+            node,
+            component,
+            `${component} aceita um único ${family}Meta e exige ${family}Title para exibi-lo.`,
+            "ui-structure-meta",
+          );
+        }
+      }
+
       const header =
         component === null ? undefined : UI_STRUCTURAL_HEADERS.get(component);
       if (header !== undefined) {