synthesisui 0.16.227 → 0.16.231

package/dist/doctor/scan.js

@@ -10,6 +10,15 @@
  * takes eight seconds and needs a build step is a diagnosis nobody runs.
  */
 import { normalizeValue, tokenMatch } from "./tokens.js";
+/**
+ * O NOME QUE SE ESCREVE NO ARQUIVO DELE - e existe uma função só para isto por um motivo.
+ *
+ * Seis lugares decidem o que a pessoa vê ou o que o `--fix` grava: o relatório, o plano, o hook, o
+ * MCP, a aplicação e a contagem. Deixar cada um lembrar de preferir `theirToken` é o padrão do
+ * argumento opcional que se esquece - e o sintoma seria o pior possível: o comando aconselhando um
+ * nome e o hook aconselhando outro, sobre o mesmo arquivo.
+ */
+export const nameToWrite = (f) => f.theirToken ?? f.token;
 /**
  * `next/og` renders JSX to a PNG on the server. There is no document, so there
  * is no `var(--ds-*)` to read: every colour in such a file MUST be a literal.
@@ -54,9 +63,35 @@ const OPEN = `["']?`;
 /** `rounded-[14px]`, `border-radius: 14px`, `borderRadius: "14px"`. Zero and
  *  full pills are idiom, not drift - nobody tokenizes `0` or `9999px`. */
 const RADIUS = new RegExp(`(?:border-?[Rr]adius\\s*:\\s*${OPEN}|rounded(?:-[a-z]+)?-\\[)(-?\\d*\\.?\\d+)(px|rem|em)`, "g");
