synthesisui 0.16.421 → 0.16.423

package/dist/commands/doctor.js

@@ -12,25 +12,16 @@ import { appendEvent, COVERAGE_RULE, COVERAGE_RULE_REASON, readEvents, suggestio
 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, nameToWrite, scanSource, siblingTokens, } from "../doctor/scan.js";
+import { diagnose, nameToWrite, ourNameOnly, 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 { parseRules } from "../doctrine.js";
-/**
- * `detectAppDirs` SAIU DESTE IMPORT em 09/09: quem pergunta "quais pastas são app?" agora é
- * `readWiringPerApp`, que responde a fiação de cada uma. O comando não escolhe mais um app.
- */
-import { globalSheetOf, prefixFrom } from "../global-sheet.js";
 import { groupRole } from "../group-role.js";
 import { actingSlug, describeScope, measuredScope, scopePaths, } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
-import { setupPrompt } from "../setup-prompt.js";
-import { installedThemeCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js";
 import { resolveDeps } from "../stack.js";
-import { projectTongue } from "../their-tongue.js";
 import { danglingTheirVars } from "../their-vars.js";
-import { readWiring, readWiringPerApp } from "../wiring-read.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -617,17 +608,6 @@ async function runFix(root, d, writing) {
         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());
     /**
@@ -743,15 +723,6 @@ export async function doctor(opts) {
      *
      * Nobody debugs from 0%. They conclude the product does not work.
      */
-    const wiring = await readWiring(root, table.slug);
-    /**
-     * O QUE, NESTE REPOSITÓRIO, SÓ A NOSSA FOLHA RESOLVE - acumulado na varredura QUE JÁ ACONTECE.
-     *
-     * Uma segunda passada pelo disco para responder isto custaria o dobro num repositório de 178
-     * arquivos, e a resposta está no mesmo texto que o scan já tem na mão. Ver `sheet-needed.ts`.
-     */
-    const themeCss = table.slug ? await installedThemeCss(root, table.slug) : "";
-    let scannedSource = "";
     const skippedProjects = [];
     const tally = emptyTally();
     const internalSpecs = await internalSpecifiers(root);
@@ -763,9 +734,6 @@ export async function doctor(opts) {
             continue;
         const rel = relative(root, file);
         reports.push(scanSource(rel, src, table));
-        /** A pasta que a plataforma escreve não conta: ela É a folha, não um consumidor dela. */
-        if (!rel.startsWith("_synthesisui"))
-            scannedSource += `\n${src}`;
         // Composition, alongside values: the contract check needs to know which
         // elements this file writes and with what options. Stories and tests are
         // excluded for the reason they are excluded everywhere else - they compose
@@ -916,304 +884,28 @@ export async function doctor(opts) {
      * distinção em vez de cada tela refazê-la. Ver `Reach` em `scan.ts`.
      */
     const measurable = d.reach.measured;
-    // Before the number, because the number is the thing that misleads. An
-    // installed-but-unwired system reads 0%, and 0% reads as "broken product"
-    // rather than "one import missing".
-    // Fonts only count as missing when `init` actually wrote the file - a
-    // non-Next project has no fonts.ts and must not be nagged about one.
-    const fontsPending = wiring.fontsWritten && !wiring.fontsMapped;
     /**
-     * A FIAÇÃO É PORTÃO, e não um aviso ao lado de um número.
+     * A FIAÇÃO SAIU DAQUI EM 11/09, e com ela o portão inteiro - `INV-GERAL-13`.
      *
-     * Sem o `@import` ou sem o `data-ds`, os tokens não chegam ao navegador. Até 06/08 a tela dizia isso
-     * e, três linhas abaixo, imprimia uma barra de 0% e uma lista de cinco prioridades - se contradizendo
-     * na mesma tela (dono: "fiquei perdido"). Ou o número não significa nada, ou existe uma lista de
-     * prioridades; as duas não cabem juntas.
-     */
-    /**
-     * A FIAÇÃO SÓ EXISTE PARA UM SISTEMA NOSSO - e usar "tem nomes" no lugar disso recusava o
-     * `--fix` a quem nunca instalou nada (medido em 18/08, no caminho de quem começa do zero).
-     *
-     * Ela escreve os tokens dela no próprio `:root`, o doctor passa a dizer "7 dos seus valores
-     * têm nome", e o `--fix` respondia "trocar agora apontaria para variáveis que o navegador não
-     * resolve". Ele resolve: o CSS é dela e já está na página. A frase era literalmente falsa, e
-     * ela aparece no primeiro comando que promete adotar.
-     *
-     * `table.source` é a distinção certa e ela já estava aqui, uma linha abaixo, em `unwired`:
-     * `"yours"` e `"adopted"` são o vocabulário dela, e não há duas linhas para ligar.
-     */
-    const sheetNeed = whatOnlyTheSheetResolves({
-        source: scannedSource,
-        themeCss,
-        theirNames: installed.theirs.byName.keys(),
-        /**
-         * A TERCEIRA FONTE NÃO É MEDIDA AQUI - ver o mesmo comentário em `component.ts` e o número em
-         * `steps/11-fora-do-escopo.md`. Este comando decide `unwired` e `blocked` por `needed`, então
-         * ligar a medição muda o veredito do `doctor` num repositório real: é etapa própria, e o vazio
-         * deixa a omissão escrita em vez de escondida.
-         */
-        sheetCss: "",
-    });
-    /**
-     * BLOQUEADO SÓ QUANDO A FOLHA É NECESSÁRIA - a mesma pergunta que decide `unwired`.
+     * O QUE ESTE TRECHO FAZIA, em 250 linhas: media se algo neste repositório ainda precisava da nossa
+     * folha, imprimia *"<sistema> is installed - but this project does not load it yet"*, listava os
+     * `✗` de `@import` e `data-ds`, colava um prompt de setup para o agente dele, e RECUSAVA o
+     * `--fix` enquanto aquilo não fosse feito.
      *
-     * Sem esta condição, o comando parava de cobrar a fiação lá em cima e continuava recusando o
-     * `--fix` aqui embaixo, fechando com *"esse número fica acionável no momento em que as duas forem
-     * verdade"* - duas condições que ele mesmo tinha acabado de deixar de pedir. Um relatório que
-     * retira a exigência numa seção e a mantém na outra ensina que nenhuma das duas é para valer.
-     */
-    const blocked = table.source === "installed" &&
-        sheetNeed.needed &&
-        (!wiring.imported || !wiring.scoped);
-    /**
-     * QUANTAS DAS DUAS FALTAM - e sem este número três frases mandavam consertar DUAS coisas quando
-     * faltava UMA.
+     * O QUE O DONO LEU NA PRÓPRIA TELA (11/09): *"isso nunca deve acontecer, a gente havia combinado
+     * (...) garanta que nunca mais você irá falar desse import e nem solicitar e nem precisar nos
+     * projetos"*.
      *
-     * `blocked` é um OU, e as frases que ele governa foram escritas assumindo o E: *"Until both are
-     * true"*, *"--fix is refused while those two are false"* e *"Wire the two lines first"*. Visto na
-     * máquina do dono em 04/09, num repositório onde `data-ds` já estava lá com um ✓ impresso três
-     * linhas acima: a tela contradizia a própria lista, e a terceira frase é INSTRUÇÃO - a pessoa está
-     * bloqueada, procurando o que escrever, e ela manda escrever duas linhas.
+     * E A PERGUNTA MORREU COM A CAUSA, não com o texto. Nada que a plataforma escreve no repositório
+     * dele carrega uma variável nossa (`their-tongue.ts`) nem um utilitário que dependa do nosso
+     * `@theme` (`theirThemeVars`), e o `--fix` só escreve nomes que o código dele declara
+     * (`nameToWrite`). Então não sobra nada para uma folha nossa resolver: não há fiação a medir, não
+     * há o que cobrar, e não há por que recusar o `--fix`.
      *
-     * O caso de faltar UMA é o mais comum: uma instalação que parou no meio erra um dos dois passos,
-     * não os dois. Derivado da mesma leitura que decide `blocked`, para as duas nunca discordarem.
+     * A RECUSA ERA O PIOR PEDAÇO. Medido no `codelevel` em 04/09: das 216 trocas com nome esperando,
+     * 156 (72%) escreviam o nome DELE e resolviam no navegador dele naquele dia - e o comando recusava
+     * as 156 para proteger as 60 que apontavam para nós. Essas 60 não existem mais.
      */
-    const missingWiring = (wiring.imported ? 0 : 1) + (wiring.scoped ? 0 : 1);
-    const bothMissing = missingWiring === 2;
-    /**
-     * A FIAÇÃO SÓ É COBRADA QUANDO ALGUMA COISA NESTE REPOSITÓRIO PRECISA DELA - ver `sheet-needed.ts`.
-     *
-     * O DEFEITO, apontado pelo dono em 07/09 sobre o próprio repositório: *"por que a gente precisa
-     * desses imports, visto que o design do projeto dele já funciona? criar esse import gera
-     * dependência ao design system, que é coisa que a gente não quer - a gente quer isolar os dois
-     * pontos, sendo que o nosso deve ser apenas uma REFERÊNCIA para que qualquer agente que gera
-     * código saiba como utilizar o design system"*.
-     *
-     * MEDIDO NO `codelevel` no mesmo dia: no repositório inteiro, apenas dois arquivos mencionam
-     * `--ds-*` - um componente que a PLATAFORMA gerou com uma versão anterior à tradução, e a costura
-     * de tipografia que o nosso próprio setup pediu. Zero linhas do código que ELE escreveu. Regerado
-     * com o CLI de hoje, o componente sai com 0 referências à nossa folha, e as duas animações que ele
-     * veste são declaradas pelo `globals.css` dele.
-     *
-     * Ou seja: o comando cobrava uma dependência de runtime que nada naquele repositório usava - e o
-     * produto já promete o contrário em `their-tongue.ts` (*"nenhuma folha nossa precisa existir no
-     * repositório dele"*). As duas metades discordavam porque nenhuma perguntava.
-     *
-     * O ESCOPO (`data-ds`) SEGUE A MESMA REGRA e pelo mesmo motivo: ele existe para a folha aplicar
-     * dentro dele. Sem folha necessária, um atributo na árvore dele é a mesma dependência com outro
-     * nome.
-     *
-     * E QUANDO ALGO PRECISA, tudo continua exatamente como era - inclusive o roteiro para o agente. A
-     * mudança não é deixar de cobrar: é parar de cobrar sem ter perguntado.
-     */
-    const unwired = table.source === "installed" &&
-        sheetNeed.needed &&
-        (!wiring.imported || !wiring.scoped || fontsPending);
-    if (unwired) {
-        console.log("");
-        console.log(body(`${table.name ?? table.slug} is installed - but this project does not load it yet.`));
-        console.log("");
-        /**
-         * O QUE ESTÁ COBRANDO A FOLHA, POR NOME - senão a exigência lê como uma regra nossa.
-         *
-         * Ela não é: é um efeito do que ESTE repositório escreveu. Medido no `codelevel` (07/09), as
-         * duas coisas que a exigiam eram um componente gerado por uma versão anterior à tradução do CLI
-         * e a costura de tipografia que o nosso próprio setup pediu - nenhuma linha do código dele.
-         * Regerado com o CLI de hoje, o mesmo componente sai com zero referências e a exigência some.
-         *
-         * Sem esta linha, quem lê não tem como saber que a dependência é REMOVÍVEL, e a única saída
-         * visível é aceitar o import.
-         */
-        /**
-         * E A SAÍDA SÓ É OFERECIDA QUANDO ELA EXISTE - senão o comando manda consertar o que não conserta.
-         *
-         * "re-run `component` and it speaks your own names instead" só é verdade onde há MAPA: onde algum
-         * valor do sistema coincide com um nome que o repositório dele já declara. Sem mapa, a tradução
-         * roda e não tem o que traduzir, regerar devolve o mesmo arquivo, e a folha é o caminho legítimo.
-         *
-         * MEDIDO EM 07/09, validando o binário publicado num `create-next-app` que instalou o
-         * `codelevel`: `.lock` sem `tokenMap`, o componente saiu com 14 linhas `--ds-*`, e esta frase
-         * mandava regerar. No `codelevel-monorepo`, onde o `.lock` tem 33 pares, regerar É a saída - e o
-         * mesmo texto servia os dois. É o defeito que o `CLAUDE.md` registra em primeira pessoa: afirmar
-         * que um comando conserta o que ele não conserta.
-         */
-        const translatable = (await projectTongue(root, table.slug ?? "")) !== null;
-        const asks = sheetNeed.variables.length > 0
-            ? `${sheetNeed.variables.slice(0, 3).join(", ")}${sheetNeed.variables.length > 3 ? `, +${sheetNeed.variables.length - 3} more` : ""}${translatable
-                ? ` - re-run \`component\` on whatever writes ${sheetNeed.variables.length === 1 ? "it" : "them"} and it speaks your own names instead`
-                : ` - your code names no value this system also holds, so there is nothing to translate ${sheetNeed.variables.length === 1 ? "it" : "them"} into, and the sheet is the way`}`
-            : `the ${sheetNeed.classes.slice(0, 3).join(", ")}${sheetNeed.classes.length > 3 ? `, +${sheetNeed.classes.length - 3} more` : ""} ${sheetNeed.classes.length === 1 ? "utility" : "utilities"}, which only this system's @theme generates`;
-        console.log(body(`  what asks for it: ${asks}`));
-        console.log("");
-        console.log(body(wiring.imported
-            ? `  ✓ some stylesheet imports _synthesisui/ds/${table.slug}/tokens.css`
-            : `  ✗ no stylesheet imports _synthesisui/ds/${table.slug}/tokens.css`));
-        console.log(body(wiring.scoped
-            ? `  ✓ data-ds="${table.slug}" found`
-            : `  ✗ no element carries data-ds="${table.slug}"`));
-        if (wiring.fontsWritten) {
-            console.log(body(wiring.fontsMapped
-                ? "  ✓ the type from fonts.ts is mapped onto the system"
-                : "  ✗ fonts.ts exists but nothing maps it - the system's type is not being used"));
-        }
-        console.log("");
-        // Three requirements now, and they fail differently. Missing the import or
-        // the scope means NOTHING reaches the browser and the number below is
-        // noise. Missing only the type mapping means colour and spacing are
-        // working and the faces are not - saying "nothing reaches the browser"
-        // there would be false, and a report that overstates is one nobody trusts
-        // the next time.
-        if (blocked) {
-            /**
-             * A FRASE SEGUE O QUE VEM DEPOIS DELA. Ela dizia "o número abaixo não pode significar nada"
-             * enquanto imprimia o número abaixo; agora não há número abaixo, e prometer um seria a mesma
-             * incoerência ao contrário.
-             */
-            console.log(body(bothMissing
-                ? `Until both are true, none of the ${table.byName.size} tokens reach the browser.`
-                : `Until that one is true, none of the ${table.byName.size} tokens reach the browser.`));
-        }
-        else {
-            console.log(body("Colour and spacing are working. Type is not: the system's faces"));
-            console.log(body("are declared and nothing points at them, so the page renders in"));
-            console.log(body("whatever the framework picked."));
-        }
-        /**
-         * A FIAÇÃO SAI DAQUI, e não de outro comando - achado do dono em 06/09, rodando o `upgrade`.
-         *
-         * O QUE ELE VIU: o doctor diz `installed - but not wired up yet` e *"none of the 66 tokens
-         * reach the browser"*, e a linha seguinte mandava ler *"the output of `init`"*. `init` é o
-         * comando de PRIMEIRA VEZ - ele instala um sistema em quem não tem nenhum. Quem chegou até
-         * aqui já importou, materializou e rodou upgrade: mandá-lo ao `init` é devolver ao começo
-         * alguém que está a um passo do fim.
-         *
-         * E O PASSO JÁ EXISTIA PRONTO. `setupPrompt` mora em `setup-prompt.ts`, exportado, e era
-         * usado só pelo `init`. Imprimi-lo aqui não é texto novo: é a MESMA fonte chegando na tela
-         * onde a pergunta nasce. Duas redações do mesmo passo divergiriam no primeiro conserto.
-         *
-         * O PROMPT LEVA A MEDIÇÃO, e até 07/09 ele era FIXO - o defeito que o dono leu na própria tela.
-         *
-         * As três linhas acima acabaram de imprimir `✗ ✓ ✓`: só o import faltava. O texto seguinte
-         * mandava *"Do the ONE-TIME SETUP it names, all of it"* e listava as três, então um agente
-         * obediente reescreve o escopo e o mapa de tipografia que já estavam corretos - contra a última
-         * linha do próprio texto, que pede para não mexer nos estilos dele. Um comando que mede e depois
-         * diz outra coisa gasta a medição.
-         *
-         * E A FOLHA TEM NOME, ao contrário do que este comentário dizia antes. `globalSheetOf` +
-         * `prefixFrom` são as mesmas funções que o `add` usa para achar a folha que os apps REALMENTE
-         * carregam - num monorepo não é o `globals.css` do app - e para contar o caminho relativo até a
-         * raiz. Elas existiam e este comando não as chamava; então ele descrevia o arquivo em vez de
-         * nomeá-lo, e o agente tinha que redescobrir o que a gente já sabia.
-         *
-         * Quando a derivação falha, `sheet` fica ausente e o texto volta a descrever - nenhum caminho é
-         * inventado.
-         */
-        if (table.slug) {
-            /**
-             * A INSTRUÇÃO É POR APP, e não do primeiro deles.
-             *
-             * O DEFEITO: esta linha era `appDirs[0]` - num monorepo com três apps servidos, dois recebiam
-             * a instrução do PRIMEIRO, com a folha e o prefixo relativo de outro app. É o mesmo defeito
-             * que `INV-VOLTA-12` fechou uma vez ("ele seguiu a instrução no arquivo CERTO e recebeu de nós
-             * o prefixo do arquivo errado"), voltando pela porta do plural: a invariante fala de "os apps
-             * dele", e o comando respondia por um.
-             *
-             * E A FIAÇÃO TAMBÉM É POR APP (`readWiringPerApp`): `readWiring` varre a raiz e responde
-             * "existe em algum lugar daqui", então o app fiado respondia pelo que não estava - e a pessoa
-             * abria o app sem nada e o comando dizia que estava tudo certo.
-             *
-             * COM UM APP, o texto não muda em byte nenhum - é a maioria dos projetos, e um cabeçalho
-             * por app ali seria cerimônia sobre uma lista de um.
-             */
-            const perApp = await readWiringPerApp(root, table.slug, config.pagesDir);
-            const targets = perApp.length > 0 ? perApp : [{ app: null, wiring }];
-            /**
-             * OS APPS QUE PEDEM A MESMA COISA VIRAM UM BLOCO SÓ, nomeando os dois.
-             *
-             * O DEFEITO, e ele é meu, do PR de algumas horas atrás: no `codelevel-monorepo` os DOIS apps
-             * resolvem para a MESMA folha (`packages/ui/src/styles/globals.css`, o pacote compartilhado),
-             * então o comando imprimiu a mesma instrução de 40 linhas DUAS VEZES, com o mesmo caminho e o
-             * mesmo prefixo. O dono leu a parede duas vezes (medido no repositório dele, 09/09).
-             *
-             * Eu tinha escrito o aviso no comentário abaixo - *"num monorepo ele apareceria em escala:
-             * dois blocos idênticos"* - sobre o caso do app JÁ FIADO, e entreguei a duplicata no caso do
-             * que ainda falta. Nomear cada app foi o conserto certo; repetir a instrução não.
-             *
-             * A CHAVE É A INSTRUÇÃO, não o app: dois apps com a mesma folha, o mesmo prefixo e os mesmos
-             * passos pendentes recebem uma instrução só. Um monorepo onde cada app tem folha própria volta
-             * a receber uma por app, porque ali as instruções DIFEREM - é a resposta derivada, e não uma
-             * regra sobre quantos apps existem.
-             */
-            const blocks = new Map();
-            for (const { app, wiring: w } of targets) {
-                const sheet = app
-                    ? await globalSheetOf(root, `${app}/globals.css`)
-                    : null;
-                /**
-                 * O APP QUE JÁ ESTÁ FIADO SAI DA LISTA, nomeado. Repetir o setup para quem já o fez é o
-                 * defeito de 08/09 outra vez.
-                 */
-                const pending = !w.imported || !w.scoped || (w.fontsWritten && !w.fontsMapped);
-                const text = pending
-                    ? setupPrompt(table.slug, {
-                        tokens: !w.imported,
-                        scope: !w.scoped,
-                        /** Só é passo quando o projeto TEM o arquivo de fontes - ver `readWiring`. */
-                        type: w.fontsWritten && !w.fontsMapped,
-                        ...(sheet
-                            ? { sheet: { path: sheet, prefix: prefixFrom(sheet) } }
-                            : {}),
-                        /**
-                         * DUAS LINHAS COM TAILWIND, UMA SEM - a mesma decisão que o `add` já toma pelo
-                         * projeto. Dizer "as duas linhas" a um projeto que precisa de uma manda o agente
-                         * procurar o que não existe.
-                         */
-                        imports: config.styles === "css" ? 1 : 2,
-                    }).split("\n")
-                    : [];
-                const key = `${pending ? "p" : "ok"}|${text.join("\n")}`;
-                const found = blocks.get(key);
-                if (found)
-                    found.apps.push(app ?? "");
-                else
-                    blocks.set(key, { apps: [app ?? ""], text, pending });
-            }
-            const anyPending = [...blocks.values()].some((b) => b.pending);
-            if (anyPending) {
-                console.log("");
-                console.log(body("Paste this into your agent - it does the setup for you:"));
-            }
-            for (const { apps, text, pending } of blocks.values()) {
-                const named = apps.filter(Boolean);
-                /**
-                 * O CABEÇALHO SÓ APARECE QUANDO HÁ MAIS DE UM APP no projeto - com um só ele seria cerimônia
-                 * sobre uma lista de um, e a maioria dos projetos é assim. Com vários, ele diz de QUEM é a
-                 * instrução, e o plural sai naturalmente: "apps/landing/app and apps/web/app".
-                 */
-                if (targets.length > 1 && named.length > 0) {
-                    /**
-                     * A LISTA SE LÊ EM VOZ ALTA, e o número dela não é fixo: "A and B" com dois,
-                     * "A, B and C" com três. `join(" and ")` daria "A and B and C", e `"both"` mentiria
-                     * no dia em que o monorepo tiver três apps na mesma folha - o mesmo erro de
-                     * dimensionar pela amostra, na escala de uma palavra.
-                     */
-                    const lista = named.length > 1
-                        ? `${named.slice(0, -1).join(", ")} and ${named[named.length - 1]}`
-                        : named[0];
-                    console.log("");
-                    console.log(body(`  ${lista} - ${pending
-                        ? named.length > 1
-                            ? "need it, and the steps are the same"
-                            : "still needs it"
-                        : "already wired, nothing to paste"}`));
-                }
-                if (!pending)
-                    continue;
-                console.log("");
-                console.log(snippet(text));
-            }
-        }
-    }
     /**
      * A FOLHA APONTA PARA O VOCABULÁRIO DELE, E UM NOME SUMIU - ver `their-vars.ts`.
      *
@@ -1234,112 +926,26 @@ export async function doctor(opts) {
         console.log(body("Rename it back, or run `npx synthesisui add <slug>` to re-point the sheet at what you have now."));
     }
     /**
-     * E AQUI O RELATÓRIO PARA, quando a fiação está vermelha: uma instrução, e nada mais.
+     * O RELATÓRIO NÃO PARA MAIS - o `return` daqui foi embora com a fiação (`INV-GERAL-13`, 11/09).
      *
-     * O que fica de fora é justamente o que não pode ser verdade ainda - a barra de cobertura, a lista de
-     * prioridades e a oferta do `--fix`. O `--fix` é o mais grave: no repo do dono ele teria trocado 217
-     * literais por `var(--ds-…)` que não resolvem em lugar nenhum, e o navegador descarta a declaração -
-     * ou seja, o comando que promete adotar o sistema quebraria a aparência do app.
-     *
-     * O ledger é gravado ANTES de sair: a corrida aconteceu, e o histórico não pode depender de o
-     * projeto estar bem configurado.
+     * Ele existia porque, sem o `@import`, a barra de cobertura lia 0% e o `--fix` teria escrito
+     * `var(--ds-…)` que o navegador descarta. As duas razões acabaram: a cobertura conta o vocabulário
+     * dele, e o `--fix` só escreve nomes que o código dele declara. Um relatório que parava aqui hoje
+     * esconderia a cobertura de quem nunca vai importar folha nenhuma - ou seja, de todo mundo.
      */
-    if (blocked) {
-        if (fullRun)
-            await appendEvent(root, {
-                kind: "doctor",
-                at: new Date().toISOString(),
-                ...(d.reach.measured ? { coverage: d.reach.percent } : {}),
-                rule: COVERAGE_RULE,
-                named: d.named,
-                ...(d.findings.some((f) => f.crossFamily)
-                    ? { crossFamily: d.findings.filter((f) => f.crossFamily).length }
-                    : {}),
-                ...(d.repeats.some((r) => nameToWrite(r))
-                    ? { matched: suggestionsFrom(d.repeats) }
-                    : {}),
-                /** SEMPRE, inclusive vazio - ver `CheckEvent.unrepresentedMatches`: o vazio é a medição. */
-                unrepresentedMatches: unrepresentedFrom(d.findings, suggestionsFrom(d.repeats)),
-            }).catch(() => { });
-        console.log("");
-        if (opts.fix) {
-            /**
-             * 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.`));
-        }
-        else {
-            console.log(body(`${d.named} of the ${d.findings.length} hand-written values found have a name waiting in`));
-            console.log(body("your system, and that number becomes actionable the moment both are true."));
-        }
-        return;
-    }
     /**
-     * SHADCN IS THE MOST LIKELY THING ALREADY IN THE PROJECT, AND THE BRIDGE WAS
-     * INVISIBLE.
+     * A PONTE DO SHADCN NÃO SE PEDE MAIS - ela era um terceiro `@import` da nossa folha.
      *
-     * Two states, and both are worth a line. Unimported is a real finding: the
-     * components a person spends all day looking at are on shadcn's defaults while
-     * everything around them wears the system, which reads as "this product does
-     * not work here" rather than "one import missing".
+     * O QUE ELA ENTREGAVA: `shadcn.css` mapeia o contrato de variáveis do shadcn nos tokens do sistema,
+     * então os componentes shadcn dele parariam de usar os defaults do shadcn. O valor é real, e é por
+     * isso que o bloco existia - mas ele se cobrava colando `@import "_synthesisui/ds/<slug>/shadcn.css"`
+     * no CSS dele, que é exatamente o que `INV-GERAL-13` proíbe.
      *
-     * Imported is worth saying too, and that is the unusual part. It is the only
-     * place we can answer "how do I know my shadcn is going through the system?"
-     * with something checked rather than claimed. A governance tool that cannot
-     * show its work is asking for trust it has not earned.
+     * A PONTE CONTINUA SENDO COMPILADA e continua caindo em `_synthesisui/ds/<slug>/`, como insumo
+     * nosso - o mesmo estatuto do `tokens.css`. O que sai é a cobrança, não o arquivo. Quando vestir
+     * os componentes shadcn dele passar a ser uma frente própria, ela se resolve como o resto do
+     * produto se resolve: escrevendo no vocabulário DELE, e não pedindo que ele carregue o nosso.
      */
-    if (hasSystem && wiring.hasShadcn) {
-        console.log("");
-        if (wiring.bridged) {
-            console.log(body(`✓ shadcn is reading ${table.name ?? table.slug}, not its own`));
-            console.log(body("  defaults. Colour, charts, radius and the sidebar all resolve"));
-            console.log(body("  to this system's tokens, in both schemes."));
-        }
-        else {
-            console.log(body("This project has shadcn, and it is not wearing the"));
-            console.log(body("system yet - its components are still on shadcn's defaults."));
-            console.log("");
-            console.log(body(`  @import "_synthesisui/ds/${table.slug}/shadcn.css";`));
-            console.log("");
-            console.log(body("  after the tokens.css import, in the same stylesheet. One line,"));
-            console.log(body("  and every shadcn component switches over."));
-        }
-    }
     if (hasSystem && d.reach.measured) {
         const { percent, uses, of } = d.reach;
         console.log("");
@@ -1383,8 +989,16 @@ export async function doctor(opts) {
          */
         if (d.ownTokens > 0 && table.source === "installed") {
             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` : ""}`)));
+            /**
+             * A GRAFIA SAIU DESTA LINHA EM 11/09 - `INV-GERAL-13`.
+             *
+             * Ela dizia *"point those at the `--ds-*` that holds it"*, e aquela variável só resolve com
+             * uma folha nossa carregada no app dele. O fato continua sendo dito - ele tem N tokens que
+             * seguram um valor que o sistema também nomeia -, e o que se faz com isso é decisão dele: os
+             * dois nomes são dele, e o segundo mora num sistema que nasceu do código dele.
+             */
             if (d.ownMirrored > 0)
-                console.log(body(paint.dim(`                point those at the \`--ds-*\` that holds it: ${d.ownMirrored} lines, one file`)));
+                console.log(body(paint.dim(`                ${d.ownMirrored} line${d.ownMirrored === 1 ? "" : "s"} where the two agree - yours to keep as one or as two`)));
         }
         /**
          * O QUE UM COMANDO ALCANÇA, ao lado do que é verdade hoje - e são DUAS contas de propósito.
@@ -1815,8 +1429,16 @@ export async function doctor(opts) {
         for (const f of frozen) {
             say(body(`ds-${f.component} · ${f.where}`));
             say(`          binds ${f.wrote}`);
-            /** A grafia que EXISTE no repo dele - o CSS compilado carrega esta variável; `{color.semantic.*}` é formato nosso e não sai. */
-            say(`          var(--ds-color-semantic-${f.role}) holds that, and becomes ${f.becomes}`);
+            /**
+             * O PAPEL PELO NOME, e não pela nossa grafia de variável (`INV-GERAL-13`, 11/09).
+             *
+             * Esta linha dizia `var(--ds-color-semantic-<role>)`, com a justificativa de que era *"a
+             * grafia que EXISTE no repo dele"*. Ela existe dentro da NOSSA folha, que o app dele não
+             * carrega - então imprimi-la aqui ensina uma variável que ele não pode escrever. O que a
+             * frase precisa dizer é qual papel do sistema segura aquele valor, e `role` já é o nome
+             * daquele papel.
+             */
+            say(`          the "${f.role}" surface colour of this system holds that, and becomes ${f.becomes}`);
             say("");
         }
         say(body("The value resolves and the CSS compiles, so nothing"));
@@ -2163,6 +1785,30 @@ export async function doctor(opts) {
                 console.log(`      ${i + 1}. ${what}  ${paint.dim(`${j.size}${j.cheap ? "  (cheap)" : ""}`)}`);
             });
         }
