synthesisui 0.16.355 → 0.16.357

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`.

package/dist/doctor/their-names.js

@@ -59,23 +59,49 @@ const segments = (name) => name.replace(/^--/, "").split("-");
  *
  *     1. quantos segmentos ele compartilha com o nosso token daquela família
  *        `--ds-radius-xs` puxa `--radius-xs` (2) e não `--spacing` (0)
- *     2. a convenção dominante dele - o primeiro segmento mais frequente entre os tokens dele
+ *     2. quantos segmentos dele são um PAPEL que este sistema declara - ver `roles`
+ *     3. a convenção dominante dele - o primeiro segmento mais frequente entre os tokens dele
  *        no repo real, `--color-*` (57) contra `--dashboard-*` (25)
- *     3. ordem de declaração, que é o desempate que sempre existe e nunca inventa
+ *     4. ordem de declaração, que é o desempate que sempre existe e nunca inventa
+ *
+ * O CRITÉRIO 2 NASCEU DE UMA DECISÃO DO DONO (03/09), e o critério 1 não alcançava o caso. No
+ * sistema dele `#f59e0b` é `--color-tier-gold` E `--color-feedback-warning`, e medindo o censo:
+ * `tier-gold` tem 59 menções contra 7, e uma escada própria (bronze 13, prata 13). Pela contagem
+ * bruta ele venceria - e vencia, sempre que o nosso token daquele valor não existisse para o
+ * critério 1 comparar: aí caía na ORDEM DE DECLARAÇÃO, e `tier-gold` vem antes no CSS dele.
+ *
+ * A ESCOLHA NÃO É PELO MAIS FREQUENTE, É PELO ERRO QUE SE ANUNCIA. `feedback-warning` escrito num
+ * badge de nível mostra "warning" onde devia ser ouro, e quem lê corrige. `tier-gold` escrito num
+ * alerta pinta a cor CERTA com o nome de outro domínio - a tela fica visualmente correta e ninguém
+ * corrige nunca. Entre dois nomes dele, o que descreve um PAPEL erra alto; o que descreve um
+ * domínio de negócio erra calado.
  */
-function pick(candidates, ours, convention) {
+function pick(candidates, ours, convention, 
+/**
+ * OS PAPÉIS QUE ESTE SISTEMA DECLARA - o critério 2, e o único que decide quando não há token
+ * nosso daquele valor para comparar.
+ *
+ * DERIVADO, nunca escrito: são os segmentos finais dos papéis semânticos do próprio sistema, e
+ * por isso a regra vale em qualquer projeto. Um projeto que chame o aviso de `atencao` puxa
+ * `atencao`; nenhum nome de família deste ou daquele repositório entra aqui (`INV-GERAL-07`).
+ */
+roles) {
     const mine = ours ? new Set(segments(ours)) : null;
     let best = candidates[0];
-    let bestScore = [-1, -1];
+    let bestScore = [-1, -1, -1];
     for (const name of candidates) {
         const parts = segments(name);
         const shared = mine ? parts.filter((p) => mine.has(p)).length : 0;
         const score = [
             shared,
+            parts.filter((p) => roles.has(p)).length,
             convention.get(parts[0] ?? "") ?? 0,
         ];
         if (score[0] > bestScore[0] ||
-            (score[0] === bestScore[0] && score[1] > bestScore[1])) {
+            (score[0] === bestScore[0] && score[1] > bestScore[1]) ||
+            (score[0] === bestScore[0] &&
+                score[1] === bestScore[1] &&
+                score[2] > bestScore[2])) {
             best = name;
             bestScore = score;
         }
@@ -106,14 +132,29 @@ function pick(candidates, ours, convention) {
  * sistema do dono, `#f59e0b` é `--color-tier-gold` E `--color-feedback-warning` - dois conceitos
  * dele, gamificação e estado -, e o relatório dizia `→ {color.tier-gold}` como se fosse fato.
  */
-function escolha(candidates, ours, convention) {
-    const name = pick(candidates, ours, convention);
+function escolha(candidates, ours, convention, roles) {
+    const name = pick(candidates, ours, convention, roles);
     return { name, also: candidates.filter((c) => c !== name) };
 }
 export function theirNames(ours, theirs) {
     const out = new Map();
     if (theirs.byName.size === 0)
         return out;
+    /**
+     * OS PAPÉIS QUE ESTE SISTEMA DECLARA, derivados dos NOSSOS nomes - ver o critério 2 de `pick`.
+     *
+     * O último segmento de cada token semântico é o papel: `--ds-color-semantic-warning` dá
+     * `warning`. Sai daqui e não de uma lista escrita porque uma lista seria o nosso vocabulário
+     * virando régua - um sistema que chame o aviso de `atencao` tem que puxar `atencao`.
+     */
+    const roles = new Set();
+    for (const name of ours.byName.keys()) {
+        if (!name.includes("-semantic-"))
+            continue;
+        const last = segments(name).at(-1);
+        if (last)
+            roles.add(last);
+    }
     /** A convenção dominante dele, contada e não suposta - ver `pick`. */
     const convention = new Map();
     for (const name of theirs.byName.keys()) {
@@ -151,7 +192,7 @@ export function theirNames(ours, theirs) {
                 : candidates.filter((n) => familySays(kind, n));
             if (usable.length === 0)
                 continue;
-            out.set(key, escolha(usable, name, convention));
+            out.set(key, escolha(usable, name, convention, roles));
         }
     }
     for (const [value, candidates] of theirs.byValue) {
@@ -161,7 +202,7 @@ export function theirNames(ours, theirs) {
             const key = `${kind}:${value}`;
             if (out.has(key))
                 continue;
-            out.set(key, escolha(candidates, null, convention));
+            out.set(key, escolha(candidates, null, convention, roles));
         }
     }
     return out;

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.355",
+  "version": "0.16.357",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {