synthesisui 0.16.326 → 0.16.328

package/dist/anatomy-from-sketch.js

@@ -318,7 +318,24 @@ export function anatomyFromSketch(sketch, defines,
  * from `recharts: ^2.12.0`, since both are spelled the same way. See
  * `frontierOf`.
  */
-versionOf) {
+versionOf, 
+/**
+ * QUAL NÓ JÁ FOI ABSORVIDO EM `base` - ver `CensusLook.consumedAt`, onde o fato nasce.
+ *
+ *     number     consuma EXATAMENTE esse nó
+ *     "none"     a coleta mediu e não absorveu nenhum - não consuma nenhum
+ *     undefined  censo LEGADO - a regra antiga, byte a byte
+ *
+ * `undefined` NUNCA é `"none"`: um censo gravado antes desta medição existir não disse que não
+ * absorveu nada; ele não disse nada. Tratá-lo como `"none"` mudaria retroativamente a leitura de
+ * 386 componentes num app real, dos quais 26 mudariam de fato - e mudar dado antigo sem uma nova
+ * medição é a definição de reinterpretar o passado.
+ *
+ * Opcional porque 37 dos 39 chamadores são specs que montam um sketch à mão e testam a regra
+ * legada de propósito. Os chamadores de PRODUÇÃO são dois, e `anatomy-consumed.guard.spec.ts`
+ * nomeia os dois: um parâmetro opcional que se pode esquecer é o defeito que este item desfaz.
+ */
+consumedAt) {
     const notes = [];
     const libraries = [];
     if (!Array.isArray(sketch) || sketch.length === 0)
@@ -662,10 +679,33 @@ versionOf) {
      * root arriving as a sibling (dono, 03/08). The reader stamps which node the
      * component returns - see `SketchNode.root`.
      */
-    const stamped = sketch.findIndex((node) => node?.root);
-    const top = stamped >= 0 ? stamped : roots.length > 0 ? roots[0] : 0;
+    /**
+     * ═══ DADO NOVO NÃO DEDUZ NADA (28/08, T43-b) ═══
+     *
+     * A linha abaixo era uma dedução por POSIÇÃO - "o nó carimbado, senão o primeiro de d0, senão o
+     * zero" - e ela discordava do coletor exatamente onde a âncora falha. Num componente que devolve
+     * um Fragment o coletor não absorve nada em `base`, e esta linha consumia um nó mesmo assim: as
+     * classes daquele nó caíam no vazio. Medido no `frontend-hub`: 8 componentes.
+     *
+     * Com o fato, não há o que deduzir. Sem o fato - censo legado - a dedução antiga fica INTEIRA,
+     * porque um censo velho não disse "não absorvi nada": ele não disse nada.
+     */
+    const top = consumedAt === "none"
+        ? -1
+        : typeof consumedAt === "number"
+            ? consumedAt
+            : /** LEGADO, e esta é a regra antiga sem uma vírgula mudada. */
+                (() => {
+                    const stamped = sketch.findIndex((node) => node?.root);
+                    return stamped >= 0 ? stamped : roots.length > 0 ? roots[0] : 0;
+                })();
+    /**
+     * `top === -1` é "nenhum nó foi consumido", e então TODO nó de d0 é emitido com as classes dele -
+     * que é o conserto: nada se perde e nada é inventado. `roots.filter(at => at !== top)` já devolve
+     * todos quando `top` não é um índice, então a mesma linha serve aos dois casos.
+     */
     const read = [
-        ...(kids[top] ?? []).flatMap((child) => build(child, 0)),
+        ...(top >= 0 ? (kids[top] ?? []).flatMap((child) => build(child, 0)) : []),
         ...roots.filter((at) => at !== top).flatMap((sibling) => build(sibling, 0)),
     ];
     /**
@@ -678,7 +718,7 @@ versionOf) {
      * as empty boxes: a Chat that says nothing about messages reads as a component
      * we failed to extract (dono, 01/08).
      */
-    const rootNode = sketch[top];
+    const rootNode = top >= 0 ? sketch[top] : undefined;
     if (rootNode?.slot) {
         const only = EXPECTS[String(rootNode.tag ?? "").toLowerCase()];
         /**

package/dist/commands/doctor.js

@@ -8,7 +8,7 @@ import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, }
 import { checkContracts } from "../doctor/contract-check.js";
 import { describeMissing, missingDependencies, summarizeMissing, } from "../doctor/dependencies.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
-import { appendEvent, COVERAGE_RULE, readEvents, suggestionsFrom, summarize, } from "../doctor/ledger.js";
+import { appendEvent, COVERAGE_RULE, readEvents, suggestionsFrom, unrepresentedFrom, summarize, } from "../doctor/ledger.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { checkableName, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { DEFAULT_ROOT_PX, rootSizeOf, saidOfRoot, } from "../doctor/root-size.js";
@@ -938,6 +938,8 @@ export async function doctor(opts) {
                 ...(d.repeats.some((r) => nameToWrite(r))
                     ? { matched: suggestionsFrom(d.repeats) }
                     : {}),
+                /** SEMPRE, inclusive vazio - ver `CheckEvent.unrepresentedMatches`: o vazio é a medição. */
+                unrepresentedMatches: unrepresentedFrom(d.findings, suggestionsFrom(d.repeats)),
             }).catch(() => { });
         console.log("");
         if (opts.fix) {
@@ -1149,6 +1151,15 @@ export async function doctor(opts) {
             ...(d.repeats.some((r) => nameToWrite(r))
                 ? { matched: suggestionsFrom(d.repeats) }
                 : {}),
+            /**
+             * E AS OCORRÊNCIAS QUE OS PARES NÃO CARREGAM - ver `CheckEvent.unrepresentedMatches`.
+             *
+             * ESCRITO SEMPRE, inclusive como lista vazia, e é a única forma de o campo significar alguma
+             * coisa: ausente quer dizer "um CLI que não media isto", e `[]` quer dizer "mediu e não há".
+             * Escrevê-lo condicionalmente faria os dois estados virarem um, e um cliente com ledger antigo
+             * passaria a parecer um cliente medido sem achados.
+             */
+            unrepresentedMatches: unrepresentedFrom(d.findings, suggestionsFrom(d.repeats)),
         });
     }
     if (hasSystem && fullRun) {

package/dist/commands/import.js

@@ -829,6 +829,22 @@ export async function takeCensus(root, opts) {
                     if (esize > 0 || etag || esketch.length > 0) {
                         looks[extra.name] = {
                             ...(esketch.length > 0 ? { sketch: esketch } : {}),
+                            /**
+                             * O MESMO FATO NO SEGUNDO COMPONENTE DO ARQUIVO - ver `CensusLook.consumedAt`.
+                             *
+                             * Escrever só no caminho primário deixaria metade dos looks de um arquivo com dois
+                             * componentes no estado LEGADO para sempre, e o deriver voltaria a deduzir por posição
+                             * exatamente neles. Um campo que só metade dos caminhos escreve é um campo que mente
+                             * sobre o que a medição cobriu.
+                             */
+                            ...(esketch.length > 0
+                                ? {
+                                    consumedAt: (() => {
+                                        const at = esketch.findIndex((n) => n.root);
+                                        return at >= 0 ? at : "none";
+                                    })(),
+                                }
+                                : {}),
                             /**
                              * Ver `CensusLook.aside` - o segundo componente do arquivo também.
                              *
@@ -1030,6 +1046,23 @@ export async function takeCensus(root, opts) {
                  * the owner's rule, adopted verbatim (dono, 01/08).
                  */
                 const sketch = sketchOf(src, found[0].name);
+                /**
+                 * QUAL NÓ FOI ABSORVIDO EM `base` - o fato, medido onde ele acontece. Ver
+                 * `CensusLook.consumedAt`.
+                 *
+                 * `rootClasses` acha o elemento pela âncora `returnAt` → primeiro `<`, e `sketchOf` carimba
+                 * `root` com a MESMA âncora. Quando ela acha um elemento, é o className DELE que entra em
+                 * `base` - com classes ou sem, e sem é o caso comum. Quando ela não acha (retorno em
+                 * Fragment, ou `returnAt` = -1), nada é absorvido e nenhum nó pode ser consumido.
+                 *
+                 * Provado nos dois repositórios reais, 139 arquivos: NUNCA existe um caso sem carimbo em que
+                 * `rootClasses` tenha lido alguma classe. As duas leituras falham juntas, sempre.
+                 *
+                 * E o carimbo `root` continua sendo outra coisa - a raiz ESTRUTURAL. Este campo é derivado
+                 * dele hoje porque hoje eles coincidem; ele não passa a ser ele.
+                 */
+                const consumedIndex = sketch.findIndex((n) => n.root);
+                const consumed = consumedIndex >= 0 ? consumedIndex : "none";
                 /**
                  * THE CSS THE COMPONENT CARRIES INSIDE ITSELF.
                  *
@@ -1192,6 +1225,8 @@ export async function takeCensus(root, opts) {
                             }
                             : {}),
                         ...withoutDark,
+                        /** SEMPRE, inclusive `"none"` - ver `CensusLook.consumedAt`: o vazio é a medição. */
+                        consumedAt: consumed,
                         base,
                         states,
                         /**
@@ -3545,7 +3580,9 @@ quiet = false) {
          */
         const derived = Array.isArray(anatomy) && anatomy.length > 0
             ? null
-            : anatomyFromSketch(looks[component]?.sketch, resolveRef, (pkg) => deps[pkg]);
+            : anatomyFromSketch(looks[component]?.sketch, resolveRef, (pkg) => deps[pkg], 
+            /** O fato medido na coleta, ou `undefined` num look legado - ver `CensusLook.consumedAt`. */
+            looks[component]?.consumedAt);
         if (derived?.read.length) {
             for (const note of derived.notes)
                 notes.add(note);

package/dist/doctor/ledger.js

@@ -36,6 +36,17 @@ export const LEDGER_FILE = "ledger.jsonl";
  * inteiro o que decide alguma coisa.
  */
 const MATCHED_CAP = 300;
+/**
+ * O MESMO TETO PARA AS OCORRÊNCIAS, e aqui ele corta MAIS, porque cada entrada é uma ocorrência e
+ * não um grupo. Medido antes de escolher o número: 1 no escopo que o repositório real mede, 2 no
+ * repositório inteiro - o teto está três ordens de grandeza acima do caso real, e existe para que
+ * um projeto grande não escreva um evento de centenas de KB no ledger dele.
+ *
+ * O corte é SILENCIOSO neste arquivo, e isso está dito em vez de calado: sem um campo de contagem
+ * não há onde escrever "e mais N". Se algum dia um projeto real encostar no teto, a resposta é um
+ * campo que declare o que ficou de fora - nunca subir o número e seguir.
+ */
+const UNREPRESENTED_CAP = 300;
 /**
  * Os pares a mandar, do agregado que o doctor já monta.
  *
@@ -64,6 +75,49 @@ export function suggestionsFrom(repeats) {
         count: r.count,
     }));
 }
+/**
+ * A IDENTIDADE ESTRUTURAL DE UMA OCORRÊNCIA - a MESMA chave que agrupa os repeats em `scan.ts`.
+ *
+ * Comparar por texto de apresentação (`shown`) seria julgar o nome que a pessoa leu em vez do fato
+ * medido, que é o acoplamento que o #1174 removeu. A família faz parte da identidade: o mesmo
+ * literal em duas famílias são dois fatos diferentes, e só um deles pode ser coincidência.
+ */
+const identityOf = (f) => `${f.kind}:${f.literal.toLowerCase()}`;
+/**
+ * AS OCORRÊNCIAS QUE `matched` NÃO TRANSPORTOU - ver `CheckEvent.unrepresentedMatches`.
+ *
+ * A regra é ESTRUTURAL e nunca semântica: entra a ocorrência que casou com um token nosso e cuja
+ * identidade não está entre as entradas que `matched` de fato carregou. Nada aqui olha
+ * `finding.crossFamily` - filtrar por aquele veredito congelaria a régua do dia da coleta e
+ * impediria uma régua futura de reavaliar o que este CLI decidiu não mandar.
+ *
+ * `matched` entra como ARGUMENTO, e não é detalhe: o que importa é o que foi de fato transportado,
+ * depois do filtro e depois do teto. Um repeat que existiu e foi cortado sai daqui como ocorrência,
+ * porque do ponto de vista de quem lê ele não chegou - e é isso que o campo promete.
+ */
+export function unrepresentedFrom(findings, matched) {
+    const carried = new Set(matched.map(identityOf));
+    const out = [];
+    for (const f of findings) {
+        /** Sem token nosso não houve match nosso, e não há o que a régua de família possa julgar. */
+        if (!f.token)
+            continue;
+        if (carried.has(identityOf(f)))
+            continue;
+        if (out.length >= UNREPRESENTED_CAP)
+            break;
+        out.push({
+            literal: f.literal,
+            kind: f.kind,
+            token: f.token,
+            file: f.file,
+            line: f.line,
+            ...(f.theirToken ? { theirToken: f.theirToken } : {}),
+            ...(f.fontRelative ? { fontRelative: true } : {}),
+        });
+    }
+    return out;
+}
 const ledgerPath = (root) => join(root, "_synthesisui", LEDGER_FILE);
 /** Keep the file from growing forever: past ~1MB, keep the newest half. A
  *  trend needs recent history, not an archive. */

package/dist/install-marks.js

@@ -352,7 +352,16 @@ export const CHECKER_SINCE = "0.16.308";
  * nenhum dos 22 apps dourados tem componente com nome de tag de SVG. Quem tem só vê a correção
  * depois de remedir.
  */
-export const READER_SINCE = "0.16.324";
+/**
+ * 0.16.324 -> 0.16.328 em 28/08 (T43-b): o censo passou a carregar `consumedAt` - qual nó do sketch
+ * teve as classes absorvidas em `base`, ou `"none"` quando nenhum teve.
+ *
+ * A marca sobe porque a medição ANTERIOR não tem como produzir o conserto: sem o campo o look cai no
+ * estado legado e o deriver volta a deduzir por posição, que é o defeito. Medido no app real: 8
+ * componentes que devolvem um Fragment recuperam as classes que hoje caem no vazio, e 386 de 386
+ * looks legados leem exatamente como liam.
+ */
+export const READER_SINCE = "0.16.328";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/naming-queue.js

@@ -59,7 +59,10 @@ export function namingQueue(looks, defines, versionOf) {
         const sketch = looks[component]?.sketch;
         if (!Array.isArray(sketch) || sketch.length === 0)
             continue;
-        const derived = anatomyFromSketch(sketch, defines, versionOf);
+        const derived = anatomyFromSketch(sketch, defines, versionOf, 
+        /** O fato medido na coleta, ou `undefined` num look legado - ver `CensusLook.consumedAt`. */
+        looks[component]
+            ?.consumedAt);
         if (derived.read.length === 0)
             continue;
         components += 1;

package/dist/populations.spec-input.js

@@ -39,6 +39,60 @@ export const FRONTEND_HUB_CENSUS = join(POPULATIONS, "frontend-hub.census.json")
  * que a jornada é conferida na tela.
  */
 export const CODELEVEL_CENSUS = join(POPULATIONS, "codelevel-ui.census.json");
+/**
+ * O HISTÓRICO DO DOCTOR - a única entrada destas provas que NÃO se deriva de um censo.
+ *
+ * O que ele carrega e o censo não: os PARES que o doctor casou (`matched`) e o placar que ele
+ * fechou (`crossFamily`). O censo é a leitura do CÓDIGO num instante; o ledger é a história das
+ * EXECUÇÕES - nenhum dos dois se produz a partir do outro.
+ *
+ * Congelado em 28/08 porque só existia na máquina do dono, e porque as provas que dependem dele
+ * ficariam órfãs no dia em que aquela pasta sumisse - foi exatamente assim que oito provas do
+ * `signalui` viraram provas apagadas. Ver `fixtures/populations/README.md`.
+ */
+export const CODELEVEL_LEDGER = join(POPULATIONS, "codelevel-ui.ledger.jsonl");
+/**
+ * OS DOIS DOCUMENTOS HISTÓRICOS - a exceção autorizada à regra do derivável (dono, 28/08).
+ *
+ * A regra desta pasta continua valendo para artefato ATUAL: um `design-system.json` de hoje se
+ * deriva do censo, e congelá-lo criaria uma segunda fonte de verdade que envelhece calada.
+ *
+ * Um documento PUBLICADO no passado é outra coisa. A cadeia só sabe produzir o presente: derivar
+ * hoje o que foi publicado em duas versões diferentes devolve o mesmo documento duas vezes, e a
+ * propriedade que o `change-preview` protege - que cada lado do par desenhe com o CSS DA SUA
+ * versão - deixaria de ter o que comparar. O passado não é derivável nem hoje nem nunca.
+ *
+ * PROVENIÊNCIA. `~/personal/codelevel-monorepo/_synthesisui/ds/codelevel/{v2,v3}/design-system.json`,
+ * escritos em 26/08/2026 pelo próprio produto - `v2` por `import`, `v3` por `sync` (`source.by` em
+ * todas as 62 receitas). Copiados byte a byte pelo VALOR: só a formatação foi compactada, e um
+ * spec assere que o objeto lido é idêntico ao original. Nenhum valor foi alterado para caber num
+ * teste, e nenhuma versão foi gerada artificialmente.
+ *
+ * O PAR FOI ESCOLHIDO PELA PROPRIEDADE, e a escolha foi medida nos três pares possíveis:
+ *
+ *     v1 -> v2    0 componentes com declaração movida, 0 que mudaram sem pintar - não serve
+ *     v2 -> v3   20 componentes com declaração movida, 42 que mudaram sem pintar
+ *     v1 -> v3   idêntico ao v2 -> v3
+ *
+ * INSPECIONADOS ANTES DE VERSIONAR, e nada precisou ser mascarado - o que importa, porque mascarar
+ * mudaria o documento:
+ *
+ *     credenciais / bearer / api-key / password    nenhuma
+ *     caminhos absolutos ou de máquina             nenhum
+ *     e-mails ou identificadores pessoais          nenhum
+ *     URLs                                         uma, o namespace de SVG do W3C
+ *
+ * O que eles CARREGAM, e está dito em vez de calado: a narrativa e o tagline do produto (texto de
+ * marketing do próprio dono), os caminhos RELATIVOS dos arquivos de origem dentro do repositório
+ * (`packages/ui/src/...`, os mesmos que o censo congelado ao lado já carrega) e, no `v3`, um
+ * carimbo `meta.repairs` com data.
+ *
+ * E SÃO EVIDÊNCIA HISTÓRICA, NUNCA FONTE NORMATIVA. Nenhuma regra do SynthesisUI pode ler daqui o
+ * que é certo - nem um nome de componente, nem um valor, nem uma convenção. Eles existem para que
+ * uma prova tenha DOIS instantes do mesmo sistema para comparar, e é só isso.
+ */
+export const CODELEVEL_DOCUMENT_OLDER = join(POPULATIONS, "codelevel-ui.v2.document.json");
+export const CODELEVEL_DOCUMENT_NEWER = join(POPULATIONS, "codelevel-ui.v3.document.json");
 /**
  * OS REPOSITÓRIOS VIVOS - e estes NÃO estão congelados, de propósito.
  *

package/dist/repo-state.js

@@ -25,7 +25,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { readEvents } from "./doctor/ledger.js";
+import { readEvents, } from "./doctor/ledger.js";
 /**
  * O estado de um slug neste projeto, ou nada quando não há `.lock`.
  *
@@ -83,6 +83,15 @@ export async function repoStateOf(projectRoot, slug, cli) {
         ...(doctor?.matched && doctor.matched.length > 0
             ? { matched: doctor.matched }
             : {}),
+        /**
+         * `Array.isArray` E NUNCA `length > 0` - a linha acima é o contraexemplo, e ela está certa para
+         * `matched`, que não distingue "não mediu" de "mediu zero". Este campo distingue, e é a razão de
+         * ele existir: `[]` é uma medição, e transformá-la em ausência faria um cliente com CLI novo
+         * parecer um cliente com ledger antigo.
+         */
+        ...(Array.isArray(doctor?.unrepresentedMatches)
+            ? { unrepresentedMatches: doctor.unrepresentedMatches }
+            : {}),
         ...(runs.length > 0 ? { runs } : {}),
         ...(typeof lock?.fetchedAt === "string"
             ? { installedAt: lock.fetchedAt }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.326",
+  "version": "0.16.328",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {