synthesisui 0.16.285 → 0.16.289

package/dist/not-expressed.js

@@ -0,0 +1,76 @@
+/**
+ * O QUE ESTA LEITURA NÃO CONSEGUIU SEGURAR, escrito pela esteira e não pedido a ninguém.
+ *
+ * O QUE O CLIENTE GANHA: ele sabe, no minuto do import, o que não chegou - com o número do
+ * repositório dele e o arquivo e a linha de cada caso. É a lei 8 do método: o cliente perdoa o que
+ * a gente diz que não faz, e não perdoa descobrir sozinho.
+ *
+ * POR QUE ISTO EXISTE. O arquivo era escrito pelo AGENTE, instruído por três frases dentro das
+ * descrições das tools do MCP. Em 23/08 o mesmo repositório foi importado duas vezes: a primeira
+ * rodada escreveu 37 linhas de lacunas declaradas, a segunda escreveu nenhuma. As lacunas
+ * continuaram todas lá - 198 declarações de CSS sem leitor, 5 `var()` que não pintam nada -, e só o
+ * aviso desapareceu. Um pedido em texto a um modelo é uma sugestão, e nada percebia quando ela não
+ * era seguida.
+ *
+ * O PISO É DETERMINÍSTICO, e todo dado que ele usa já estava medido no censo. O agente continua
+ * livre para ACRESCENTAR o que só ele viu; o que ele não pode mais é ser a única testemunha.
+ *
+ * `null` quando não há lacuna nenhuma: um arquivo vazio dizendo "nada a declarar" é ruído, e a
+ * ausência do arquivo já é a resposta.
+ */
+export function notExpressed(census) {
+    const ledger = census.ledger;
+    const unread = ledger?.unread ?? [];
+    const broken = census.brokenRefs ?? [];
+    const skipped = census.skipped ?? [];
+    if (unread.length === 0 && broken.length === 0 && skipped.length === 0)
+        return null;
+    const out = [];
+    const scope = census.scope ? ` of \`${census.scope}\`` : "";
+    out.push(`# What this reading could not hold`);
+    out.push("");
+    out.push(`Measured by synthesisui \`${ledger?.cli ?? "unknown"}\`${scope}. Every number here is from` +
+        ` your files. This file is written by the pipeline on every import - what it lists is what` +
+        ` did NOT reach a recipe.`);
+    if (unread.length > 0) {
+        out.push("");
+        out.push("## Style your files hold and no recipe received");
+        for (const group of unread) {
+            out.push("");
+            out.push(`### ${group.uses} ${group.shape} declaration${group.uses === 1 ? "" : "s"}` +
+                ` across ${group.files} file${group.files === 1 ? "" : "s"} - ${group.reason}`);
+            out.push("");
+            out.push(group.because);
+            out.push("");
+            for (const ex of group.examples ?? [])
+                out.push(`    ${ex.file}:${ex.line}   ${ex.text}`);
+        }
+    }
+    if (broken.length > 0) {
+        out.push("");
+        out.push("## Variables referenced and never declared");
+        out.push("");
+        out.push("These do not paint a different colour - they paint nothing. They are yours to fix, in your" +
+            " own words. Up to three places are listed for each; the count says how many there are in" +
+            " total.");
+        out.push("");
+        for (const ref of broken) {
+            out.push(`    ${ref.name}   ${ref.count} reference${ref.count === 1 ? "" : "s"}` +
+                ` in ${ref.files} file${ref.files === 1 ? "" : "s"}`);
+            for (const place of ref.at ?? [])
+                out.push(`        ${place.file}:${place.line}`);
+        }
+    }
+    if (skipped.length > 0) {
+        out.push("");
+        out.push("## Exports the gate left out, and why");
+        out.push("");
+        out.push("Nothing here was dropped in silence. If one of these IS a component of your system, that is" +
+            " a reading to correct - and the reason below is the one to argue with.");
+        out.push("");
+        for (const s of skipped)
+            out.push(`    ${s.name}${s.file ? `  (${s.file})` : ""}\n        ${s.because}`);
+    }
+    out.push("");
+    return `${out.join("\n")}\n`;
+}

package/dist/token-ref.js

@@ -0,0 +1,93 @@
+/**
+ * O NOME QUE UM TOKEN DELE TEM DENTRO DO DOCUMENTO - uma regra, num lugar só.
+ *
+ * O QUE O CLIENTE GANHA: mudar um valor no Studio repinta o componente que o usa. Um ref liga os
+ * dois; um `var()` literal não liga nada - ele renderiza certo hoje e fica órfão da edição.
+ *
+ * ESTA FUNÇÃO EXISTIA DUAS VEZES, em `transcribe.ts` e em `css-modules.ts`, e as duas divergiam: a
+ * segunda não conhecia `--font-*`, então a família de fonte dele virava referência quando lida de uma
+ * classe e `var()` quando lida de uma folha - a mesma decisão dele com dois destinos, dependendo de
+ * onde a esteira olhou. Gêmeo não declarado sempre acaba assim.
+ *
+ * E O GRADIENTE ERA DECIDIDO PELO NOME. A regra reconhecia `--gradient-*`; o cliente escreveu
+ * `--grad-cool`. O escritor da plataforma reconhece pelo VALOR - `linear-gradient(…)` - e guarda em
+ * `foundations.gradients.grad-cool`, então o token TINHA casa no documento e a classe que o usa
+ * apontava para o vazio. É a lei 13 aplicada a token: a origem decide, e aqui a origem é o valor.
+ *
+ * Medido: `--grad-*` são 5 no `codelevel-ui`, `--gradient-*` são 3 no `frontend-hub`, e as duas
+ * grafias passam a chegar onde o documento as guarda.
+ */
+export function tokenRefFor(name, 
+/**
+ * O que cada token DELE vale. O mapa é o que permite reconhecer um gradiente pela forma em vez do
+ * nome; vazio, a decisão volta a ser só pelo nome, que é o comportamento de quem não tem o valor
+ * em mãos.
+ */
+declared) {
+    const bare = name.replace(/^--/, "");
+    if (bare.startsWith("color-"))
+        return refFor(bare.slice("color-".length));
+    if (bare.startsWith("radius-"))
+        return `{radius.${bare.slice(7)}}`;
+    if (bare.startsWith("spacing-"))
+        return `{spacing.${bare.slice(8)}}`;
+    if (bare.startsWith("shadow-"))
+        return `{shadow.${bare.slice(7)}}`;
+    // `--gradient-ui` e `--background-image-gradient-ui` são um token em duas grafias - o namespace de
+    // utility do Tailwind v4 embrulha o primeiro. Os dois chegam a `{gradients.ui}`.
+    if (bare.startsWith("background-image-gradient-")) {
+        return `{gradients.${bare.slice("background-image-gradient-".length)}}`;
+    }
+    if (bare.startsWith("gradient-"))
+        return `{gradients.${bare.slice(9)}}`;
+    if (bare.startsWith("text-")) {
+        /**
+         * O TOKEN COMPANHEIRO. O Tailwind v4 escreve "a altura de linha DE text-body-s" como
+         * `--text-body-s--line-height` - um duplo hífen dentro de um nome. Lido como nome de passo ele
+         * produzia `{typography.scale.body-s--line-height.fontSize}`, cujo duplo hífen nenhuma gramática
+         * de ref aceita, e a receita inteira era RECUSADA na validação (test13, 01/08). O sufixo nomeia a
+         * propriedade; o meio nomeia o passo.
+         */
+        const companion = /^text-(.+?)--(line-height|letter-spacing|font-weight)$/.exec(bare);
+        if (companion) {
+            const prop = {
+                "line-height": "lineHeight",
+                "letter-spacing": "letterSpacing",
+                "font-weight": "weight",
+            }[companion[2]];
+            return `{typography.scale.${companion[1]}.${prop}}`;
+        }
+        // Qualquer outro duplo hífen é um nome que esta gramática não segura - o `var()` literal ainda
+        // resolve contra a folha dele, e um ref inválido não ajuda ninguém.
+        if (bare.slice(5).includes("--"))
+            return `var(${name})`;
+        return `{typography.scale.${bare.slice(5)}.fontSize}`;
+    }
+    if (bare.startsWith("font-"))
+        return `{typography.families.${bare.slice(5)}}`;
+    /**
+     * O GRADIENTE PELA FORMA DO VALOR, e é a última pergunta e não a primeira.
+     *
+     * Os namespaces acima são vocabulário conhecido e ganham deste teste - `--color-brand` que valha um
+     * `linear-gradient` continua sendo cor pelo nome que ele deu. Aqui embaixo estão os nomes que a
+     * gente NÃO modela, e é onde `--grad-cool` cai. A chave é o nome dele inteiro, que é exatamente o
+     * que `gradientsFromCensus` guarda no documento.
+     */
+    const value = declared.get(name);
+    if (value && /\b(?:linear|radial|conic)-gradient\(/.test(value)) {
+        return `{gradients.${bare}}`;
+    }
+    // Um namespace que não modelamos. O `var()` literal continua sendo CSS correto contra a folha
+    // dele, e inventar um ref apontaria para nada.
+    return `var(${name})`;
+}
+/**
+ * `ocean-500` → `{color.ocean.500}`. O passo é o número final; o que vem antes é a família, hífens
+ * intactos, porque `royal-blue-500` é uma família chamada `royal-blue`.
+ */
+function refFor(name) {
+    const m = /^(.*)-(\d{2,4})$/.exec(name);
+    if (!m)
+        return `{color.${name}}`;
+    return `{color.${m[1]}.${m[2]}}`;
+}

package/package.json

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