synthesisui 0.16.282 → 0.16.284

package/dist/commands/add.js

@@ -10,6 +10,7 @@ import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
 import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
 import { detectStack } from "../stack.js";
+import { pointTokensAtTheirNames } from "../their-vars.js";
 /**
  * QUAL METADE DESTA PASTA UM TIME COMMITA.
  *
@@ -193,9 +194,18 @@ export async function add(slug, opts) {
     // know what was active before, to report install vs update vs switch
     const prev = await readRootLock(rootLockPath);
     await mkdir(versionDir, { recursive: true });
+    /**
+     * O VOCABULÁRIO DELE, LIDO NESTA MÁQUINA - ver `their-vars.ts`, e é por isso que isto acontece
+     * aqui e não no compilador: a pergunta *"esta variável existe NESTE repositório?"* só tem resposta
+     * onde o repositório está.
+     *
+     * Falha calada de propósito: um repositório sem folha de estilo, ou sem build, devolve o que veio
+     * do servidor. A folha nunca fica pior do que estava.
+     */
+    const theirVars = await pointTokensAtTheirNames(projectRoot, payload);
     // 1. server artifacts (tokens.css, theme.css, …) → pinned version folder
     for (const [filename, content] of Object.entries(payload.artifacts)) {
-        await writeFile(join(versionDir, filename), content, "utf8");
+        await writeFile(join(versionDir, filename), filename === "tokens.css" ? theirVars.css : content, "utf8");
     }
     // 2. canonical source of truth
     await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document, null, 2)}\n`, "utf8");
@@ -250,6 +260,14 @@ export async function add(slug, opts) {
         /** Ver `RegistryPayload.compiler`: é o que faz um conserto de CSS chegar a um install. */
         ...(payload.compiler != null ? { compiler: payload.compiler } : {}),
         ...(payload.rulesStamp ? { rules: payload.rulesStamp } : {}),
+        /**
+         * QUANTAS LINHAS DESTA FOLHA APONTAM PARA UMA VARIÁVEL DELE - ver `their-vars.ts`.
+         *
+         * Sem isto, o `tokens.css` de dois repositórios do mesmo sistema seria diferente e nada diria por
+         * quê. O número é o rastro: o `doctor` sabe que aquelas linhas dependem do vocabulário DESTE
+         * repositório, e é ele que avisa quando uma delas deixa de resolver.
+         */
+        ...(theirVars.pointed > 0 ? { theirVars: theirVars.pointed } : {}),
         ...(scope ? { scope } : {}),
         ...(systems.length > 0 ? { scopes: systems } : {}),
         ...(usage.length > 0 ? { usage } : {}),
@@ -371,6 +389,13 @@ export async function add(slug, opts) {
         "GUIDE.md",
     ];
     console.log(`  v${v}/: ${files.join(", ")}`);
+    /**
+     * A FOLHA NÃO É A QUE O SERVIDOR COMPILOU, e calar isso é o pior dos dois mundos: o cliente vê um
+     * `var(--color-ink-500)` num arquivo "gerenciado pelo synthesisui" e não tem como saber de onde
+     * veio. Dito assim, ele lê a linha como o que ela é - o sistema seguindo o vocabulário dele.
+     */
+    if (theirVars.pointed > 0)
+        console.log(`  ${theirVars.pointed} value${theirVars.pointed === 1 ? "" : "s"} in tokens.css now point at the name YOUR code already gives ${theirVars.pointed === 1 ? "it" : "them"} - change yours and the system follows${theirVars.pruned > 0 ? `; ${theirVars.pruned} matched but your build does not emit ${theirVars.pruned === 1 ? "that name" : "those names"}, so ${theirVars.pruned === 1 ? "it keeps" : "they keep"} the value` : ""}`);
     /**
      * O QUE O AGENTE VAI LER, e por qual porta - nomear o arquivo quando a porta é uma ferramenta
      * mandaria alguém procurar um caminho que não existe mais.

package/dist/commands/doctor.js

@@ -20,6 +20,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 { resolveDeps } from "../stack.js";
+import { danglingTheirVars } from "../their-vars.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -891,6 +892,25 @@ export async function doctor(opts) {
         }
         console.log(body("The exact snippets are in the output of `init`."));
     }
+    /**
+     * A FOLHA APONTA PARA O VOCABULÁRIO DELE, E UM NOME SUMIU - ver `their-vars.ts`.
+     *
+     * O `add` reescreve `--ds-color-ink-500: #6b6b78` como `var(--color-ink-500)` quando o repositório
+     * já nomeia aquele valor, para não existirem duas fontes da verdade. Não há fallback, por decisão:
+     * uma cópia do valor sobreviveria a um rename DELE pintando o valor velho, que é a plataforma
+     * decidindo por cima da decisão dele.
+     *
+     * O preço é que um rename apaga a cor, e este é o único lugar que conhece as duas pontas. Sem esta
+     * linha ele veria um componente sem cor e nada explicaria de onde veio.
+     */
+    const dangling = danglingTheirVars(await readFile(join(root, "_synthesisui", "ds", table.slug ?? "", "tokens.css"), "utf8").catch(() => ""), installed.theirs);
+    if (dangling.length > 0) {
+        console.log("");
+        console.log(body(`${dangling.length} line${dangling.length === 1 ? "" : "s"} of this system point at ${dangling.length === 1 ? "a variable" : "variables"} your code no longer declares, so ${dangling.length === 1 ? "that value" : "those values"} paint nothing:`));
+        for (const { ours, theirs: name } of dangling.slice(0, 6))
+            console.log(body(`  ${ours} → ${name}`));
+        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.
      *

package/dist/guide.js

@@ -262,6 +262,23 @@ export function buildGuide(payload) {
     const { document: doc, slug, name, version } = payload;
     const { meta, foundations, motion, components } = doc;
     const semanticRoles = Object.keys(foundations.color.semantic);
+    /**
+     * O NOME QUE ELE DÁ AO PAPEL, quando o documento sabe qual é - `semanticNames`.
+     *
+     * O guia listava `info, faint, muted, scrim, accent, border, canvas, danger, raised, overlay,
+     * primary, success, surface, warning` e chamava isso de vocabulário do sistema DELE. Nenhuma dessas
+     * palavras está no código dele: `canvas` é `paper`, `primary` é `brand-blue`, `danger` é
+     * `feedback-error`. Este arquivo é o que o agente dele LÊ antes de escrever, então a nossa língua
+     * aqui vira o código dele.
+     *
+     * A missão de 16/08 tirou o nosso identificador das telas e da saída de texto do CLI; o guia é
+     * artefato e escapou da varredura. Medido em 22/08 no `codelevel-ui`: 14 papéis listados, 12 com
+     * nome dele guardado no documento e nenhum aparecendo.
+     *
+     * Sem `semanticNames` o papel sai como está - é o caso de um sistema que NASCEU aqui, e aí o nome
+     * é nosso mesmo.
+     */
+    const theirRole = (role) => foundations.color.semanticNames?.[role] ?? role;
     /**
      * AS CORES QUE ELE NOMEIA POR PROPÓSITO, no arquivo que o agente lê primeiro.
      *
@@ -679,7 +696,10 @@ ${hasTailwind
   The token names below are the source vocabulary - every utility derives from them.`
         : ""}
 - **Always use semantic tokens**, never raw values nor primitives directly.
-  Color: \`var(--ds-color-semantic-<role>)\`${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}. The roles are: ${list(semanticRoles)}.
+  Color: \`var(--ds-color-semantic-<role>)\`${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}. The roles are: ${list(semanticRoles.map((r) => {
+        const theirs = theirRole(r);
+        return theirs === r ? r : `${r} (${theirs} in your code)`;
+    }))}.
 - Primitives (\`--ds-color-<palette>-<step>\`) exist but should **not** be referenced directly -
   they feed the semantic roles.${namedColours.length > 0
         ? `\n- **Yours by name** → \`var(--ds-color-<name>)\`: ${namedColours.length} colour${namedColours.length === 1 ? "" : "s"} your code names by PURPOSE rather than by step, so no scale could hold ${namedColours.length === 1 ? "it" : "them"} - ${list(namedColours.slice(0, 8))}${namedColours.length > 8 ? ", …" : ""}. These are yours: reach for them when the purpose matches, and prefer a semantic role when it does not.`

package/dist/install-marks.js

@@ -128,7 +128,7 @@
  * é sempre o bump deste PR - nunca o número que o `package.json` já carrega, porque alguém pode
  * publicar no meio.
  */
-export const MATERIALISER_SINCE = "0.16.281";
+export const MATERIALISER_SINCE = "0.16.284";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/their-vars.js

@@ -0,0 +1,200 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { theirNames } from "./doctor/their-names.js";
+import { buildTable, normalizeValue, } from "./doctor/tokens.js";
+/**
+ * A FOLHA APONTA PARA O NOME QUE O CÓDIGO DELE JÁ DÁ AO VALOR.
+ *
+ * O QUE O CLIENTE VÊ. O `tokens.css` que a gente instala declara `--ds-color-ink-500: #6b6b78` num
+ * repositório que declara `--color-ink-500: #6b6b78` desde antes da gente existir. Mesmo valor,
+ * mesma palavra, prefixo nosso - e duas fontes da verdade. Ele muda a dele e a nossa fica congelada
+ * no valor que a gente copiou. Medido em 22/08 no `codelevel-monorepo`: 78 de 161 declarações.
+ *
+ * Depois disto a nossa linha vira `--ds-color-ink-500: var(--color-ink-500)`, e a cor do sistema
+ * segue a decisão dele sem a gente reescrever nada no arquivo dele.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * POR QUE ISTO MORA NO CLI E NÃO NO COMPILADOR, que é onde eu ia colocar.
+ *
+ * O mesmo `compileDesignSystemCss` serve DOIS consumidores: o `tokens.css` que vai para a pasta dele
+ * e o Canvas do Studio, onde a folha de estilo dele não existe. Apontar para `var(--color-ink-500)`
+ * lá dentro apagaria a cor do nosso próprio preview - e apagaria também em todo projeto de DESTINO,
+ * que é o caso que `orphan-var.ts` já descreve: *"no projeto de origem isso nunca aparece, porque o
+ * globals.css dele ainda está lá"*.
+ *
+ * A informação que decide - *"esta variável existe NESTE repositório?"* - só existe na máquina dele.
+ * Rodando aqui, o projeto de destino se resolve sozinho: nada casa, nada é reescrito.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O QUE PROTEGE, e cada guarda saiu de uma medição.
+ *
+ *     o BUILD é a autoridade     o Tailwind PODA `@theme` que nenhuma utility usa. Medido nos 19
+ *                                arquivos CSS que o build dele produziu: 7 das 78 declarações somem.
+ *                                Apontar para uma podada não deixa a cor errada - apaga a cor.
+ *                                (as 29 cores dele sobreviveram; a poda pegou só `--animate-*`)
+ *     sem build, sem reescrita   um repositório que nunca buildou não tem como provar o que resolve,
+ *                                e chutar aqui é o oposto do objetivo. A folha fica como veio e o
+ *                                comando DIZ que ficou.
+ *     a categoria fecha          `theirNames` recusa comprimento cru: `24px` pode ser raio ou
+ *                                espaçamento no vocabulário dele, e escolher errado escreve um token
+ *                                de tipo num `border-radius`.
+ *     nada de fallback           `var(--x, #6b6b78)` sobreviveria a um rename DELE pintando o valor
+ *                                velho - a plataforma decidindo por cima da decisão dele. Se ele
+ *                                renomear, quebra, e o `doctor` diz qual (dono, 22/08: *"a gente não
+ *                                pode ser invasivo... mas tem que ser capaz de identificar"*).
+ */
+/** Onde um build costuma deixar o CSS que o navegador realmente recebe. */
+const BUILD_DIRS = [".next", "dist", "build", "out", "storybook-static"];
+async function* cssUnder(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* cssUnder(path);
+        else if (entry.name.endsWith(".css"))
+            yield path;
+    }
+}
+/**
+ * AS VARIÁVEIS QUE O BUILD DELE REALMENTE EMITE - a autoridade sobre o que resolve no navegador.
+ *
+ * `null` quando não há build nenhum, e null significa *não sei*, não *nenhuma*. Quem chama trata os
+ * dois de forma oposta.
+ */
+export async function resolvableVars(root) {
+    const out = new Set();
+    let found = false;
+    for (const dir of BUILD_DIRS) {
+        for await (const file of cssUnder(join(root, dir))) {
+            found = true;
+            const css = await readFile(file, "utf8").catch(() => "");
+            for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g))
+                out.add(m[1]);
+        }
+        /** Monorepo: o build mora dentro de cada app, não na raiz. */
+        for (const group of ["apps", "packages"]) {
+            for (const entry of await readdir(join(root, group), {
+                withFileTypes: true,
+            }).catch(() => [])) {
+                if (!entry.isDirectory())
+                    continue;
+                for await (const file of cssUnder(join(root, group, entry.name, dir))) {
+                    found = true;
+                    const css = await readFile(file, "utf8").catch(() => "");
+                    for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g))
+                        out.add(m[1]);
+                }
+            }
+        }
+    }
+    return found ? out : null;
+}
+/**
+ * REESCREVE A FOLHA, e só as linhas que passam nos dois portões.
+ *
+ * `theirs` é a tabela do repositório dele (`harvestOwnTokens`); `resolvable` é o que o build emite,
+ * ou `null` quando não há build - e aí nada é reescrito.
+ */
+export function pointAtTheirNames(css, theirs, resolvable) {
+    if (!resolvable || theirs.byName.size === 0)
+        return { css, pointed: 0, pruned: 0 };
+    const ours = buildTable({ css, source: "installed" });
+    const alias = theirNames(ours, theirs);
+    let pointed = 0;
+    let pruned = 0;
+    const out = css.replace(/^(\s*)(--ds-[a-zA-Z0-9_-]+)(\s*:\s*)([^;]+);/gm, (line, indent, name, sep, value) => {
+        /** Uma linha que já aponta para outra variável não é uma cópia de valor. */
+        if (value.includes("var("))
+            return line;
+        const kind = Object.entries(FAMILY_KIND).find(([prefix]) => name.startsWith(prefix))?.[1];
+        if (!kind)
+            return line;
+        const theirName = alias.get(`${kind}:${normalizeValue(value.trim(), ours.rootPx)}`);
+        if (!theirName || theirName === name)
+            return line;
+        if (!resolvable.has(theirName)) {
+            pruned += 1;
+            return line;
+        }
+        pointed += 1;
+        return `${indent}${name}${sep}var(${theirName});`;
+    });
+    return { css: out, pointed, pruned };
+}
+/**
+ * O PREFIXO DA NOSSA VARIÁVEL -> A FAMÍLIA, e a chave que `theirNames` devolve é `<família>:<valor>`.
+ *
+ * Comprimento cru fica de fora por decisão de `their-names.ts`, e a razão é a mesma aqui: `24px` pode
+ * ser raio ou espaçamento no vocabulário dele.
+ */
+const FAMILY_KIND = {
+    "--ds-color-": "color",
+    "--ds-shadow-": "shadow",
+    "--ds-typography-families-": "font",
+    "--ds-motion-durations-": "motion",
+    "--ds-motion-easings-": "motion",
+};
+/**
+ * A JORNADA INTEIRA, num chamador só - varrer, medir o build, reescrever.
+ *
+ * Recebe o payload em vez do CSS solto porque um argumento opcional a menos é uma chamada pela
+ * metade a menos: quem chama não tem como esquecer de passar a folha certa.
+ */
+export async function pointTokensAtTheirNames(root, payload) {
+    const css = payload.artifacts["tokens.css"] ?? "";
+    if (!css)
+        return { css, pointed: 0, pruned: 0 };
+    const [theirs, resolvable] = await Promise.all([
+        harvestTheirCss(root),
+        resolvableVars(root),
+    ]);
+    return pointAtTheirNames(css, theirs, resolvable);
+}
+/** As folhas de estilo DELE, e nenhuma da nossa pasta. Gêmeo de `harvestOwnTokens` no doctor. */
+async function harvestTheirCss(root) {
+    const skip = new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        ".next",
+        "build",
+        "out",
+        "_synthesisui",
+    ]);
+    let css = "";
+    const walk = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+            if (skip.has(entry.name) || entry.name.startsWith("."))
+                continue;
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (/\.(css|scss|sass|less)$/i.test(entry.name))
+                css += `\n${await readFile(path, "utf8").catch(() => "")}`;
+        }
+    };
+    await walk(root);
+    return buildTable({ css, source: "yours" });
+}
+/**
+ * AS LINHAS QUE APONTAM PARA UM NOME DELE QUE NÃO EXISTE MAIS.
+ *
+ * O dono decidiu a política em 22/08, e ela é o oposto de defensiva: *"só fazer o design dele quebrar
+ * e ele mesmo acaba consertando. A gente não pode ser invasivo... mas tem que ser capaz de, se o
+ * usuário precisar, corrigir, ou pelo menos identificar o problema."*
+ *
+ * Então não existe fallback. Se ele renomeia `--color-ink-500`, a cor some - e este é o único lugar
+ * que sabe dizer POR QUÊ, porque só ele conhece as duas pontas: a folha que a gente instalou e o
+ * vocabulário que o repositório declara hoje.
+ */
+export function danglingTheirVars(installedCss, theirs) {
+    const out = [];
+    for (const m of installedCss.matchAll(/(--ds-[a-zA-Z0-9_-]+)\s*:\s*var\(\s*(--[a-zA-Z0-9_-]+)\s*\)\s*;/g)) {
+        const target = m[2];
+        /** Uma referência à nossa própria folha resolve nela mesma - não é dependência do repo dele. */
+        if (target.startsWith("--ds-"))
+            continue;
+        if (!theirs.byName.has(target))
+            out.push({ ours: m[1], theirs: target });
+    }
+    return out;
+}

package/package.json

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