synthesisui 0.16.349 → 0.16.351

package/dist/census-pages.js

@@ -0,0 +1,66 @@
+/**
+ * COMO ELE MONTA UMA PÁGINA - a régua única, num módulo só.
+ *
+ * O que o cliente ganha: o planejador de página oferece o esqueleto que ELE já usa - as peças
+ * dele, na ordem em que ele as escreve - em vez dos três layouts que NÓS escrevemos. Ver
+ * `INV-COLETA-12` em `contracts/camada-1-coleta.md`.
+ *
+ * POR QUE ISTO NÃO MORA EM `import.ts`: três lugares precisam da mesma resposta - a varredura do
+ * escopo, a varredura da evidência (`--usage`, que é onde as páginas moram em todo monorepo) e a
+ * FUSÃO de dois escopos medidos. Duas cópias da transcrição seriam duas réguas no dia em que uma
+ * fosse editada, e o teto declarado num arquivo e furado no outro seria um teto que não existe.
+ */
+import { sketchOf } from "./doctor/sketch.js";
+import { transcribe } from "./doctor/transcribe.js";
+/**
+ * QUANTAS PÁGINAS VIAJAM NO CENSO.
+ *
+ * O teto existe pela mesma razão que o de `skipped`: num monorepo o número estoura e o censo
+ * viraria um dump do repositório. Medido em 01/09, o `frontend-hub` tem 145 arquivos de página e
+ * o nosso app 65, então 400 cabe as duas populações inteiras e o corte só aparece em repositório
+ * bem maior que os que a gente mede.
+ *
+ * E QUANDO ELE CORTAR, `pagesTotal` diz quantas eram. Uma tela que contasse `pages.length` diria
+ * 400 e pareceria completa, que é a forma mais barata de um corte silencioso mentir.
+ */
+export const PAGES_MAX = 400;
+/**
+ * UMA PÁGINA DELE, TRANSCRITA - a moldura da raiz e as peças que ela compõe.
+ *
+ * `from` VEM DO SKETCH e não de uma segunda leitura do arquivo: o nó já carrega o especificador
+ * que o import dele declara, e reabrir o arquivo para descobrir o mesmo fato é a falha de
+ * esteira que o dono nomeou em 01/08.
+ */
+export function pageCompositionOf(rel, src, name, declaredValues) {
+    const sketch = sketchOf(src, name);
+    const at = sketch[0];
+    return {
+        file: rel,
+        root: at?.classes
+            ? transcribe(at.classes.split(/\s+/).filter(Boolean), declaredValues).base
+            : {},
+        composes: sketch
+            .filter((n) => /^[A-Z]/.test(n.tag))
+            .map((n) => ({
+            name: n.tag.split(".")[0],
+            ...(n.from ? { from: n.from } : {}),
+            depth: n.depth,
+        })),
+    };
+}
+/**
+ * AS PÁGINAS DE DOIS ESCOPOS MEDIDOS, SOMADAS - e o teto reaplicado sobre a soma.
+ *
+ * Cada escopo mediu arquivos DIFERENTES, então isto é soma e não desempate: nenhuma regra do
+ * primeiro-escopo-vence se aplica a um conjunto disjunto. O que se preserva é o denominador -
+ * `pagesTotal` conta quantas foram VISTAS em cada medição, inclusive as que aquela medição já
+ * havia cortado, senão a soma de dois cortes leria como o total do projeto.
+ */
+export function mergePages(list) {
+    const all = list.flatMap((c) => c.pages ?? []);
+    if (all.length === 0)
+        return {};
+    const seen = list.reduce((n, c) => n + (c.pagesTotal ?? (c.pages ?? []).length), 0);
+    const pages = all.slice(0, PAGES_MAX);
+    return { pages, ...(seen > pages.length ? { pagesTotal: seen } : {}) };
+}

package/dist/commands/import.js