+        /**
+         * A4 · O VALOR QUE O SISTEMA NOMEIA E O CÓDIGO DELE NÃO - dito, nunca batizado.
+         *
+         * A METADE QUE SUMIRIA SEM ISTO. Desde que `nameToWrite` parou de devolver a nossa grafia
+         * (11/09), um achado com nome só do nosso lado não entra na lista de trocas - e não entrava em
+         * lista nenhuma. Ele saía das duas, e sumir é indistinguível de *"está tudo nomeado"* para quem
+         * lê: o relatório dizia *"1 value by hand · 0 already have a name"* sobre um valor que o
+         * sistema dele nomeia há meses.
+         *
+         * DIZER, E NÃO PROPOR. É a escolha dele de 10/09 entre as duas alternativas, literal: *"DIZER o
+         * valor e onde ele está, sem propor nome nenhum"*. Nenhuma grafia nossa sai daqui - nem como
+         * sugestão, nem entre parênteses - porque um relatório que roda sozinho é o pior lugar para
+         * inventar vocabulário: o agente obedece, e a violação acontece sem ninguém decidir nada.
+         */
+        const onlyOurs = d.findings.filter(ourNameOnly);
+        if (onlyOurs.length > 0) {
+            console.log("");
+            console.log(body(`${onlyOurs.length} value${onlyOurs.length === 1 ? "" : "s"} ${onlyOurs.length === 1 ? "has" : "have"} a name in ${systemName} and none in your own code:`));
+            for (const f of onlyOurs.slice(0, 5))
+                console.log(body(paint.dim(`    ${f.file}:${f.line}  ${f.literal}`)));
+            if (onlyOurs.length > 5)
+                console.log(body(paint.dim(`    (${onlyOurs.length - 5} more)`)));
+            console.log(body(paint.dim("    Naming one is yours to decide - it may be intentional. Once your code names it, `--fix` picks it up.")));
+        }
         console.log("");
         console.log(body("synthesisui doctor --verbose   every finding, file by file"));
         /**