synthesisui 0.16.354 → 0.16.355

package/dist/doctor/style-ledger.js

@@ -185,6 +185,7 @@ declared) {
             seenFiles: new Set(),
             withTheirTokens: 0,
             formTally: new Map(),
+            distinctTexts: new Set(),
         };
         group.uses += 1;
         group.seenFiles.add(f.file);
@@ -218,30 +219,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
          *
-         * `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.
+         * 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.
+         *
+         * 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 +278,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 +374,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/package.json

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