synthesisui 0.16.373 → 0.16.375

package/dist/commands/doctor.js

@@ -589,6 +589,55 @@ async function readWiring(root, slug) {
 }
 /** Onde o retrato mora por default: dentro do que a esteira já escreve, e commitável. */
 const DEFAULT_BASELINE = "_synthesisui/drift-baseline.json";
+/**
+ * A PORTA ÚNICA DO `--fix` - e ela existe porque o conserto passou a ter DOIS chamadores.
+ *
+ * O caminho normal chama com o diagnóstico inteiro. O caminho de um projeto sem fiação chama com o
+ * subconjunto que o código DELE já resolve - ver `ownName` e o bloco que decide isso. Duas cópias
+ * desta sequência divergiriam no dia em que uma delas ganhasse um passo: o `writeFix` sem o
+ * `appendEvent`, ou o recibo sem a linha que manda ler o diff.
+ */
+async function runFix(root, d, writing) {
+    const read = await readerFor(root, d.findings.filter((f) => nameToWrite(f)).map((f) => f.file));
+    const { result, next } = planFix(d, read);
+    if (writing)
+        await writeFix(root, next);
+    console.log(section(writing ? "Fixed what had an answer" : "What --fix would do"));
+    for (const line of describeFix(result, !writing))
+        console.log(body(line));
+    if (!writing && result.applied.length > 0) {
+        console.log("");
+        console.log(body("Nothing was written. When the list above is what you want:"));
+        console.log(paint.blue(snippet(["npx synthesisui@latest doctor --fix --write"])));
+    }
+    /**
+     * O CONSERTO DEIXA RASTRO - ver `CheckEvent.kind: "fix"`.
+     *
+     * Sem esta linha, "ele trocou 129 valores por token" existia só no terminal daquele minuto: o
+     * ledger deduz conserto por arquivo que limpou, e um `--fix` que toca 79 arquivos de uma vez não
+     * aparece como um ato.
+     */
+    if (writing && result.applied.length > 0) {
+        await appendEvent(root, {
+            kind: "fix",
+            at: new Date().toISOString(),
+            named: result.applied.length,
+        });
+        console.log("");
+        console.log(body(paint.dim("Read the diff before committing - it is your code, and this replaced literals with the tokens your own system declares.")));
+    }
+}
+/**
+ * O NOME QUE ESTA TROCA ESCREVERIA É DELE? - a pergunta que a recusa do `--fix` nunca fez.
+ *
+ * `nameToWrite` devolve `theirToken ?? token`: quando o repositório dele nomeia aquele valor, é o
+ * nome DELE que vai para o código. Um nome dele resolve no navegador dele HOJE, com ou sem a nossa
+ * folha instalada - a folha só é necessária para os `--ds-*`, que são nossos.
+ */
+const ownName = (f) => {
+    const name = nameToWrite(f);
+    return Boolean(name && !name.startsWith("--ds-"));
+};
 export async function doctor(opts) {
     const root = resolve(opts.dir ?? process.cwd());
     /**
@@ -982,9 +1031,42 @@ export async function doctor(opts) {
             }).catch(() => { });
         console.log("");
         if (opts.fix) {
-            /** `1 ... do have` saía assim desde sempre; a frase que recusa um comando não pode tropeçar. */
-            const one = d.named === 1;
-            console.log(body(`--fix is refused while ${bothMissing ? "those two are" : "that one is"} false. ${d.named} of your hand-written values`));
+            /**
+             * A RECUSA PASSA A SER POR VALOR, E NÃO PELO COMANDO INTEIRO.
+             *
+             * NASCEU DE UMA PERGUNTA DO DONO (04/09): *"se o design system dele já está funcionando e são
+             * as mesmas referências, faz sentido esse ligamento? combinamos que não seria invasivo"*.
+             *
+             * A MEDIÇÃO DEU RAZÃO A ELE, pelo mesmo caminho que a tela usa (`loadSystem` + `scanSource` +
+             * `diagnose` sobre packages/ui + apps/landing + apps/web do codelevel): dos 216 valores com
+             * nome esperando, **156 (72%) escreveriam o nome DELE** - `--color-brand-violet`,
+             * `--color-tier-gold`, `--duration-base` - e esses resolvem no navegador dele HOJE, sem folha
+             * nenhuma instalada. Só 60 apontam para `--ds-*`, que são nossos e precisam da fiação.
+             *
+             * A recusa olhava `blocked` e nada mais. Ela nunca perguntava de quem era o nome que ia
+             * escrever, embora `nameToWrite` já responda isso (`theirToken ?? token`). O produto recusava
+             * 156 consertos que funcionariam para proteger 60 que quebrariam - e cobrava, em troca, uma
+             * folha inteira dentro do app de alguém que só queria governar o próprio vocabulário.
+             *
+             * ISSO ATINGE O CASO DE USO CENTRAL: quem importa um design system que já existe tem, por
+             * construção, a maioria dos nomes sendo dele.
+             *
+             * O QUE FICA DE FORA CONTINUA SENDO DITO, com o número e o motivo - Lei 8. O que muda é que a
+             * lacuna deixou de fechar a porta inteira.
+             */
+            const theirs = d.findings.filter(ownName).length;
+            const ours = d.findings.filter((f) => nameToWrite(f) && !ownName(f)).length;
+            if (theirs > 0) {
+                console.log(body(`${theirs} of your hand-written values ${theirs === 1 ? "carries" : "carry"} a name your own code declares, and ${theirs === 1 ? "it resolves" : "those resolve"} today - --fix will swap ${theirs === 1 ? "it" : "them"}.`));
+                if (ours > 0)
+                    console.log(body(`${ours} more point at ${table.name ?? table.slug} tokens, which only resolve once the wiring above is done. Left alone.`));
+                console.log("");
+                await runFix(root, { ...d, findings: d.findings.filter(ownName) }, opts.write === true);
+                return;
+            }
+            /** Nenhum nome dele em jogo: aqui a recusa continua sendo a resposta certa, e inteira. */
+            const one = ours === 1;
+            console.log(body(`--fix is refused while ${bothMissing ? "those two are" : "that one is"} false. ${ours} of your hand-written values`));
             console.log(body(`${one ? "does" : "do"} have a name in the system, and swapping ${one ? "it" : "them"} now would point ${one ? "it" : "them"} at`));
             console.log(body(`variables the browser cannot resolve - the ${one ? "declaration" : "declarations"} would be dropped`));
             console.log(body(`and the page would change. Wire ${bothMissing ? "the two lines" : "that line"} first.`));
@@ -1878,37 +1960,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) => nameToWrite(f)).map((f) => f.file));
-        const { result, next } = planFix(d, read);
-        const writing = opts.write === true;
-        if (writing)
-            await writeFix(root, next);
-        console.log(section(writing ? "Fixed what had an answer" : "What --fix would do"));
-        for (const line of describeFix(result, !writing))
-            console.log(body(line));
-        if (!writing && result.applied.length > 0) {
-            console.log("");
-            console.log(body("Nothing was written. When the list above is what you want:"));
-            console.log(paint.blue(snippet(["npx synthesisui@latest doctor --fix --write"])));
-        }
-        /**
-         * O CONSERTO DEIXA RASTRO - ver `CheckEvent.kind: "fix"`.
-         *
-         * Sem esta linha, "ele trocou 129 valores por token" existia só no terminal daquele minuto: o
-         * ledger deduz conserto por arquivo que limpou, e um `--fix` que toca 79 arquivos de uma vez não
-         * aparece como um ato.
-         */
-        if (writing && result.applied.length > 0) {
-            await appendEvent(root, {
-                kind: "fix",
-                at: new Date().toISOString(),
-                named: result.applied.length,
-            });
-        }
-        if (writing && result.applied.length > 0) {
-            console.log("");
-            console.log(body(paint.dim("Read the diff before committing - it is your code, and this replaced literals with the tokens your own system declares.")));
-        }
+        await runFix(root, d, opts.write === true);
         return;
     }
     if (opts.writeBaseline) {

package/dist/doctor/apply-fix.js

@@ -51,6 +51,8 @@ export function planFix(d, read) {
     const next = new Map();
     /** Linhas por arquivo, mutadas em memória: dois achados no mesmo arquivo compõem. */
     const lines = new Map();
+    /** A mesma chave, congelada antes da primeira troca - ver o skip de `not-written`. */
+    const originals = new Map();
     /**
      * DE BAIXO PARA CIMA no arquivo não é necessário - a troca não muda a contagem de linhas - mas a
      * ORDEM por arquivo é, para dois achados na mesma linha não se atropelarem: o segundo procura o seu
@@ -119,6 +121,11 @@ export function planFix(d, read) {
                 continue;
             }
             lines.set(f.file, raw.split("\n"));
+            /**
+             * A LINHA COMO ELA ESTAVA ANTES DE QUALQUER TROCA DESTA RODADA - e é ela que separa dois
+             * skips que hoje se dizem com a mesma frase. Ver o bloco de `swapped === null`.
+             */
+            originals.set(f.file, raw.split("\n"));
         }
         const body = lines.get(f.file);
         if (!body)
@@ -127,12 +134,38 @@ export function planFix(d, read) {
         const current = body[idx];
         const swapped = current === undefined ? null : swap(current, f.literal, name);
         if (swapped === null) {
-            /** O arquivo mudou desde a medição, ou o literal já foi trocado por outro achado. */
+            /**
+             * DOIS MOTIVOS DIFERENTES, E A TELA DIZIA UM SÓ - e o que ela dizia era falso quase sempre.
+             *
+             * O QUE O DONO VIU em 05/09: *"13 lines changed since the scan and were left alone - run it
+             * again"*, num repositório onde ele não tinha editado nada. Medido: **13 de 13** eram classe
+             * utilitária. A linha era `"transition-all duration-300 ease-[var(--ease-out-soft)]"`, o scan
+             * derivou `300ms` de `duration-300` - corretamente -, e o `swap` procura o texto `300ms`, que
+             * nunca esteve escrito ali. `grep 300ms` no arquivo devolve zero.
+             *
+             * O comentário que estava aqui já sabia disso: *"o arquivo mudou desde a medição, OU o literal
+             * já foi trocado por outro achado"*. A frase impressa contava só o primeiro caso, e mandava
+             * rodar de novo - o que não muda nada, porque nada mudou.
+             *
+             * A LINHA ORIGINAL DESEMPATA. Sem o literal nela, o valor veio de forma abreviada e trocá-lo é
+             * outra reescrita (`duration-[var(--duration-base)]`), não uma troca de literal. Com o literal
+             * nela, alguma coisa mexeu na linha depois - e aí rodar de novo é o conselho certo.
+             *
+             * É GERAL: `duration-*` é Tailwind puro - 15 arquivos no repositório dele, 37 no frontend-hub.
+             */
+            /**
+             * A LINHA SUMIU É OUTRA COISA - e é `moved` de verdade: um arquivo que encolheu desde a
+             * medição mudou, e rodar de novo é o conselho certo. `not-written` só quando a linha ESTÁ lá
+             * e o valor não está escrito nela.
+             */
+            const before = originals.get(f.file)?.[idx];
             skipped.push({
                 file: f.file,
                 line: f.line,
                 literal: f.literal,
-                because: "moved",
+                because: before === undefined || before.includes(f.literal)
+                    ? "moved"
+                    : "not-written",
             });
             continue;
         }
@@ -176,6 +209,8 @@ export async function readerFor(root, files) {
 export function describeFix(result, dry) {
     const { applied, skipped } = result;
     const moved = skipped.filter((s) => s.because === "moved").length;
+    /** O valor veio de forma abreviada - ver `not-written` em `planFix`. */
+    const notWritten = skipped.filter((s) => s.because === "not-written").length;
     const coincidence = skipped.filter((s) => s.because === "cross-family").length;
     const unread = skipped.filter((s) => s.because === "unreadable").length;
     const decisions = skipped.filter((s) => s.because === "no-token").length;
@@ -187,23 +222,55 @@ export function describeFix(result, dry) {
             ? `Nothing to apply. All ${decisions} findings are values your system has no name for - those are design decisions, not fixes.`
             : relative > 0
                 ? `Nothing to apply. All ${relative} findings are lengths in \`em\`, which follow the element's font size - swapping them can move the layout, so that call is yours.`
-                : "Nothing to apply.");
+                : /**
+                   * E QUANDO NADA É APLICÁVEL, O MOTIVO SAI AQUI TAMBÉM - senão a saída inteira é
+                   * "Nothing to apply." e a pessoa não tem como saber que o valor existe, tem nome, e só
+                   * não está escrito como texto.
+                   */
+                    notWritten > 0
+                        ? `Nothing to apply. All ${notWritten} findings are written as a shorthand - a utility class like \`duration-300\` carries the value in its name, so there is no literal on the line to replace. Changing them is a different rewrite.`
+                        : "Nothing to apply.");
         return lines;
     }
     lines.push(`${dry ? "Would replace" : "Replaced"} ${applied.length} hand-written value${applied.length === 1 ? "" : "s"} with the token your system already has, across ${result.files} file${result.files === 1 ? "" : "s"}.`);
     const byToken = new Map();
     for (const a of applied)
         byToken.set(a.token, (byToken.get(a.token) ?? 0) + 1);
-    for (const [token, n] of [...byToken.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 6))
+    const ranked = [...byToken.entries()].sort((a, b) => b[1] - a[1]);
+    const SHOWN = 6;
+    for (const [token, n] of ranked.slice(0, SHOWN))
         lines.push(`  var(${token}) · ${n} time${n === 1 ? "" : "s"}`);
+    /**
+     * O QUE O CORTE ESCONDEU, DITO - e é a mesma lei que a linha abaixo já obedece.
+     *
+     * O QUE O DONO VIU em 05/09: `Would replace 143 ... across 20 files` e seis linhas somando 81. As
+     * outras 62 ocorrências não apareciam em lugar nenhum, e ele aprovaria a escrita sem saber que
+     * existiam.
+     *
+     * O comentário três linhas abaixo já enuncia a regra - *"DITO SEMPRE QUE ACONTECE, senão o número
+     * some da conta sem explicação"* -, aplicada ao `relative` e ao `moved` e não ao próprio corte
+     * desta lista. Terceira vez nesta família num dia: o `gaps` (#1327) e a tela de admin (#1304).
+     */
+    const rest = ranked.slice(SHOWN);
+    if (rest.length > 0) {
+        const restUses = rest.reduce((n, [, uses]) => n + uses, 0);
+        lines.push(`  and ${restUses} more across ${rest.length} other token${rest.length === 1 ? "" : "s"}, not listed here`);
+    }
     /**
      * DITO SEMPRE QUE ACONTECE - senão o número de "trocado" some da conta sem explicação, e a pessoa
      * conclui que o comando falhou onde ele se recusou de propósito.
      */
     if (relative > 0)
         lines.push(`  ${relative} more ${relative === 1 ? "is a length" : "are lengths"} in \`em\`, which follow the element's font size - your system names the same number, but the pixel may differ. Left for you to decide.`);
+    /**
+     * O VALOR QUE NÃO ESTÁ ESCRITO - a frase que substituiu uma afirmação falsa sobre o repositório.
+     *
+     * Isto saía como *"N lines changed since the scan - run it again"*, e na tela do dono nada tinha
+     * mudado: 13 de 13 eram `duration-300` e afins. Mandar rodar de novo não muda nada, e mandar
+     * alguém procurar uma edição que ela não fez é pior que calar.
+     */
+    if (notWritten > 0)
+        lines.push(`  ${notWritten} more ${notWritten === 1 ? "is" : "are"} written as a shorthand - a utility class like \`duration-300\` carries the value in its name, so there is no literal on the line to replace. Changing ${notWritten === 1 ? "it" : "those"} is a different rewrite. Left alone.`);
     if (moved > 0)
         lines.push(`${moved} line${moved === 1 ? "" : "s"} changed since the scan and ${moved === 1 ? "was" : "were"} left alone - run it again.`);
     if (coincidence > 0)

package/package.json

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