-/** Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`, `gap: "18px"`.
- *  The JSX side also writes `paddingLeft`, `marginTop` and friends. */
-const SPACING = new RegExp(`(?:\\b[pmg](?:[trblxy])?-\\[|gap-\\[|(?:padding|margin|gap)(?:[A-Z][a-z]+)?\\s*:\\s*${OPEN})(-?\\d*\\.?\\d+)(px|rem)`, "g");
+/**
+ * Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`, `gap: "18px"`.
+ * The JSX side also writes `paddingLeft`, `marginTop` and friends.
+ *
+ * `em` ENTROU EM 13/08, e a falta dele era uma palavra: o padrão do RAIO logo acima já aceitava as
+ * três unidades e o do espaçamento aceitava duas. Não era doutrina, era assimetria - e o custo dela é
+ * o pior tipo, porque um valor que a varredura não vê não aparece nem como lacuna.
+ *
+ * Medido no repositório real, o que estava invisível:
+ *
+ *     933  espaçamentos em `em`   300×0.5em · 276×1em · 116×0.25em
+ *     144  raios em `em`          lidos, mas nunca nomeados (ver `normalizeValue`)
+ *     325  arquivos
+ *
+ * O dono achou pelo caminho que a gente não quer que ele precise usar (13/08): a skill abriu o
+ * `.scss` por conta própria e listou quatro `em` que o comando tinha acabado de chamar de limpo -
+ * *"não chegou nem a entrar no css, acho isso errado"*.
+ *
+ * E O KEBAB VEIO NA MESMA PUXADA, escondido atrás do primeiro. O sufixo aceito era só o camelCase
+ * do JSX (`paddingLeft`), então `padding-right: 1em` - a forma que TODO css escreve - não casava com
+ * nada. Foram os quatro `em` daquele mesmo arquivo que denunciaram: com `em` já no padrão, um
+ * continuou aparecendo e três não.
+ *
+ *     1175  `padding-*`/`margin-*` em kebab, em 335 arquivos do repositório real
+ *
+ * Duas gramáticas para a mesma propriedade é o tipo de coisa que só aparece quando alguém aponta
+ * para um arquivo e conta na mão.
+ */
+const SPACING = new RegExp(`(?:\\b[pmg](?:[trblxy])?-\\[|gap-\\[|(?:padding|margin|gap)(?:[A-Z][a-z]+|(?:-[a-z]+)+)?\\s*:\\s*${OPEN})(-?\\d*\\.?\\d+)(px|rem|em)`, "g");
 /** A font stack written by hand rather than taken from the type scale. */
 const FONT = /font-family\s*:\s*([^;}\n]+)/g;
 /**
@@ -370,11 +405,22 @@ function scanCore(file, source, table) {
             // The kind is already known here, and without passing it the lookup
             // answers a `gap` with a radius token.
             const match = tokenMatch(table, literal, kind);
+            /**
+             * O NOME DELE VEM DA MESMA CHAVE QUE A NOSSA FAMÍLIA VALIDOU - ver `theirNames`.
+             *
+             * A chave carrega o `kind` porque o valor sozinho não decide: `4px` é `--radius-xs` e
+             * `--spacing` no vocabulário dele, e qual dos dois está certo depende de onde o literal está.
+             */
+            const theirs = table.aliases.get(`${kind}:${normalizeValue(literal, table.rootPx)}`);
             findings.push({
                 kind,
                 line: at,
                 literal,
                 token: match?.token ?? null,
+                ...(/(?<!r)em$/i.test(literal.trim())
+                    ? { fontRelative: true }
+                    : {}),
+                ...(theirs ? { theirToken: theirs } : {}),
                 /**
                  * A COINCIDÊNCIA VIAJA COM O ACHADO - ver `tokenMatch`.
                  *
@@ -562,6 +608,8 @@ export function diagnose(files) {
             byLiteral.set(key, {
                 kind: f.kind,
                 token: f.token,
+                ...(f.theirToken ? { theirToken: f.theirToken } : {}),
+                ...(f.fontRelative ? { fontRelative: true } : {}),
                 count: 1,
                 files: new Set([f.file]),
                 ...(f.crossFamily ? { crossFamily: true } : {}),
@@ -573,6 +621,8 @@ export function diagnose(files) {
         literal: key.slice(key.indexOf(":") + 1),
         kind: v.kind,
         token: v.token,
+        ...(v.theirToken ? { theirToken: v.theirToken } : {}),
+        ...(v.fontRelative ? { fontRelative: true } : {}),
         count: v.count,
         files: v.files.size,
         ...(v.crossFamily ? { crossFamily: true } : {}),
@@ -585,7 +635,15 @@ export function diagnose(files) {
         files: files.filter((f) => f.findings.length > 0 || (f.phantoms?.length ?? 0) > 0),
         findings: flat,
         counts,
-        named: flat.filter((f) => f.token).length,
+        /**
+         * QUANTOS JÁ TÊM NOME NESTE REPOSITÓRIO - e o dele conta.
+         *
+         * Este número é a promessa que a tela faz ("9 of those have a name waiting"), e enquanto ele
+         * contava só os nossos, 852 achados que o repositório DELE nomeia saíam como "the system has no
+         * name for it". Uma promessa medida por metade do vocabulário que existe é uma promessa menor
+         * que a verdade.
+         */
+        named: flat.filter((f) => nameToWrite(f)).length,
         tokenUses,
         phantomUses,
         coverage: total === 0 ? 100 : Math.round(((tokenUses + ownUses) / total) * 100),

package/dist/doctor/their-names.js

@@ -0,0 +1,154 @@
+import { DS_FAMILY, normalizeValue } from "./tokens.js";
+/**
+ * COMO ELE CHAMA O VALOR - para a gente parar de renomear as variáveis dele.
+ *
+ * O doctor sempre soube dizer o que o sistema chama de `#888`. O que ele fazia com isso é que estava
+ * errado: mandava trocar por `var(--ds-color-gray-400)` num repositório que declara
+ * `--color-lightgray-700: #888888` desde antes de a gente existir. `--fix --write` escrevia o NOSSO
+ * nome dentro do arquivo dele.
+ *
+ * Medido no repositório vivo em 13/08, repo inteiro:
+ *
+ *     141  tokens que ELE declara
+ *     181  tokens que o sistema declara
+ *     114  dos nossos seguram um valor que um dos dele também segura
+ *
+ *     995  achados com nome nosso
+ *     737  deles (74%) renomeavam uma variável que ele já tem
+ *
+ * E o grupo que saía como "the system has no name for it":
+ *
+ *    5383  sem nome nosso
+ *     852  ...mas o repositório DELE nomeia   (843 cor · 8 tipo · 1 motion)
+ *
+ * A LEI JÁ EXISTIA, num sentido só. `absorb-plan.ts` diz, sobre a direção repo -> sistema: *"quando o
+ * vocabulário DELES já nomeia o valor, o nome é o deles"*. Na direção sistema -> repo a gente fazia o
+ * contrário. É a mesma lei 11 um nível abaixo da cor: não reescrever o vocabulário dele.
+ *
+ * ESTE MAPA NÃO É UM ARQUIVO, e é de propósito (dono, 13/08: *"talvez essas informações possam vir do
+ * MCP para não levar isso para o usuário ficar vendo"*). Ele é derivado das folhas de estilo dele a
+ * cada rodada - 686 folhas e 797KB no repo real, 4ms no hook inteiro (80ms -> 84ms, medido ponta a
+ * ponta), e o `absorb` já pagava essa varredura hoje. Um
+ * mapa gravado envelhece no dia em que ele renomeia um token, e aí a gente sugere um nome que não
+ * existe mais. O MCP ganha de graça, porque `check_file` roda este mesmo doctor.
+ *
+ * E ele nunca aparece na tela: o que aparece é o nome DELE, no lugar onde antes aparecia o nosso.
+ */
+/**
+ * QUANDO A FORMA DO VALOR JÁ DECIDE A FAMÍLIA - e é isto que a segunda porta pede.
+ *
+ * A porta admitia só COR, e o motivo estava certo pela metade: o que impede um comprimento de entrar
+ * é a AMBIGUIDADE (`24px` pode ser raio, espaçamento ou tamanho de fonte, e sem um token nosso não há
+ * o que decidisse), não o fato de ser cor. Uma pilha de fontes não é ambígua - `'Figtree', sans-serif`
+ * não pode ser um espaçamento -, e uma duração também não: `s` e `ms` só existem em motion.
+ *
+ * Então a regra é a forma, e o comprimento continua de fora, declarado. Medido no repositório real em
+ * 14/08: 7 achados em 6 arquivos saíam como "the system has no name for it" sobre a família de fontes
+ * que o próprio css dele nomeia `--dashboard-font-family`. É pouco, e é o único grupo que sobrou do
+ * item que eu tinha nomeado - os `em` saíram na leva anterior.
+ */
+const UNAMBIGUOUS = {
+    /** `#rrggbbaa`, que é onde toda a família de dialetos cai. */
+    color: /^#[0-9a-f]{8}$/,
+    /** `s` e `ms` não aparecem em nenhuma outra família do contrato. */
+    motion: /^-?[\d.]+ms$/,
+    /** Uma pilha de fontes: tem vírgula, ou é uma das palavras genéricas do CSS. */
+    font: /,|^(?:serif|sans-serif|monospace|cursive|fantasy|system-ui)$/,
+};
+const segments = (name) => name.replace(/^--/, "").split("-");
+/**
+ * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e são 18 no repo real.
+ *
+ * O empate não é decorativo: `4px` é `--radius-xs` E `--spacing` lá dentro, `24px` é `--text-h2` E
+ * `--spacing-lg`. Escolher errado escreve um token de tipo numa posição de espaçamento, que é
+ * exatamente o erro de categoria que o `crossFamily` foi criado para impedir do nosso lado.
+ *
+ * Três critérios, nesta ordem, e todos LIDOS do repositório dele:
+ *
+ *     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
+ *        no repo real, `--color-*` (57) contra `--dashboard-*` (25)
+ *     3. ordem de declaração, que é o desempate que sempre existe e nunca inventa
+ */
+function pick(candidates, ours, convention) {
+    const mine = ours ? new Set(segments(ours)) : null;
+    let best = candidates[0];
+    let bestScore = [-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,
+            convention.get(parts[0] ?? "") ?? 0,
+        ];
+        if (score[0] > bestScore[0] ||
+            (score[0] === bestScore[0] && score[1] > bestScore[1])) {
+            best = name;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * O MAPA DE UMA RODADA: `<natureza>:<valor normalizado>` -> como ELE chama.
+ *
+ * A chave carrega a natureza porque o valor sozinho não decide: o mesmo `4px` tem dois nomes no
+ * vocabulário dele, e qual dos dois está certo depende de o literal estar num raio ou num
+ * espaçamento. É a mesma razão pela qual `tokenMatch` recebe o `kind`.
+ *
+ * DUAS PORTAS, e a segunda é o que faz o número dobrar:
+ *
+ *     o sistema nomeia o valor     a NOSSA família valida a natureza, e o nome dele entra
+ *     o sistema NÃO nomeia         entra o valor cuja FORMA já decide a família - ver `UNAMBIGUOUS`
+ *
+ * O que fica de fora da segunda porta é o COMPRIMENTO, e ele fica por um motivo e não por descuido:
+ * `24px` pode ser raio, espaçamento ou tamanho de fonte, e sem um token nosso não há o que validasse.
+ * Esses continuam saindo como "no name for it", que é verdade e é o caminho do `absorb`.
+ */
+export function theirNames(ours, theirs) {
+    const out = new Map();
+    if (theirs.byName.size === 0)
+        return out;
+    /** A convenção dominante dele, contada e não suposta - ver `pick`. */
+    const convention = new Map();
+    for (const name of theirs.byName.keys()) {
+        const head = segments(name)[0] ?? "";
+        convention.set(head, (convention.get(head) ?? 0) + 1);
+    }
+    for (const [kind, prefix] of Object.entries(DS_FAMILY)) {
+        for (const [name, raw] of ours.byName) {
+            if (!name.startsWith(prefix))
+                continue;
+            const value = normalizeValue(raw, ours.rootPx);
+            const key = `${kind}:${value}`;
+            if (out.has(key))
+                continue;
+            const candidates = theirs.byValue.get(value);
+            if (!candidates || candidates.length === 0)
+                continue;
+            out.set(key, pick(candidates, name, convention));
+        }
+    }
+    for (const [value, candidates] of theirs.byValue) {
+        for (const [kind, form] of Object.entries(UNAMBIGUOUS)) {
+            if (!form.test(value))
+                continue;
+            const key = `${kind}:${value}`;
+            if (out.has(key))
+                continue;
+            out.set(key, pick(candidates, null, convention));
+        }
+    }
+    return out;
+}
+/**
+ * A TABELA COM O VOCABULÁRIO DELE DENTRO - um passo, e é este que os comandos chamam.
+ *
+ * `ours` continua sendo a lei: é ela que diz se `2rem` é tipo ou raio, e é dela que sai a cobertura.
+ * A dele decide só COMO SE ESCREVE. Separar as duas é o mesmo desenho que o `absorb` já usa
+ * ("DUAS TABELAS, e é a diferença entre elas que define o trabalho").
+ */
+export function withTheirNames(ours, theirs) {
+    return { ...ours, aliases: theirNames(ours, theirs) };
+}

package/dist/doctor/tokens.js

@@ -31,6 +31,7 @@ export const EMPTY_TABLE = {
     byValue: new Map(),
     rootPx: DEFAULT_ROOT_PX,
     rootFrom: null,
+    aliases: new Map(),
     declared: new Set(),
     keyframes: new Set(),
 };
@@ -120,10 +121,19 @@ export function normalizeValue(raw, rootPx) {
      * A FAMÍLIA CONTINUA MANDANDO: `4px` passa a casar com `--ds-radius-xs` E com `--ds-spacing-3xs`,
      * e é `tokenMatch` quem escolhe pelo `kind` - um raio não vira espaçamento dentro de um `gap`.
      */
-    const len = /^(-?\d*\.?\d+)(px|rem)$/.exec(v);
+    /**
+     * `em` CAI AQUI JUNTO, e o que impede isso de virar uma suposição é o achado, não o normalizador.
+     *
+     * Converter `1em` por `rootPx` é certo sempre que a fonte do elemento é a da raiz, e errado quando
+     * um ancestral a mudou - e isto aqui não tem como saber qual dos dois. Ele converte para a
+     * CONVERSA existir (sem isto, `1em` não casa com degrau nenhum e sai como "o sistema não nomeia
+     * isto", sobre um valor que o sistema nomeia); quem impede a troca automática é `Finding.fontRelative`,
+     * que o `--fix` recusa. Ver `scan.ts`.
+     */
+    const len = /^(-?\d*\.?\d+)(px|r?em)$/.exec(v);
     if (len) {
         const n = Number.parseFloat(len[1]);
-        const px = len[2] === "rem" ? n * rootPx : n;
+        const px = len[2] === "px" ? n : n * rootPx;
         /** Arredonda o rastro binário: `0.35rem * 16` é 5.6000000000000005. */
         return `${Math.round(px * 1e4) / 1e4}px`;
     }
@@ -431,6 +441,8 @@ export function buildTable(input) {
         byValue,
         rootPx,
         rootFrom: input.rootFrom ?? null,
+        /** Vazio até `withTheirNames` ler o vocabulário dele - ver `their-names.ts`. */
+        aliases: new Map(),
         declared: parseDeclaredNames(input.css),
         keyframes: new Set([...input.css.matchAll(/@keyframes\s+([a-zA-Z0-9_-]+)/g)].map((m) => m[1])),
     };
@@ -492,7 +504,9 @@ export function nearestToken(table, literal) {
  * radius is one a person stops reading, and this one has exactly one job that
  * nobody else does: naming the right token.
  */
-const FAMILY = {
+/** Exportado para `their-names.ts`, que precisa da MESMA divisão de família para validar a natureza
+ *  de um nome dele - duas tabelas de família seriam duas leis. */
+export const DS_FAMILY = {
     color: "--ds-color-",
     radius: "--ds-radius-",
     spacing: "--ds-spacing-",
@@ -521,7 +535,7 @@ export function tokenMatch(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal, table.rootPx));
     if (!hit || hit.length === 0)
         return null;
-    const prefix = kind ? FAMILY[kind] : undefined;
+    const prefix = kind ? DS_FAMILY[kind] : undefined;
     const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
     const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.

package/dist/install-marks.js

@@ -96,7 +96,34 @@ export const MATERIALISER_SINCE = "0.16.220";
  * tem nome para isto" sobre um valor que o sistema dela nomeia - medido no repo real, 243 trocas
  * viraram 764 sobre os mesmos 4433 valores à mão.
  */
-export const CHECKER_SINCE = "0.16.223";
+/**
+ * 0.16.223 -> 0.16.229 em 13/08, e o SIM mais forte que esta marca já teve: o hook passou a
+ * aconselhar o nome DELE. Um pin anterior lê o mesmo arquivo e manda escrever
+ * `var(--ds-color-gray-400)` num repositório que declara `--color-lightgray-700: #888888` - e a
+ * pessoa acaba com dois conselhos diferentes sobre o mesmo valor, porque o `doctor` de hoje diz o
+ * nome dela. Medido no repo real: 737 de 995 sugestões renomeavam uma variável dela, e outras 852
+ * saíam como "o sistema não nomeia isto" sobre valores que o repositório dela nomeia.
+ *
+ * É também a primeira vez que o hook VARRE as folhas de estilo, revisando a escolha declarada em
+ * `loadSystem` - medido ponta a ponta no repo real, 80ms -> 84ms, contra oferecer o nome errado.
+ */
+/**
+ * 0.16.229 -> 0.16.230 em 13/08: `em` passou a ser um comprimento como os outros. O padrão do RAIO
+ * já aceitava as três unidades e o do ESPAÇAMENTO aceitava duas - assimetria, não doutrina - e um
+ * hook pinado antes disto lê o mesmo arquivo e não vê 933 espaçamentos e 144 raios, em 325 arquivos
+ * do repositório real. Não é medir menos: é chamar de limpo o que não é.
+ *
+ * A 0.16.229 nunca chegou ao npm, mas a marca sobe assim mesmo - uma marca que aponta para uma
+ * versão que ninguém pode instalar é uma marca que nunca dispara.
+ */
+/**
+ * 0.16.230 -> 0.16.231 em 14/08: a segunda porta do mapa de vocabulário deixou de ser "só cor" e
+ * passou a ser "a forma que já decide a família" - uma pilha de fontes não pode ser um espaçamento, e
+ * `ms` só existe em motion. Um hook pinado antes disto olha o arquivo que a pessoa acabou de escrever
+ * e diz que o sistema não nomeia a fonte que o css dela nomeia. Medido no repositório real: as trocas
+ * com nome disponível foram de 1624 para 1631.
+ */
+export const CHECKER_SINCE = "0.16.231";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/measured-scope.js

@@ -117,7 +117,9 @@ export function describeScope(m) {
             ]
             : []),
     ];
-    return `read from your census: ${parts.join(" · ")}`;
+    /** O ARQUIVO, e não a palavra: "census" é o nosso nome para a medição; `_synthesisui/census.json`
+     *  é um caminho que ele abre. Ver a guarda de vocabulário em `doctor-intent.spec.ts`. */
+    return `read from _synthesisui/census.json: ${parts.join(" · ")}`;
 }
 /**
  * GRAVA ONDE ESTE SISTEMA FOI MEDIDO, no ponteiro dele.