synthesisui 0.16.354 → 0.16.356

package/dist/doctor/style-ledger.js

@@ -150,10 +150,38 @@ const BECAUSE = {
  * look, e reter as duas cópias é o que dobraria o censo.
  */
 /**
- * TETO DE FORMAS POR GRUPO. Medido: as 706 folhas do app inteiro comprimem 18 473 declarações em
- * 194 formas - 64 por grupo cobre as populações reais com folga e segura o patológico.
+ * TETO DE FORMAS POR GRUPO - o MESMO número do texto, e a razão de serem iguais é a razão de os dois
+ * existirem: proteger contra um censo patológico, não escolher quanto do repositório dele viaja.
+ *
+ * ERA 64, sobre uma medição que não era a deste campo: *"as 706 folhas do app inteiro comprimem
+ * 18 473 declarações em 194 formas - 64 por grupo cobre as populações reais com folga"*. As 194 são
+ * do APP INTEIRO; o teto é POR GRUPO, e um grupo concentra muito mais. Remedido em 03/09, com o
+ * teto solto, o maior grupo de cada população:
+ *
+ *     web-subscribe           css/component-not-admitted   1 480 formas
+ *     wellcell-official-app   css/shape-not-read             752
+ *     frontend-hub/dashboard  css/component-not-admitted     245
+ *     web-onboarding          css/shape-not-read              15
+ *
+ * Com 64, o que chegava era 424 de 2 481 formas no `web-subscribe` (17%), 124 de 812 no `wellcell`
+ * (15%) e 230 de 411 no `frontend-hub` (56%).
+ *
+ * POR QUE A FORMA E NÃO O TEXTO, que é a escolha que este número representa. Subir `DISTINCT_CAP`
+ * para cobrir os textos do `web-subscribe` custaria **+1,12 MB** num censo de 1,50 MB (+75%), e
+ * levaria o texto-fonte dele de 67% para 81% do arquivo - 18 426 declarações verbatim, que é o CSS
+ * dele praticamente inteiro. Cobrir todas as FORMAS custa **+93 KB** (+6%), doze vezes menos, e
+ * entrega o que um leitor novo precisa: `form-identity` existe porque *"quem ensina a ler
+ * `text-<word>-<n>` ensinou as centenas de uma vez"*.
+ *
+ * E A FORMA TEM OS VALORES ABSTRAÍDOS - `background: <gradient>`, `text-<word>-<n>` -, então
+ * carregá-la inteira não muda a resposta que a gente dá quando um cliente pergunta se guardamos o
+ * código dele. Carregar o texto inteiro mudaria.
+ *
+ * O TETO CONTINUA EXISTINDO, e `formsTotal` continua dizendo quando ele corta (`INV-COB-14`): 4 096
+ * é 2,7x o maior grupo medido, o que segura o patológico sem dimensionar pela amostra - que foi
+ * exatamente o erro que escolheu 4096 para o texto em 24/08 e 64 para a forma.
  */
-const FORM_CAP = 64;
+const FORM_CAP = DISTINCT_CAP;
 export function buildLedger(cli, seen, 
 /**
  * OS NOMES QUE ELE DECLARA - para a contagem de `withTheirTokens`.
@@ -185,6 +213,7 @@ declared) {
             seenFiles: new Set(),
             withTheirTokens: 0,
             formTally: new Map(),
+            distinctTexts: new Set(),
         };
         group.uses += 1;
         group.seenFiles.add(f.file);
@@ -218,30 +247,57 @@ declared) {
         /**
          * SÓ O QUE UM LEITOR ALCANÇA, E SÓ TEXTO DISTINTO - as duas restrições vieram de medir.
          *
-         * `value-not-read` diz que a forma FOI lida e o valor está fora das escalas deles - texto não
-         * ensina nada a leitor nenhum. `computed` é montado em runtime e não existe na fonte.
-         * `component-not-admitted` é o portão, não a leitura. Sobram os dois de `A_READER_REACHES`.
+         * SOBRA O QUE `A_READER_REACHES` NOMEIA, e o que ele nomeia mudou duas vezes - este comentário
+         * ficou parado na primeira. Ele dizia *"`value-not-read` … texto não ensina nada a leitor
+         * nenhum … `component-not-admitted` é o portão, não a leitura. Sobram os DOIS"*, e os dois
+         * excluídos ali entraram no conjunto depois (11/08 e 24/08), somando quatro. Quem lesse isto
+         * concluiria que o maior grupo de todos - 96% do volume não interpretado - não carrega texto,
+         * quando ele carrega. O conjunto é a fonte única; esta frase não repete os nomes de propósito.
+         *
+         * `computed` continua fora, e por uma razão que não envelhece: é montado em runtime e não
+         * existe na fonte, então não há texto para guardar.
          *
          * E TEXTO DISTINTO, porque a primeira versão disto reprovou no spec do repo vivo: guardar todo
          * fragmento deu 723 215 bytes no dashboard dele, contra um teto de 65 536. Oito mil cópias da
          * mesma string não ensinam mais que uma - o que um leitor precisa é da variedade de FORMAS.
          *
-         * O TETO SUBIU PARA 4096 EM 24/08, e o número saiu de uma medição e não de um palpite: a
-         * variedade real do `frontend-hub` é de ~1 500 textos distintos sobre 10 825 usos, então 4096
-         * cabe a população inteira daquele repositório com folga e continua sendo um teto de verdade
-         * para um caso patológico.
+         * O TETO SUBIU PARA 4096 EM 24/08 sobre uma medição que EXTRAPOLOU: *"a variedade real do
+         * `frontend-hub` é de ~1 500 textos distintos sobre 10 825 usos"*, contada nos 400 primeiros
+         * arquivos de module. Remedida em 03/09 no repositório inteiro, com o teto solto, ela é 6 394 -
+         * quatro vezes o estimado. O teto corta, e corta a maior parte:
+         *
+         *     web-subscribe          css/component-not-admitted   9 722 distintos, 4 096 viajam
+         *     web-subscribe          css/shape-not-read           8 016 distintos, 4 096 viajam
+         *     frontend-hub/dashboard css/component-not-admitted   6 394 distintos, 4 096 viajam
+         *
+         * A FRASE QUE ESTAVA AQUI DIZIA QUE ISSO ERA VISÍVEL: *"`uses` continua contando tudo, então a
+         * diferença entre o contado e o que viajou permanece visível em vez de silenciosa"*. Não é.
+         * `uses` conta ocorrências e `unreadable` guarda distintos, então aquela diferença existe
+         * sempre, por repetição, e não muda de forma quando o teto entra. Quem paga é a
+         * re-interpretação, que roda sobre o censo guardado prometendo alcançar quem já importou sem
+         * re-medir: ela processa 4 096 de 9 722 e relata sucesso.
          *
-         * `uses` continua contando tudo, então a diferença entre o contado e o que viajou permanece
-         * visível em vez de silenciosa - e é ela que a tela mostra quando o teto corta.
+         * QUEM DECLARA O CORTE AGORA É `distinct`, escrito na linha de baixo e sempre presente. ESTE
+         * NÚMERO NÃO É O CONSERTO DO TETO - subir 4096 é uma decisão de tamanho de censo, medida e
+         * entregue à parte. Declarar vem primeiro; ampliar vem depois, e as duas são separadas porque
+         * uma é honestidade e a outra é custo.
          */
-        if (A_READER_REACHES.has(reason) &&
-            group.unreadable.length < DISTINCT_CAP &&
-            !group.unreadable.some((u) => u.text === f.text))
-            group.unreadable.push({
-                file: f.file,
-                line: f.line,
-                text: f.text.replace(/\s+/g, " ").trim().slice(0, 400),
-            });
+        if (A_READER_REACHES.has(reason) && !group.distinctTexts.has(f.text)) {
+            /**
+             * CONTAR VEM ANTES DE CABER, e essa ordem é a correção inteira.
+             *
+             * O texto entra no conjunto mesmo quando o teto já fechou: é assim que `distinct` sabe
+             * dizer 9 722 enquanto `unreadable` carrega 4 096, e é a única diferença entre um teto
+             * declarado e um teto silencioso. Inverter as duas linhas devolve o defeito.
+             */
+            group.distinctTexts.add(f.text);
+            if (group.unreadable.length < DISTINCT_CAP)
+                group.unreadable.push({
+                    file: f.file,
+                    line: f.line,
+                    text: f.text.replace(/\s+/g, " ").trim().slice(0, 400),
+                });
+        }
         groups.set(key, group);
     }
     return {
@@ -250,18 +306,36 @@ declared) {
         counted,
         interpreted,
         unread: [...groups.values()]
-            .map(({ seenFiles, withTheirTokens, formTally, ...group }) => ({
+            .map(({ seenFiles, withTheirTokens, formTally, distinctTexts, ...group }) => ({
             ...group,
             files: seenFiles.size,
+            /**
+             * QUANTOS TEXTOS DISTINTOS EXISTEM - incondicional, e é isso que o torna legível.
+             *
+             * Os outros campos deste objeto somem quando são zero, porque um zero repetido em todo
+             * grupo é ruído. Este não pode: quem lê precisa separar "o censo mediu e deu zero" de "o
+             * censo é anterior a este campo", e um campo que desaparece funde os dois casos. O tipo o
+             * declara opcional pela segunda razão, nunca pela primeira.
+             */
+            distinct: distinctTexts.size,
             /** Ausente quando é zero: um campo zerado em todo grupo é ruído em cada relatório. */
-            ...(withTheirTokens && withTheirTokens > 0 ? { withTheirTokens } : {}),
+            ...(withTheirTokens && withTheirTokens > 0
+                ? { withTheirTokens }
+                : {}),
             /**
              * AS FORMAS DESTE GRUPO, com os usos de cada uma - ver `form-identity.ts` (item 12).
-             * Ordenadas por uso: a primeira é a pergunta que mais vale a pena fazer. O teto corta o
-             * patológico, e `uses` do grupo continua contando tudo - o corte fica visível.
+             * Ordenadas por uso: a primeira é a pergunta que mais vale a pena fazer.
+             *
+             * `formsTotal` existe pela MESMA razão que `distinct`, e o comentário que estava aqui
+             * afirmava o contrário: *"o teto corta o patológico, e `uses` do grupo continua contando
+             * tudo - o corte fica visível"*. `uses` conta OCORRÊNCIAS e o teto corta FORMAS, então
+             * `uses` alto convive com qualquer número de formas e não denuncia corte nenhum. Medido em
+             * 03/09: cinco grupos em três populações relatam exatamente 64 formas, que é o teto - e
+             * nenhum deles diz quantas ficaram de fora.
              */
             ...(formTally.size > 0
                 ? {
+                    formsTotal: formTally.size,
                     forms: [...formTally.entries()]
                         .sort((a, b) => b[1] - a[1])
                         .slice(0, FORM_CAP)
@@ -328,6 +402,22 @@ values) {
             ? ` — and ${g.withTheirTokens} of them already wear a token you declare, so their value is in the system`
             : "";
         lines.push(`  ${g.uses} ${g.shape}${g.uses === 1 ? "" : "s"} in ${g.files} file${g.files === 1 ? "" : "s"} - ${g.because}${theirs}`);
+        /**
+         * A TERCEIRA FRASE, QUANDO O TETO CORTOU - e ela existe para não deixar o cliente descobrir
+         * sozinho (lei 8: lacuna declarada é confiança, lacuna calada é bug).
+         *
+         * Ela só aparece quando corta, ao contrário do campo `distinct`, e a assimetria é de propósito:
+         * um campo ausente no censo é ambíguo para quem lê JSON e precisa do valor incondicional; uma
+         * linha a mais em TODO grupo de um relatório de 108 linhas é ruído que treina a pessoa a rolar
+         * sem ler (dono, 09/08).
+         *
+         * O QUE ELA NÃO FAZ é prometer o desfecho - mesma correção que `shape-not-read` recebeu em
+         * 24/08. Ela diz quantos textos viajam e o que isso significa para um leitor que a gente
+         * publique depois; para onde vai o resto depende de uma decisão de tamanho de censo que não é
+         * do cliente e ainda não foi tomada.
+         */
+        if (g.distinct !== undefined && g.distinct > g.unreadable.length)
+            lines.push(`      of ${g.distinct} distinct texts here, ${g.unreadable.length} travel with the census - a reader we publish later reaches those without you re-measuring, and the remaining ${g.distinct - g.unreadable.length} need this scan run again`);
         for (const e of g.examples)
             lines.push(`      ${e.file}:${e.line}  ${e.text.slice(0, 80)}`);
     }

package/dist/install-marks.js

@@ -616,7 +616,24 @@ export const CHECKER_SINCE = "0.16.308";
  * QUEM NÃO É AFETADO: quem não escreve `rotate-x`, `skew-x/y` ou `scale-x/y`. As formas SEM eixo -
  * `rotate-180`, `scale-95` - não se movem, e há asserção disso.
  */
-export const READER_SINCE = "0.16.354";
+/**
+ * 0.16.355 -> 0.16.356 em 03/09 (`INV-COB-14`): a FORMA de cada declaração não lida passa a viajar
+ * inteira, e é a decisão 24 no seu outro lado - declarar não move a marca, AMPLIAR move.
+ *
+ * O QUE ELE GANHA COM O `sync`: o teto de formas por grupo era 64, sobre uma medição do app inteiro
+ * (194 formas) aplicada a um limite POR GRUPO. Remedido em 03/09, o maior grupo do `web-subscribe`
+ * tem 1 480 formas - então chegavam 424 de 2 481 (17%), 124 de 812 no `wellcell` (15%) e 230 de 411
+ * no `frontend-hub` (56%). Um leitor novo escrito sobre o censo guardado alcançava um sexto do que
+ * existe no repositório dele, e o censo não tinha como dizer isso até `formsTotal` existir.
+ *
+ * POR QUE A FORMA E NÃO O TEXTO: cobrir os textos do `web-subscribe` custava +1,12 MB num censo de
+ * 1,50 MB (+75%), levando o texto-fonte dele a 81% do arquivo. Cobrir as formas custa +93 KB (+6%),
+ * e a forma tem os valores abstraídos - ela ensina o leitor sem guardar o código dele.
+ *
+ * QUEM NÃO É AFETADO: quem tem menos de 4 096 formas em todo grupo - `web-onboarding` já chegava
+ * com 39 de 39. O `sync` daquele repositório não muda um byte.
+ */
+export const READER_SINCE = "0.16.356";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/package.json

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