synthesisui 0.16.228 → 0.16.233

package/dist/absorb-plan.js

@@ -1,5 +1,5 @@
 import { deltaE, JND } from "./doctor/color-distance.js";
-import { nearestToken } from "./doctor/tokens.js";
+import { familySays, nearestToken, normalizeValue, } from "./doctor/tokens.js";
 /** Onde cada tipo de valor mora na fundação. `color` é o único com dois segmentos. */
 const HOME = {
     color: "color",
@@ -9,8 +9,31 @@ const HOME = {
     motion: "motion.durations",
 };
 /** Uma palavra de categoria no começo do nome deles não é família - é a categoria repetida. */
-const CATEGORY = /^(color|colour|radius|rounded|spacing|space|gap|font|type|duration|motion|ease|easing)-/;
+const CATEGORY = /^(color|colour|radius|rounded|spacing|space|gap|font|type|text|duration|motion|ease|easing)-/;
 const clean = (name) => name.replace(/^--/, "").toLowerCase();
+/**
+ * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e aqui a natureza do ACHADO decide.
+ *
+ * `24px` é `--text-h2` E `--spacing-lg` no vocabulário do repositório real. Um `[0]` pega o de tipo
+ * para um achado de espaçamento, e o caminho que sai daí é `typography.h2` sobre uma margem - o mesmo
+ * erro de categoria que o `crossFamily` foi criado para impedir do outro lado da esteira.
+ *
+ * A pista são as palavras de família do nome dele - `familySays`, a MESMA tabela que o mapa de
+ * vocabulário usa para recusar uma sugestão de categoria trocada. Duas listas para a mesma pergunta é
+ * como duas telas passam a discordar sobre o mesmo `12px`.
+ *
+ * Quando nenhum candidato concorda com a natureza do achado, COR ainda passa - um hex numa posição de
+ * cor não tem ambiguidade de família - e comprimento não passa: sem concordância não há o que
+ * separasse um token de tipo de um de espaçamento, e o valor volta sem caminho para a pessoa decidir.
+ */
+function nameOf(kind, candidates) {
+    if (!candidates || candidates.length === 0)
+        return undefined;
+    const agrees = candidates.find((n) => familySays(kind, n));
+    if (agrees)
+        return agrees;
+    return kind === "color" ? candidates[0] : undefined;
+}
 /**
  * O CAMINHO A PARTIR DO NOME DELES, e nada além dele.
  *
@@ -87,10 +110,34 @@ export function absorbPlan(d, theirs, have, cap = 40) {
     for (const r of unnamed) {
         if (entries.length >= cap)
             break;
-        const theirNames = theirs.byValue.get(r.literal.toLowerCase()) ?? [];
-        const theirName = theirNames[0];
+        /**
+         * O VALOR NORMALIZADO, e não o literal cru - era aqui que a metade pronta desta lista sumia.
+         *
+         * `byValue` é indexada pela forma canônica: cor em `#rrggbbaa`, comprimento em px sobre a raiz
+         * medida. A busca usava o literal como ele aparece no código, então:
+         *
+         *     get("#fff")        ->  nada          get("#ffffffff")  ->  --dashboard-white-500
+         *     get("1em")         ->  nada          get("16px")       ->  --spacing-md
+         *     get("24px")        ->  acertava por acidente, porque px já é a forma canônica
+         *
+         * Cor NUNCA casava (a chave tem alfa), `em`/`rem` nunca casavam, e `px` casava por coincidência.
+         * Medido no repositório real em 14/08:
+         *
+         *     na lista que ele VÊ (as 40 mais repetidas)    0 -> 5 com nome dele, 404 arquivos
+         *     na fila inteira (338 valores)                 1 -> 22 com nome dele, 478 arquivos
+         *
+         * A primeira leitura desta medição contou os 22 e escreveu "22 de 40", que é a fila inteira sobre
+         * o denominador da página - o número certo na conta errada. São 5 na tela e 22 na fila.
+         *
+         * O custo não era só a lista curta: o `doctor` mandava trocar `#fff` por
+         * `var(--dashboard-white-500)` e o `absorb`, no mesmo dia, pedia que ele batizasse `#fff`. Dois
+         * comandos com conselhos opostos sobre o mesmo valor.
+         */
+        const theirName = nameOf(r.kind, theirs.byValue.get(normalizeValue(r.literal, theirs.rootPx)));
         const path = pathFor(r.kind, theirName);
-        const near = nearestOwn(theirs, r.literal, r.kind);
+        /** "≈ perto de um token seu" só interessa a quem não tem um EXATO - com o nome na mão, a dica
+         *  vira ruído, e no arquivo de proposta ela vira uma segunda opção que não é opção. */
+        const near = theirName ? undefined : nearestOwn(theirs, r.literal, r.kind);
         /** Já existe na fundação com OUTRO valor: absorver aqui seria repintar o token deles. */
         if (path && have.has(path))
             continue;

package/dist/commands/absorb.js

@@ -3,7 +3,6 @@ import { dirname, join, resolve } from "node:path";
 import { absorbPlan, describeAbsorb, needingName, } from "../absorb-plan.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
-import { buildTable } from "../doctor/tokens.js";
 import { measuredScope, scopePaths } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { loadSystem, walkAll } from "./doctor.js";
@@ -48,12 +47,12 @@ export async function absorb(opts) {
      * eles chamam o valor, e é de lá que o nome sai. Lida da RAIZ mesmo quando a medição é escopada: o
      * vocabulário é do projeto, e um app que pega um token emprestado do `packages/ui` deles não o
      * redeclara.
+     *
+     * A varredura era daqui e mudou de lugar: `loadSystem` a faz agora, porque o `doctor`, o `hook` e
+     * o MCP passaram a precisar da MESMA tabela dele - ver `their-names.ts`. Este comando descreveu a
+     * ideia primeiro e ficou com a implementação de todo mundo.
      */
-    let css = "";
-    for await (const file of walkAll([root]))
-        if (/\.(css|scss|sass|less)$/i.test(file))
-            css += `\n${await readFile(file, "utf8").catch(() => "")}`;
-    const theirs = buildTable({ css, source: "yours" });
+    const theirs = installed.theirs;
     const reports = [];
     for await (const file of walkAll(roots)) {
         const source = await readFile(file, "utf8").catch(() => null);

package/dist/commands/doctor.js

@@ -12,8 +12,9 @@ import { appendEvent, COVERAGE_RULE, readEvents, suggestionsFrom, summarize, } f
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { checkableName, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { DEFAULT_ROOT_PX, rootSizeOf, saidOfRoot, } from "../doctor/root-size.js";
-import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
+import { diagnose, nameToWrite, scanSource, siblingTokens, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
+import { withTheirNames } from "../doctor/their-names.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
 import { describeScope, measuredScope, scopePaths } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
@@ -167,8 +168,12 @@ measured) {
             .map((e) => e.name);
     }
     catch {
+        /** Sem nada nosso instalado, o vocabulário dele é o ÚNICO que existe - e é contra ele que a
+         *  medição acontece. Era a queda que já existia, agora servida do mesmo lugar que o resto. */
+        const theirs = await harvestOwnTokens([root], measured);
         return {
             table: EMPTY_TABLE,
+            theirs,
             recipes: new Map(),
             documents: [],
             requires: [],
@@ -275,13 +280,39 @@ measured) {
             }
         }
     }
+    const ours = buildTable({
+        css,
+        lock,
+        source: adopted ? "adopted" : "installed",
+        ...(measured ? { rootPx: measured.px, rootFrom: measured.from } : {}),
+    });
+    /**
+     * O VOCABULÁRIO DELE, LIDO SEMPRE - e isto revisa uma escolha declarada, então ela se revisa em
+     * voz alta.
+     *
+     * A nota antiga aqui dizia que o `hook` NÃO varre css de propósito, por orçamento: ele roda depois
+     * de cada escrita, e uma varredura por edição trocaria um relatório instantâneo por um que a
+     * pessoa desliga. O princípio dela continua valendo e é ele que manda mudar agora - *"erra para o
+     * lado de oferecer MENOS, nunca de oferecer a troca errada"*. Sem o vocabulário dele, o hook não
+     * oferece menos: ele oferece o NOME ERRADO, mandando escrever `--ds-color-gray-400` num arquivo de
+     * um repositório que declara `--color-lightgray-700` para aquele mesmo valor.
+     *
+     * O custo, medido ponta a ponta no repositório real em 13/08 - o hook inteiro, e não a varredura
+     * isolada, porque é o hook que tem o orçamento:
+     *
+     *     antes   80ms   mediana de 5 execuções
+     *     depois  84ms   mediana de 9, sobre 686 folhas e 797KB de css
+     *
+     * A primeira estimativa desta varredura foi 28ms, medida num processo à parte e sem o `walkAll`
+     * do CLI, que pula o que não interessa. Ficam os 4ms medidos, que são o que a pessoa paga.
+     *
+     * E a raiz medida atravessa junto, para as duas tabelas normalizarem `4px` e `0.25rem` na mesma
+     * unidade. Uma raiz por tabela seria a forma mais silenciosa de discordar.
+     */
+    const theirs = await harvestOwnTokens([root], measured);
     return {
-        table: buildTable({
-            css,
-            lock,
-            source: adopted ? "adopted" : "installed",
-            ...(measured ? { rootPx: measured.px, rootFrom: measured.from } : {}),
-        }),
+        table: withTheirNames(ours, theirs),
+        theirs,
         recipes,
         documents,
         requires,
@@ -315,14 +346,22 @@ async function sheetsIn(roots) {
     }
     return out;
 }
-async function harvestOwnTokens(roots) {
+async function harvestOwnTokens(roots, 
+/** A MESMA raiz que a nossa tabela usa - duas raízes seriam a forma mais silenciosa de discordar,
+ *  e `4px` deixaria de casar com `0.25rem` de um lado só. */
+measured) {
     let css = "";
     for await (const file of walkAll(roots)) {
         if (!/\.(css|scss|sass|less)$/i.test(file))
             continue;
         css += `\n${await readFile(file, "utf8").catch(() => "")}`;
     }
-    return buildTable({ css, source: "yours" });
+    return buildTable({
+        css,
+        source: "yours",
+        rootPx: measured?.px,
+        rootFrom: measured?.from ?? null,
+    });
 }
 const KIND_LABEL = {
     color: "colour",
@@ -528,6 +567,14 @@ export async function doctor(opts) {
         from: rootSize.from,
     });
     const { recipes, documents } = installed;
+    /**
+     * A TABELA JÁ VEM COM O VOCABULÁRIO DELE DENTRO - ver `loadSystem` e `their-names.ts`.
+     *
+     * O que muda aqui é só a QUEDA: quando não há nada nosso instalado, a dele passa a ser a tabela
+     * inteira, que é o que sempre foi. Ela é lida da RAIZ mesmo com a leitura escopada, pela mesma
+     * razão de sempre: o vocabulário é do projeto, e um app que pega um token emprestado do
+     * `packages/ui` dele não o redeclara.
+     */
     let table = installed.table;
     // Nothing of ours here does not mean nothing to measure against. Fall back
     // to whatever vocabulary the project already declares for itself.
@@ -545,9 +592,20 @@ export async function doctor(opts) {
          * Same rule our own installed system already follows: found from the root,
          * measured in the scope.
          */
-        table = await harvestOwnTokens([root]);
+        table = withTheirNames(installed.theirs, installed.theirs);
     }
     const hasSystem = table.byName.size > 0;
+    /**
+     * O NOME DELE, ONDE ANTES ESTAVA "the system".
+     *
+     * O cabeçalho já abre com `SignalUI v8` e três linhas abaixo o mesmo relatório dizia *"0 from the
+     * system"* num repositório que tem DOIS vocabulários - o dele e o nosso. "the system" obriga quem lê
+     * a adivinhar de qual dos dois a linha fala, e a resposta certa é a que ele mesmo batizou. Mesma
+     * decisão do #937 um nível acima: o nome que a gente devolve é o nome dele.
+     *
+     * Quando não há sistema instalado, cai em "this system", porque aí não existe nome para usar.
+     */
+    const systemName = table.name ?? table.slug ?? "this system";
     const reports = [];
     const overrides = [];
     const used = new Map();
@@ -655,7 +713,7 @@ export async function doctor(opts) {
      */
     if (scopes.length > 0) {
         const said = measured.from === "census" ? describeScope(measured) : null;
-        console.log(body(said ?? `scope: ${relScopes.join(", ")}`));
+        console.log(body(said ?? `read from: ${relScopes.join(", ")}`));
     }
     /**
      * A RAIZ QUE ESTA RODADA USOU - e ela é impressa SEMPRE, inclusive quando é o padrão.
@@ -690,7 +748,7 @@ export async function doctor(opts) {
     const asideTotal = [...aside.values()].reduce((n, v) => n + v, 0);
     if (verbose) {
         for (const [reason, count] of aside) {
-            console.log(body(`set aside: ${plural(count, "value")} in ${reason}`));
+            console.log(body(`out of the count: ${plural(count, "value")} in ${reason}`));
         }
     }
     else if (asideTotal > 0) {
@@ -699,9 +757,13 @@ export async function doctor(opts) {
         // `var(--ds-color-semantic-knob, #ffffff)` - is set aside for the opposite
         // reason: it is already tokenized. The summary said the false half out
         // loud and hid the true half behind a flag.
-        console.log(body(`set aside ${plural(asideTotal, "value")} that are not drift` +
+        /**
+         * "not drift" era a nossa palavra para o motivo, e ela não diz o motivo. As duas razões reais
+         * cabem na linha: ou nenhum token poderia segurar aquele valor, ou ele já vem de um.
+         */
+        console.log(body(`${plural(asideTotal, "value")} left out of the count - a token could never hold them, or they already come from one` +
             (skippedProjects.length > 0
-                ? ` and ${plural(skippedProjects.length, "nested project")} that speak their own systems`
+                ? `, and ${plural(skippedProjects.length, "nested project")} that speak their own systems`
                 : "") +
             " (--verbose for why)"));
     }
@@ -784,7 +846,7 @@ export async function doctor(opts) {
                 ...(d.findings.some((f) => f.crossFamily)
                     ? { crossFamily: d.findings.filter((f) => f.crossFamily).length }
                     : {}),
-                ...(d.repeats.some((r) => r.token)
+                ...(d.repeats.some((r) => nameToWrite(r))
                     ? { matched: suggestionsFrom(d.repeats) }
                     : {}),
             }).catch(() => { });
@@ -835,7 +897,7 @@ export async function doctor(opts) {
     if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${paint.strong(`${String(d.coverage).padStart(3)}%`)}`));
-        console.log(body(paint.dim(`                ${d.tokenUses} from the system${d.ownUses > 0 ? `, ${d.ownUses} from your own tokens` : ""}, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
+        console.log(body(paint.dim(`                ${d.tokenUses} from ${systemName}${d.ownUses > 0 ? `, ${d.ownUses} from your own tokens` : ""}, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
         /**
          * A CAMADA DE TOKEN DELE, CONTADA - e a decisão é do dono, em 13/08.
          *
@@ -850,7 +912,7 @@ export async function doctor(opts) {
          * os 122 usos seguem o sistema sem tocar em um componente sequer.
          */
         if (d.ownTokens > 0) {
-            console.log(body(paint.dim(`                ${d.ownTokens} token${d.ownTokens === 1 ? "" : "s"} of your own, used ${d.ownUses}x${d.ownMirrored > 0 ? ` - ${d.ownMirrored} hold a value this system also names` : ""}`)));
+            console.log(body(paint.dim(`                ${d.ownTokens} token${d.ownTokens === 1 ? "" : "s"} of your own, used ${d.ownUses}x${d.ownMirrored > 0 ? ` - ${d.ownMirrored} hold a value ${systemName} also names` : ""}`)));
             if (d.ownMirrored > 0)
                 console.log(body(paint.dim(`                point those at the \`--ds-*\` that holds it: ${d.ownMirrored} lines, one file`)));
         }
@@ -869,12 +931,34 @@ export async function doctor(opts) {
          * Medido no repo do dono: 1 uso do sistema, 4 433 à mão, 243 com nome - o medidor diz 0% e a
          * linha diz 5%.
          */
-        const nameable = d.findings.filter((f) => f.token).length;
+        const named = d.findings.filter((f) => nameToWrite(f));
+        /**
+         * "UM COMANDO DE DISTÂNCIA" SÓ VALE PARA O QUE O COMANDO ESCREVE - ver `Finding.fontRelative`.
+         *
+         * `1em` ganhou nome nesta versão, e ganhar nome não é ganhar troca automática: o `--fix` recusa
+         * o comprimento que segue a fonte do elemento, porque o pixel pode mudar. Contá-los aqui faria a
+         * tela prometer 100% e o comando entregar 0 - e um relatório que promete o que o comando seguinte
+         * recusa gasta mais confiança do que teria custado dizer o número menor.
+         *
+         * Medido no arquivo que o dono apontou (13/08): 4 valores, 4 com nome, e os 4 são `em`. A linha
+         * dizia "100% is one command away" sobre um `--fix` que não escreveria nenhum deles.
+         */
+        const nameable = named.filter((f) => !f.fontRelative).length;
+        const yours = named.length - nameable;
         if (nameable > 0) {
             const reach = Math.round(((d.tokenUses + nameable) / (d.tokenUses + d.findings.length)) * 100);
             console.log(body(paint.dim(`                ${reach}% is one command away - ${nameable} of those have a name waiting`)));
             console.log(body(paint.dim("                npx synthesisui doctor --fix")));
         }
+        /**
+         * E O QUE TEM NOME MAS NÃO TEM TROCA APARECE MESMO ASSIM, com o motivo.
+         *
+         * Sem esta linha, o `em` volta a ser invisível por outra porta: ele sai da conta de "um comando
+         * de distância" e não entra em lugar nenhum, e a pessoa fica sem saber que o sistema dela nomeia
+         * aquele valor. A lacuna é declarada, não escondida.
+         */
+        if (yours > 0)
+            console.log(body(paint.dim(`                ${yours} more your system names, in \`em\` - the same number, but it follows the element's font size, so that swap is yours to make`)));
         /**
          * ZERO NUM REPO QUE ORIGINOU O SISTEMA É O ESTADO CERTO, e sem esta linha ele lê como falha
          * NOSSA.
@@ -903,14 +987,14 @@ export async function doctor(opts) {
          */
         if (d.coverage === 0 && measured.system) {
             console.log(body(paint.dim(`                zero is the expected start here - this system was measured FROM`)));
-            console.log(body(paint.dim(`                \`${measured.system}\`, so these values are its source, not a drift`)));
-            console.log(body(paint.dim(`                from it. They count once the code points at the names they became.`)));
+            console.log(body(paint.dim(`                \`${measured.system}\`, so these values are where the tokens`)));
+            console.log(body(paint.dim(`                came from. They count once the code points at the names they became.`)));
         }
         // The strongest number leads, not trails: it used to sit two screens
         // down, after the phantom list (30/07). For the reader who already owns
         // a system - the ICP - THIS line is the report.
         if (table.source === "yours" && d.findings.length > 0) {
-            const named = d.findings.filter((f) => f.token).length;
+            const named = d.findings.filter((f) => nameToWrite(f)).length;
             if (named > 0) {
                 console.log("");
                 console.log(body(`${paint.strong(String(named))} of the ${d.findings.length} hand-written values have a name waiting in YOUR system - they are still literals.`));
@@ -950,7 +1034,7 @@ export async function doctor(opts) {
             named: d.named,
             ...(crossFamily > 0 ? { crossFamily } : {}),
             /** E os pares em si, para a plataforma reavaliar sem esperar outra medição - ver `matched`. */
-            ...(d.repeats.some((r) => r.token)
+            ...(d.repeats.some((r) => nameToWrite(r))
                 ? { matched: suggestionsFrom(d.repeats) }
                 : {}),
         });
@@ -979,8 +1063,9 @@ export async function doctor(opts) {
              * para 37% sem uma linha de código mudada. Somar as duas fotos anunciaria um progresso
              * inventado; calar a mudança deixaria alguém procurar o que fez o número pular.
              */
+            /** E SEM O NÚMERO DA VERSÃO: o que mudou a conta é a conta, não a nossa release. */
             if (record.ruleChanged)
-                console.log(body("  the coverage ruler changed in 0.16.219 - your own tokens now count, so the trend restarts here."));
+                console.log(body("  the way this is counted changed - your own tokens count now too, so the trend restarts here."));
         }
     }
     /**
@@ -1072,7 +1157,14 @@ export async function doctor(opts) {
         console.log(body("Add the name to the system, or use one it has. Do not leave it."));
     }
     if (d.findings.length > 0) {
-        say(section("Drift"));
+        /**
+         * "Drift" É A NOSSA PALAVRA para um valor fora do sistema, e era o TÍTULO de uma seção inteira.
+         *
+         * A rodada padrão perdeu o vocabulário nosso em 13/08 e o `--verbose` ficou - a guarda rodava
+         * sobre a saída sem `--verbose`, que é o que a maioria lê. O que a seção lista é literal escrito
+         * à mão, e é isso que o título passa a dizer.
+         */
+        say(section("Values written by hand"));
         const order = ["color", "radius", "spacing", "font"].filter((k) => d.counts[k] > 0);
         for (const kind of order) {
             say(body(`${d.counts[kind]}  ${KIND_LABEL[kind]}`));
@@ -1087,15 +1179,15 @@ export async function doctor(opts) {
             const w = Math.max(...repeats.map((r) => r.literal.length));
             for (const r of repeats) {
                 const where = `${r.count}\u00d7 in ${r.files} file${r.files === 1 ? "" : "s"}`;
-                const near = r.token ? null : nearestToken(table, r.literal);
+                const near = nameToWrite(r) ? null : nearestToken(table, r.literal);
                 /**
                  * COINCIDÊNCIA NÃO É RESPOSTA - ver `crossFamily` em `scan.ts`. Para aquele `kind` o
                  * sistema não tem nome; o valor mora noutra família, e dizer só a seta afirma o contrário.
                  */
                 const named = r.crossFamily
                     ? `  → no ${r.kind} named for it · the value lives as ${r.token}`
-                    : r.token
-                        ? `  → ${r.token}`
+                    : nameToWrite(r)
+                        ? `  → ${nameToWrite(r)}`
                         : near
                             ? `  → nearest is ${near.name} (${near.value})`
                             : "";
@@ -1113,11 +1205,11 @@ export async function doctor(opts) {
             for (const x of shown) {
                 // A dead end with a neighbour is not a dead end. Only for lengths -
                 // "nearly the same blue" is the guess this tool must never make.
-                const near = x.token ? null : nearestToken(table, x.literal);
+                const near = nameToWrite(x) ? null : nearestToken(table, x.literal);
                 const named = x.crossFamily
                     ? `→ no ${x.kind} named for it · the value lives as ${x.token}`
-                    : x.token
-                        ? `→ ${x.token}`
+                    : nameToWrite(x)
+                        ? `→ ${nameToWrite(x)}`
                         : near
                             ? `→ nearest is ${near.name} (${near.value})`
                             : "→ no token holds this value yet";
@@ -1449,25 +1541,36 @@ export async function doctor(opts) {
      * Ele não some: vai para o grupo de quem NÃO tem nome, que é literalmente o que ele é para
      * aquele kind - e a linha diz onde o valor mora hoje.
      */
-    const named = d.repeats.filter((x) => x.token && !x.crossFamily);
-    const unnamed = d.repeats.filter((x) => !x.token || x.crossFamily);
+    const named = d.repeats.filter((x) => nameToWrite(x) && (!x.crossFamily || x.theirToken));
+    const unnamed = d.repeats.filter((x) => !nameToWrite(x) || (x.crossFamily && !x.theirToken));
     for (const r of named.slice(0, migrating ? 2 : 3)) {
         plan.push({
             rank: migrating ? 4 : 3,
-            what: `${r.literal} → ${r.token}`,
+            /** Curto de propósito: a coluna trunca, e uma ressalva cortada ao meio é pior que nenhuma.
+             *  O porquê inteiro está na linha do medidor, logo acima. */
+            what: r.fontRelative
+                ? `${r.literal} → ${nameToWrite(r)} · your call`
+                : `${r.literal} → ${nameToWrite(r)}`,
             size: `${r.files} file${r.files === 1 ? "" : "s"}`,
-            cheap: true,
+            /** `cheap` promete "não muda um pixel", e um `em` pode mudar - ver `Finding.fontRelative`. */
+            cheap: !r.fontRelative,
         });
     }
     for (const r of unnamed.slice(0, migrating ? 3 : 2)) {
         const near = nearestToken(table, r.literal);
         plan.push({
             rank: migrating ? 3 : 4,
+            /**
+             * "the system has no name for it" era verdade sobre O SISTEMA e o repositório tem dois
+             * vocabulários - o dele também foi consultado (ver `their-names.ts`), e chegar aqui significa
+             * que NENHUM dos dois nomeia o valor. É isso que a linha passa a dizer, e é o que separa esta
+             * fila da anterior: aquela tem nome esperando, esta precisa de um.
+             */
             what: near
                 ? `${r.literal} - name it, or snap to ${near.name}`
                 : r.crossFamily
                     ? `${r.literal} - no ${r.kind} named for it, and the value lives as ${r.token} in another family`
-                    : `${r.literal} - the system has no name for it`,
+                    : `${r.literal} - no name for it, here or in your CSS`,
             size: `${r.files} file${r.files === 1 ? "" : "s"}`,
             cheap: false,
         });
@@ -1589,7 +1692,7 @@ export async function doctor(opts) {
      * 1500 achados e depois dizer "troquei 900" é fazer a pessoa procurar a linha que importa.
      */
     if (opts.fix) {
-        const read = await readerFor(root, d.findings.filter((f) => f.token).map((f) => f.file));
+        const read = await readerFor(root, d.findings.filter((f) => nameToWrite(f)).map((f) => f.file));
         const { result, next } = planFix(d, read);
         const writing = opts.write === true;
         if (writing)

package/dist/commands/hook.js

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { appendEvent } from "../doctor/ledger.js";
-import { diagnose, scanSource } from "../doctor/scan.js";
+import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
 import { loadSystem } from "./doctor.js";
 const pass = () => ({ continue: true });
 const speak = (context) => ({
@@ -56,7 +56,7 @@ async function report(root, filePath) {
         return null;
     const rel = relative(root, filePath);
     const d = diagnose([scanSource(rel, src, table)]);
-    const named = d.findings.filter((f) => f.token);
+    const named = d.findings.filter((f) => nameToWrite(f));
     const phantoms = d.files.flatMap((f) => f.phantoms ?? []);
     // Every check leaves one line in the ledger - INCLUDING the clean ones,
     // because a fix is itself a write, so the clean re-check of a file that was
@@ -83,7 +83,7 @@ async function report(root, filePath) {
     if (named.length > 0) {
         lines.push("", "Values written by hand that this system already has a name for:", ...named
             .slice(0, 20)
-            .map((f) => `  line ${f.line}  ${f.literal} → ${f.token}`), "", "Replace them now, while you still have this file in mind.");
+            .map((f) => `  line ${f.line}  ${f.literal} → ${nameToWrite(f)}`), "", "Replace them now, while you still have this file in mind.");
     }
     if (phantoms.length > 0) {
         lines.push("", "Names this system does not declare. These look tokenized and apply nothing at all:", ...phantoms.slice(0, 20).map((p) => `  line ${p.line}  ${p.name}`), "", "Use a name the system has, or say which value you need and what you would call it. Do NOT invent a token.");

package/dist/commands/mcp.js

@@ -5,7 +5,7 @@ import { pinnedHookVersion } from "../agent-wiring.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
-import { diagnose, scanSource } from "../doctor/scan.js";
+import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
 import { nearestToken, tokenFor } from "../doctor/tokens.js";
 import { repoStateOf } from "../repo-state.js";
 import { component } from "./component.js";
@@ -253,8 +253,8 @@ async function checkFile(root, path) {
     if (d.findings.length > 0) {
         out.push("", "Written by hand:");
         for (const f of d.findings.slice(0, 40)) {
-            out.push(f.token
-                ? `  ${f.file}:${f.line}  ${f.literal} - this system calls it ${f.token}`
+            out.push(nameToWrite(f)
+                ? `  ${f.file}:${f.line}  ${f.literal} - this repo calls it ${nameToWrite(f)}`
                 : `  ${f.file}:${f.line}  ${f.literal} - no token holds this value`);
         }
         out.push("", "Replace the ones that have a token. For a value with none, do NOT invent a token: say which value it is and what you would call it, and let a person decide.");

package/dist/component-codegen.js

@@ -1,3 +1,4 @@
+import { PHRASING_FORMS, } from "./types.js";
 export const DEFAULT_CONVENTION = {
     prefix: "ds-",
     partSeparator: "-",
@@ -106,11 +107,22 @@ function elementFor(name, recipe) {
      * UI and a hand-written disclosure, because it reads the SHAPE.
      */
     if (tag === "button") {
-        const holdsBlock = (nodes) => nodes.some((n) => n.as === "slot" ||
-            n.as === "button" ||
-            n.as === "field" ||
-            n.as === "component" ||
-            n.as === "external" ||
+        /**
+         * A LISTA SAI DE `PHRASING_FORMS`, e a enumeração à mão estava incompleta - conserto de 14/08.
+         *
+         * Ela esquecia `heading`, `row` e `stack`, e o custo é a marcação que a lei nomeia logo acima: uma
+         * raiz `action` com um heading no topo saía como `<button><h3>…</h3></button>`. Reproduzido pelo
+         * próprio codegen:
+         *
+         *     preview.kind = "action", parts = [{ as: "heading" }]  ->  ComponentProps<"button">
+         *
+         * E o ramo abaixo já sabia que heading importa - ele devolve `article` quando o topo tem um -,
+         * então era código morto: o gate nunca deixava chegar até ele.
+         *
+         * O complemento de phrasing é a pergunta certa, e não uma lista de formas de bloco: são três nomes
+         * de um lado contra oito do outro, e a lista curta é a que não esquece um.
+         */
+        const holdsBlock = (nodes) => nodes.some((n) => !PHRASING_FORMS.includes(n.as) ||
             (n.children != null && n.children.length > 0));
         const tree = recipe.preview?.parts;
         if (tree && tree.length > 0 && holdsBlock(tree)) {

package/dist/config.js

@@ -143,19 +143,26 @@ export function intentOf(config, flag) {
         };
     return { intent: "adopt", from: "default" };
 }
-/** A frase que acompanha o relatório - ver `intentOf` para por que ela é obrigatória. */
+/**
+ * A frase que acompanha o relatório - ver `intentOf` para por que ela é obrigatória.
+ *
+ * E ELA DIZ O QUE FAZ, não como a gente chama - dono, 13/08, sobre a saída inteira do doctor:
+ * *"ele quer saber do que é feito no projeto dele"*. `ADOPTION` e `MIGRATION` são a nossa taxonomia,
+ * e quem lê esta linha não tem como saber que uma ordena por "já tem nome" e a outra por "ainda não
+ * tem". A informação é a ORDEM DA LISTA que ele está prestes a ler, então é isso que a frase diz.
+ */
 export function describeIntent(source) {
     const what = source.intent === "migrate"
-        ? "reading as a MIGRATION - values your system does not name yet come first"
-        : "reading as ADOPTION - values your system already names come first";
+        ? "sorted by what your design system does not name yet"
+        : "sorted by what your design system already names";
     const where = source.from === "flag"
         ? "this run only"
         : source.from === "config"
             ? `set in _synthesisui/config.json${source.at ? ` on ${source.at.slice(0, 10)}` : ""}`
-            : "nobody declared one, so this is the default";
+            : "nobody chose, so this is the default";
     const flip = source.intent === "migrate"
-        ? "`doctor --adopt` flips it"
-        : "`doctor --migrate` flips it";
+        ? "`doctor --adopt` sorts the other way"
+        : "`doctor --migrate` sorts the other way";
     return `${what} · ${where} · ${flip}`;
 }
 /** Writes the project config (committable, plain JSON). */