@@ -3,6 +3,7 @@ import { basename, dirname, join, relative, sep } from "node:path";
 import { anatomyFromSketch } from "../anatomy-from-sketch.js";
 import { applyAnatomyPatch, hasEdits, } from "../anatomy-patch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
+import { PAGES_MAX, pageCompositionOf } from "../census-pages.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { declaredElsewhere } from "../declared-elsewhere.js";
 import { architectureGap, architectureRule, componentHome, describeArchitecture, describeChoice, describeGap, detectArchitectures, homeLine, packagingOf, proposeNewHome, resolvesAs, } from "../doctor/architecture.js";
@@ -68,17 +69,12 @@ import { walk, walkAll } from "./doctor.js";
  * nunca o nome do arquivo - e é isso que a faz valer no projeto de alguém que a gente nunca viu.
  */
 /**
- * QUANTAS PÁGINAS VIAJAM NO CENSO.
+ * O TETO DE PÁGINAS, re-exportado de onde a régua inteira mora - ver `census-pages.ts`.
  *
- * O teto existe pela mesma razão que o de `skipped`: num monorepo o número estoura e o censo
- * viraria um dump do repositório. Medido em 01/09, o `frontend-hub` tem 145 arquivos de página e
- * o nosso app 65, então 400 cabe as duas populações inteiras e o corte só aparece em repositório
- * bem maior que os que a gente mede.
- *
- * E QUANDO ELE CORTAR, `pagesTotal` diz quantas eram. Uma tela que contasse `pages.length` diria
- * 400 e pareceria completa, que é a forma mais barata de um corte silencioso mentir.
+ * Ele vive lá porque a FUSÃO de dois escopos precisa reaplicá-lo sobre a soma, e um teto
+ * declarado num arquivo e furado no outro é um teto que não existe.
  */
