synthesisui 0.16.396 → 0.16.397

package/dist/commands/component.js

@@ -8,6 +8,7 @@ import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-tem
 import { body, section, snippet } from "../output.js";
 import { findCollision, installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
+import { installedThemeCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { inTheirTongue, projectTongue, sumSpoken, } from "../their-tongue.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
@@ -110,6 +111,13 @@ export async function component(slug, name, opts) {
      * sai no fim - depois da linha que nomeia o que foi escrito.
      */
     let spoken = null;
+    /**
+     * OS BYTES QUE FORAM A DISCO - é sobre ELES que a pergunta "precisa da folha?" se responde.
+     *
+     * Pela mesma razão que `spoken` é preenchido em cada caminho de escrita: perguntar sobre o
+     * recipe, ou sobre o css antes da tradução, seria responder sobre um arquivo que ninguém abriu.
+     */
+    let writtenSource = "";
     const artifactsAreTheProduct = opts.artifactsOnly === true || config.target !== "next";
     if (artifactsAreTheProduct) {
         const dir = join(root, "_synthesisui", "ds", slug, "components");
@@ -119,6 +127,7 @@ export async function component(slug, name, opts) {
         const sheet = tongue ? inTheirTongue(res.css, tongue) : null;
         if (sheet)
             spoken = sheet;
+        writtenSource = sheet ? sheet.css : res.css;
         await writeFile(join(dir, `${res.name}.css`), `${sheet ? sheet.css : res.css}\n`, "utf8");
         console.log(`✓ ${res.name} → _synthesisui/ds/${slug}/components/${res.name}.{json,css}  (${slug} v${res.version})`);
     }
@@ -287,6 +296,7 @@ export async function component(slug, name, opts) {
             ];
             for (const f of written)
                 await writeFile(join(compDir, f.filename), f.content, "utf8");
+            writtenSource = written.map((f) => f.content).join("\n");
             /** O fingerprint do que escrevemos - é o que protege a edição dele no upgrade (T7). */
             await recordWritten(join(root, "_synthesisui", "ds", slug), local, written);
             filenames = written.map((f) => f.filename);
@@ -335,6 +345,7 @@ export async function component(slug, name, opts) {
             }));
             for (const f of written)
                 await writeFile(join(compDir, f.filename), f.content, "utf8");
+            writtenSource = written.map((f) => f.content).join("\n");
             await recordWritten(join(root, "_synthesisui", "ds", slug), local, written);
             if (flavour === "tailwind")
                 await writeCn(root, compDir, slug);
@@ -368,34 +379,63 @@ export async function component(slug, name, opts) {
             `@import "../_synthesisui/ds/${slug}/theme.css";`,
         ]
         : [`@import "../_synthesisui/ds/${slug}/tokens.css";`];
-    console.log(section(`One-time setup (once per app, for "${slug}")`));
     /**
-     * POR QUE O SETUP CONTINUA AQUI QUANDO NENHUMA VARIÁVEL É NOSSA - e dizer isto é o conserto.
+     * O SETUP SÓ É COBRADO QUANDO ESTE ARQUIVO PRECISA DELE - ver `sheet-needed.ts`.
+     *
+     * O DEFEITO, apontado pelo dono olhando a própria tela (07/09): o comando terminava dizendo
+     * *"No variable in what was just written points at our stylesheet"* e, três linhas abaixo,
+     * imprimia **One-time setup** mandando colar dois `@import`. As duas frases não podem ser
+     * verdadeiras ao mesmo tempo, e a segunda pedia uma dependência de runtime para um arquivo que
+     * não a usa.
      *
-     * A tentação era suprimir o bloco quando `left` é vazio, e ele leria como a promessa "seu
-     * repositório dispensa a folha". Medido no codelevel (07/09): as duas coisas são independentes.
-     * As VARIÁVEIS podem ser todas dele e o arquivo continua vestindo utilitários que só o adaptador
-     * do sistema gera (`rounded-3`, `gap-2xs`) e movimento que o `theme.css` declara referenciando
-     * `--ds-*`. Suprimir entregaria um componente sem raio e sem gap.
+     * A VERSÃO ANTERIOR DESTE BLOCO já tinha visto metade do problema e parou na metade: manteve o
+     * setup e acrescentou *"o que estes imports ainda trazem são os utilitários do sistema e o
+     * movimento"*. A razão é real - `INV-VOLTA-13` deixa no `@theme` os nomes que só o sistema tem -
+     * mas ela era AFIRMADA, nunca medida. No `codelevel` aquele `@theme` declara 50 variáveis, todas
+     * `--animate-*` e `--max-width-*`, e o componente gerado não veste nenhuma delas: as duas
+     * animações que ele usa são declaradas pelo `globals.css` DELE.
      *
-     * Então o bloco não muda de tamanho: ele muda de MOTIVO. A linha abaixo diz qual das duas coisas
-     * a importação ainda serve, e ela é derivada, nunca fixa.
+     * Então a pergunta passa a ser feita: sobrou variável nossa, ou classe que só o nosso `@theme`
+     * gera? Se nenhuma das duas, o arquivo está isolado e o bloco diz isso - com o que o import ainda
+     * daria, para a escolha continuar sendo dele.
      */
-    if (spoken && spoken.left.length === 0) {
-        console.log(body(`(the variables are already yours - what these imports still bring is the`));
-        console.log(body(` system's own utilities and its motion, which the app has to generate)`));
+    const need = whatOnlyTheSheetResolves({
+        source: writtenSource,
+        themeCss: await installedThemeCss(root, slug),
+        /** O vocabulário DELE sai da conta - ver `theirNames`. O mapa do `.lock` é a via mais barata. */
+        theirNames: tongue?.names ? [...tongue.names.values()] : [],
+    });
+    if (!need.needed) {
+        console.log(section("This file needs nothing else"));
+        console.log(body("Every variable and class in it is declared by your own code - no import, no scope"));
+        console.log(body("attribute, nothing at runtime. It is yours."));
         console.log("");
+        console.log(body(`The system stays what it is here: the reference your agent reads to build ON it.`));
+        console.log(body(`If you later want the utilities only its own @theme generates, that is when`));
+        console.log(body(`importing earns its place - and \`doctor\` says so.`));
+    }
+    /**
+     * E O "USE IT" SAI NOS DOIS CAMINHOS - a primeira versão disto era um `return`, e ela levava
+     * junto a única linha que diz COMO importar o componente. Dizer "está isolado" e sonegar o
+     * `import { ButtonSample }` troca um defeito por outro.
+     */
+    if (need.needed) {
+        console.log(section(`One-time setup (once per app, for "${slug}")`));
+        console.log(body(need.variables.length > 0
+            ? `(what still needs the sheet here: ${need.variables.slice(0, 3).join(", ")}${need.variables.length > 3 ? `, +${need.variables.length - 3}` : ""} - your code names no value for ${need.variables.length === 1 ? "it" : "them"})`
+            : `(what still needs the sheet here: the ${need.classes.slice(0, 3).join(", ")}${need.classes.length > 3 ? `, +${need.classes.length - 3}` : ""} ${need.classes.length === 1 ? "utility" : "utilities"}, which only this system's @theme generates)`));
+        console.log("");
+        console.log(body(`1. Import the design system in your GLOBAL stylesheet, e.g. app/globals.css`));
+        console.log(body(`   (the path is relative to that file - hence the leading ../):`));
+        console.log("");
+        console.log(snippet(imports));
+        console.log("");
+        console.log(body(`2. Scope your app: add data-ds="${slug}" to a ROOT element, e.g. app/layout.tsx:`));
+        console.log("");
+        console.log(snippet([`<body data-ds="${slug}">{children}</body>`]));
+        console.log("");
+        console.log(body(`(If you haven't installed the system yet, run: synthesisui add ${slug})`));
     }
-    console.log(body(`1. Import the design system in your GLOBAL stylesheet, e.g. app/globals.css`));
-    console.log(body(`   (the path is relative to that file - hence the leading ../):`));
-    console.log("");
-    console.log(snippet(imports));
-    console.log("");
-    console.log(body(`2. Scope your app: add data-ds="${slug}" to a ROOT element, e.g. app/layout.tsx:`));
-    console.log("");
-    console.log(snippet([`<body data-ds="${slug}">{children}</body>`]));
-    console.log("");
-    console.log(body(`(If you haven't installed the system yet, run: synthesisui add ${slug})`));
     console.log(section("Use it"));
     if (!opts.artifactsOnly && config.target === "next") {
         /**

package/dist/commands/doctor.js

@@ -22,6 +22,7 @@ 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 { danglingTheirVars } from "../their-vars.js";
 /**
@@ -782,6 +783,14 @@ 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);
@@ -793,6 +802,9 @@ 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
@@ -967,7 +979,22 @@ export async function doctor(opts) {
      * `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 blocked = table.source === "installed" && (!wiring.imported || !wiring.scoped);
+    const sheetNeed = whatOnlyTheSheetResolves({
+        source: scannedSource,
+        themeCss,
+        theirNames: installed.theirs.byName.keys(),
+    });
+    /**
+     * BLOQUEADO SÓ QUANDO A FOLHA É NECESSÁRIA - a mesma pergunta que decide `unwired`.
+     *
+     * 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.
@@ -983,12 +1010,55 @@ export async function doctor(opts) {
      */
     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.
+         */
+        const asks = sheetNeed.variables.length > 0
+            ? `${sheetNeed.variables.slice(0, 3).join(", ")}${sheetNeed.variables.length > 3 ? `, +${sheetNeed.variables.length - 3} more` : ""} - re-run \`component\` on whatever writes ${sheetNeed.variables.length === 1 ? "it" : "them"} and it speaks your own names instead`
+            : `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`));

package/dist/sheet-needed.js

@@ -0,0 +1,76 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { TAILWIND_THEME_VARS } from "./tailwind-theme-vars.js";
+/** `--animate-shimmer` no `@theme` -> o nome `shimmer`, que é o que uma classe carrega. */
+function themeNames(themeCss) {
+    const out = new Set();
+    for (const block of themeCss.matchAll(/@theme[^{]*\{([\s\S]*?)\n\}/g))
+        for (const m of block[1].matchAll(/^\s*--([a-z]+)-([a-zA-Z0-9_-]+)\s*:/gm))
+            out.add(m[2]);
+    return [...out];
+}
+/** As classes escritas no código - `hover:animate-shimmer` conta como `animate-shimmer`. */
+function classesIn(source) {
+    const out = new Set();
+    for (const m of source.matchAll(/class(?:Name)?=(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\}|\{"([^"]*)"\})/g)) {
+        const body = m[1] ?? m[2] ?? m[3] ?? m[4] ?? "";
+        for (const raw of body.split(/\s+/)) {
+            if (!raw)
+                continue;
+            const bare = raw.split(":").pop() ?? raw;
+            out.add(bare.replace(/^[!-]/, ""));
+        }
+    }
+    return out;
+}
+/**
+ * O QUE, NESTE TEXTO, SÓ A FOLHA RESOLVE.
+ *
+ * Puro de propósito: quem varre o disco é quem chama, e um spec precisa poder afirmar a regra sem
+ * um diretório temporário.
+ */
+export function whatOnlyTheSheetResolves(input) {
+    const variables = [
+        ...new Set([...input.source.matchAll(/var\(\s*(--ds-[a-zA-Z0-9_-]+)/g)].map((m) => m[1])),
+    ];
+    /**
+     * `--animate-shimmer` declarado por ele -> o nome `shimmer` sai da conta.
+     *
+     * E O QUE O PRÓPRIO TAILWIND DECLARA sai junto, pela mesma razão e pela lista que já existe:
+     * `animate-pulse` existe em qualquer projeto que importe o Tailwind, e acusá-la de exigir a nossa
+     * folha é o mesmo aviso falso que `TAILWIND_THEME_VARS` foi escrito para acabar. Medido no
+     * `codelevel` (07/09): sem esta linha, `animate-pulse` era a ÚNICA coisa sustentando a cobrança
+     * do import naquele repositório.
+     */
+    const theirs = new Set();
+    for (const name of [...TAILWIND_THEME_VARS, ...(input.theirNames ?? [])]) {
+        const m = /^--[a-z]+-(.+)$/.exec(name.toLowerCase());
+        if (m)
+            theirs.add(m[1]);
+    }
+    const names = themeNames(input.themeCss).filter((n) => !theirs.has(n));
+    const written = classesIn(input.source);
+    const classes = [
+        ...new Set([...written].filter((c) => names.some((n) => c === n || c.endsWith(`-${n}`)))),
+    ];
+    return {
+        variables,
+        classes,
+        needed: variables.length > 0 || classes.length > 0,
+    };
+}
+/** O `theme.css` da versão instalada - a folha da raiz é um re-export de uma linha. */
+export async function installedThemeCss(root, slug) {
+    const dir = join(root, "_synthesisui", "ds", slug);
+    const lock = await readFile(join(dir, ".lock"), "utf8").catch(() => null);
+    let version = 0;
+    if (lock) {
+        try {
+            version = JSON.parse(lock).version ?? 0;
+        }
+        catch {
+            version = 0;
+        }
+    }
+    return readFile(join(dir, `v${version}`, "theme.css"), "utf8").catch(() => "");
+}

package/package.json

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