-export const PAGES_MAX = 400;
+export { PAGES_MAX };
 /**
  * How many distinct values travel, PER KIND.
  *
@@ -770,26 +766,7 @@ export async function takeCensus(root, opts) {
                  * que falta para alguém escrever a próxima (04/08).
                  */
                 if (verdict.why === "route" || verdict.why === "screen") {
-                    const sketch = sketchOf(src, d.name);
-                    const root = sketch[0];
-                    pages.push({
-                        file: rel,
-                        root: root?.classes
-                            ? transcribe(root.classes.split(/\s+/).filter(Boolean), declaredValues).base
-                            : {},
-                        /**
-                         * `from` VEM DO SKETCH e não de uma segunda leitura do arquivo: o nó já carrega o
-                         * especificador que o import dele declara, e reabrir o arquivo para descobrir o
-                         * mesmo fato é a falha de esteira que o dono nomeou em 01/08.
-                         */
-                        composes: sketch
-                            .filter((n) => /^[A-Z]/.test(n.tag))
-                            .map((n) => ({
-                            name: n.tag.split(".")[0],
-                            ...(n.from ? { from: n.from } : {}),
-                            depth: n.depth,
-                        })),
-                    });
+                    pages.push(pageCompositionOf(rel, src, d.name, declaredValues));
                 }
                 skips.push({
                     name: d.name,
@@ -1456,6 +1433,11 @@ export async function takeCensus(root, opts) {
      * not `reports`: an app's classes are choices made from a scale, and folding
      * them into the census would put the average back where the declaration goes.
      *
+     * A ÚNICA COISA QUE ESTE LAÇO ESCREVE ALÉM DA CONTAGEM É `pages`, e a razão é que uma página
+     * não é uma escolha de estilo: é a COMPOSIÇÃO dela - quais peças, em que ordem, sob que
+     * moldura. Ela não entra em `defined`, não declara token e não vota em escala. Ver o bloco
+     * `AS PÁGINAS MORAM AQUI` mais abaixo, com o número das duas populações.
+     *
      * Deliberately its own tally so the LIBRARY QUESTION is asked of the scope
      * alone. Fold the app in first and every export has a count, `isLibrary` reads
      * false, and the crosswalk starts substituting the components it was just
@@ -1548,6 +1530,41 @@ export async function takeCensus(root, opts) {
             // source - so measuring nesting only on the defined loop reported zero
             // companions on a 128-component library (e2e, 01/08).
             readNesting(rel, src, nesting);
+            /**
+             * AS PÁGINAS MORAM AQUI, E ATÉ AGORA O CENSO NÃO GUARDAVA NENHUMA.
+             *
+             * `Census.pages` é como ELE monta uma tela - a moldura da raiz e a ordem das peças -, e é
+             * o único dado a partir do qual alguém escreve a próxima página no vocabulário dele. Ele
+             * só era colhido na varredura do ESCOPO, e o escopo é a biblioteca: uma `packages/ui` não
+             * tem `app/` nem `pages/`, então a resposta era sempre zero. Medido em 01/09 nas duas
+             * populações, com o mesmo `--scope`/`--usage` que o `import` e o `sync` passam:
+             *
+             *     codelevel      0 páginas guardadas · 9 existem  (apps/web 3, apps/landing 6)
+             *     frontend-hub   0 páginas guardadas · 156 existem (apps/web-dashboard)
+             *
+             * Isto NÃO afrouxa a lei da passagem de evidência. Uma página não entra em `defined`, não
+             * doa token e não vota em escala: o que ela doa é COMPOSIÇÃO - quais peças dele seguram
+             * quais telas -, que é exatamente a classe de fato que `--usage` existe para trazer.
+             *
+             * A régua é a mesma do escopo, de propósito: o portão recusa a rota (`route`/`screen`) e
+             * é essa recusa que a identifica como página. Só o que o portão RECUSA por ser tela vira
+             * página, então nada que já é componente é contado duas vezes.
+             */
+            if (/\.(tsx|jsx)$/i.test(rel)) {
+                for (const d of scanDefinitions(rel, src)) {
+                    const verdict = gateComponent({
+                        name: d.name,
+                        file: rel,
+                        source: src,
+                        internal: [...shared, ...uInternal],
+                    });
+                    if (verdict.ok)
+                        continue;
+                    if (verdict.why !== "route" && verdict.why !== "screen")
+                        continue;
+                    pages.push(pageCompositionOf(rel, src, d.name, declaredValues));
+                }
+            }
             // Which PROJECT composes it - the credibility panel's number, per root.
             for (const m of src.matchAll(/<([A-Z][A-Za-z0-9_]*)/g)) {
                 const at = projectsOf.get(m[1]) ?? new Set();
@@ -2000,6 +2017,21 @@ export async function takeCensus(root, opts) {
         ]),
         islandRead: islandClassesRead,
         refused: new Set(skips.map((s) => s.file)),
+        /**
+         * AS ANIMAÇÕES QUE O CENSO CAPTUROU - ver o veredito em `judgeFragments`.
+         *
+         * `keyframes` é o objeto que já viaja no censo e que o compilador emite. Um frame de uma
+         * delas chegou por essa porta, então cobrá-lo como lacuna conta a mesma coisa duas vezes.
+         * A LISTA É A MESMA FUSÃO QUE O CENSO GRAVA, e não a metade de componente.
+         *
+         * `keyframes` sozinho é o que os componentes declaram; `globalKeyframes` é a folha dele, e
+         * é ali que os 35 do codelevel moram - o censo funde os dois na hora de escrever. Ler só o
+         * primeiro aqui declarava capturado um conjunto VAZIO e o conserto não movia nada: a
+         * primeira medição depois de ligar isto deu exatamente os mesmos 130 de antes.
+         *
+         * Se a captura falhar, o frame volta a ser lacuna sozinho, que é a resposta certa.
+         */
+        keyframes: new Set(Object.keys({ ...globalKeyframes, ...keyframes })),
     }, 
     /**
      * AS FORMAS QUE ELE DECLAROU - e é aqui que a declaração dele muda o veredito.

package/dist/doctor/fragments.js

@@ -302,12 +302,24 @@ kind) {
                 continue;
             }
             const selector = selectorOf(open);
+            /**
+             * DE QUAL ANIMAÇÃO ESTE FRAME É - ver `Fragment.inKeyframe`.
+             *
+             * `selectorOf` devolve `0%`, porque o bloco do frame é um seletor comum e o at-rule só
+             * vence quando não há nenhum. O nome fica na pilha e é a única coisa que liga esta
+             * declaração ao keyframe que o censo capturou.
+             */
+            const inKeyframe = open
+                .map((b) => /^@keyframes\s+([^\s{]+)/.exec(b)?.[1])
+                .filter(Boolean)
+                .pop();
             out.push({
                 shape: "css",
                 file,
                 line: i + 1,
                 text: `${selector ? `${selector} ` : ""}{ ${m[1]}: ${m[2].trim()} }`,
                 read: false,
+                ...(inKeyframe ? { inKeyframe } : {}),
                 ...(kind === "global"
                     ? { reason: "shape-not-read" }
                     : kind === "dead"
@@ -440,7 +452,30 @@ forms = []) {
     const wornGlobal = elsewhere?.wornGlobal ?? new Set();
     const islandRead = elsewhere?.islandRead ?? new Map();
     const refused = elsewhere?.refused ?? new Set();
+    const captured = elsewhere?.keyframes ?? new Set();
     return seen.map((f) => {
+        /**
+         * UM FRAME DE UM KEYFRAME CAPTURADO CHEGOU - a mesma família de `wornGlobal` logo abaixo, e a
+         * mesma família de `INV-INTERP-15`: a régua acusava um fato que já estava no censo.
+         *
+         * `0% { opacity: 0 }` não tem leitor de RECEITA e nunca vai ter - um frame não é a decisão de
+         * um componente, é um instante de uma animação. Mas a animação inteira viaja em
+         * `census.keyframes`, com todos os seus frames, e o compilador a emite. Cobrar o frame como
+         * lacuna é contar duas vezes a mesma coisa e chamar a segunda de perda.
+         *
+         * MEDIDO EM 02/09, nas duas populações e com o mesmo `--scope`/`--usage` do produto:
+         *
+         *     codelevel      35 keyframes capturados · 87 de 105 declarações sem leitor eram frames (83%)
+         *     frontend-hub    1 keyframe  capturado ·  0 de   6 eram frames (0%)
+         *
+         * As duas discordam por larga margem, e é isso que decide o desenho: a pergunta não é sobre
+         * volume, é sobre a porta por onde a declaração passou. O nome tem que estar CAPTURADO - um
+         * frame de uma animação que o censo não colheu continua sendo lacuna, porque ali ela é real.
+         */
+        if (f.inKeyframe && captured.has(f.inKeyframe)) {
+            const { reason: _unread, ...rest } = f;
+            return { ...rest, read: true };
+        }
         /**
          * A REGRA DE CLASSE GLOBAL QUE ALGUÉM VESTE FOI LIDA - antes do desvio de
          * `binding`, porque lida é mais forte que ligada. `.root { isolation: isolate }`

package/dist/install-marks.js

@@ -532,7 +532,42 @@ export const CHECKER_SINCE = "0.16.308";
  * si, o campo fica ausente, e ausente ali continua sendo a resposta certa - o `codelevel-ui` dá
  * 0 de 0 contra 145 arquivos de página do `frontend-hub`.
  */
-export const READER_SINCE = "0.16.348";
+/**
+ * 0.16.349 -> 0.16.350 em 01/09 (`INV-COLETA-12`, a metade do MONOREPO): as páginas do app dele
+ * passam a chegar ao censo mesmo quando a leitura foi apontada para a biblioteca.
+ *
+ * O QUE ELE GANHA COM O `sync`: a linha *"N of your components hold up M pages"* - quais peças
+ * dele são a espinha das telas dele. Quem roda `--scope packages/ui --usage apps/web` recebia
+ * ZERO página e o relatório calava as duas seções que falam delas.
+ *
+ * A CORREÇÃO DE UMA FRASE QUE ESTAVA AQUI: "ausente continua sendo a resposta certa para quem
+ * apontou a leitura para uma biblioteca" só valia para quem NÃO passou `--usage`. As páginas
+ * moram no app, e a varredura da evidência lia cada um desses arquivos para contagem e lei e
+ * passava direto pela composição. Medido em 01/09, com o mesmo `--scope`/`--usage` que o
+ * `import` e o `sync` passam:
+ *
+ *     codelevel      0 páginas guardadas · 9 existem  (apps/web 3, apps/landing 6)
+ *     frontend-hub   0 páginas guardadas · 156 existem (apps/web-dashboard)
+ *
+ * QUEM NÃO É AFETADO: quem mede um app inteiro sem escopo - esse caminho já carregava as páginas
+ * desde 0.16.348. E quem aponta para uma biblioteca sem `--usage`: ela não compõe telas dentro de
+ * si, o campo segue ausente, e ali a ausência é a resposta certa de verdade.
+ */
+/**
+ * 0.16.350 -> 0.16.351 em 02/09 (`INV-COLETA-16`): um frame de uma animação que o censo CAPTUROU
+ * deixa de ser contado como declaração sem leitor.
+ *
+ * O QUE ELE GANHA COM O `sync`: o número de cobertura para de contar como perdido o que a
+ * plataforma leu inteiro. `0% { opacity: 0 }` nunca vai ter leitor de RECEITA - um frame não é a
+ * decisão de um componente -, mas a animação viaja em `census.keyframes` e o compilador a emite.
+ *
+ *     codelevel      35 keyframes capturados · shape-not-read 130 -> 18 · CSS lido 35% -> 88%
+ *     frontend-hub    1 keyframe  capturado · shape-not-read   6 ->  6 · nada muda
+ *
+ * QUEM NÃO É AFETADO: quem não escreve `@keyframes`. E quem escreve um que a captura NÃO alcançou -
+ * ali o frame continua sendo lacuna, porque ali a perda é real.
+ */
+export const READER_SINCE = "0.16.351";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/merge-census.js

@@ -1,3 +1,4 @@
+import { mergePages } from "./census-pages.js";
 import { gapReason } from "./doctor/architecture.js";
 const asRecord = (v) => (v ?? {});
 /** Nome do escopo para as mensagens - `.` quando a medição não escopou nada. */
@@ -296,6 +297,25 @@ export function mergeCensus(list) {
         out.conventions = conventions;
     if (architectures && architectures.length > 0)
         out.architectures = architectures;
+    /**
+     * AS PÁGINAS DOS ESCOPOS SOMAM - ver `mergePages` em `census-pages.ts`.
+     *
+     * `out` nasce de um spread do PRIMEIRO censo e depois é montado campo a campo, então `pages`
+     * do primeiro escopo viajava de carona e a dos SEGUINTES caía inteira, sem uma linha dizendo
+     * isso. Com um escopo só o defeito não aparece (a fusão de uma lista devolve o próprio censo),
+     * e é por isso que ele sobreviveu: o caminho que o expõe é `--scope A --scope B`, que existe
+     * justamente para o sistema que mora em dois pacotes.
+     *
+     * `pagesTotal` também precisava ser recontado: herdado do primeiro, ele descrevia uma medição
+     * e era lido como o total do projeto.
+     */
+    const merged = mergePages(list);
+    delete out.pages;
+    delete out.pagesTotal;
+    if (merged.pages)
+        out.pages = merged.pages;
+    if (merged.pagesTotal)
+        out.pagesTotal = merged.pagesTotal;
     if (gaps.length > 0)
         out.architectureGaps = gaps;
     if (newComponentHome)

package/package.json

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