synthesisui 0.16.309 → 0.16.311

package/dist/commands/component.js

@@ -9,7 +9,7 @@ import { body, section, snippet } from "../output.js";
 import { findCollision, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
-import { inTheirTongue, tongueOf } from "../their-tongue.js";
+import { inTheirTongue, projectTongue } from "../their-tongue.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -98,7 +98,7 @@ export async function component(slug, name, opts) {
      * apagaria a cor. Um projeto de destino chega sem mapa no `.lock`, nada é traduzido, e a folha
      * continua sendo o caminho - o comando DIZ qual dos dois aconteceu.
      */
-    const tongue = await tongueFor(root, slug);
+    const tongue = await projectTongue(root, slug);
     const spoken = tongue ? inTheirTongue(res.css, tongue) : null;
     const css = spoken ? spoken.css : res.css;
     /**
@@ -325,35 +325,3 @@ export async function component(slug, name, opts) {
     }
     console.log("");
 }
-/**
- * O VOCABULÁRIO DESTE REPOSITÓRIO, do que o `add` já deixou na pasta - ver `tongueOf`.
- *
- * `null` quando não há mapa: é a resposta de um projeto de destino, de um repositório que nunca
- * buildou, ou de um install feito por um CLI anterior a 0.16.290. Nos três casos nada é traduzido e
- * a folha instalada continua sendo o caminho, que é o comportamento de sempre.
- */
-async function tongueFor(root, slug) {
-    const dir = join(root, "_synthesisui", "ds", slug);
-    const lock = await readFile(join(dir, ".lock"), "utf8").catch(() => null);
-    if (!lock)
-        return null;
-    let map = [];
-    let version = 0;
-    try {
-        const parsed = JSON.parse(lock);
-        map = parsed.tokenMap ?? [];
-        version = parsed.version ?? 0;
-    }
-    catch {
-        return null;
-    }
-    if (map.length === 0)
-        return null;
-    /**
-     * O VALOR COMPILADO MORA NA PASTA DA VERSÃO - a folha da raiz é um re-export de uma linha, escrito
-     * assim de propósito para que o `@import` dele nunca mude entre updates (ver `add.ts`). É de lá
-     * que sai o literal para as variáveis que não têm nome dele.
-     */
-    const installed = await readFile(join(dir, `v${version}`, "tokens.css"), "utf8").catch(() => "");
-    return tongueOf(map, installed);
-}

package/dist/commands/gaps.js

@@ -26,8 +26,12 @@ export async function gaps(opts) {
         return;
     }
     let ledger;
+    /** A régua única - ver `describeValueRuler`. Ausente num censo medido antes de 0.16.308. */
+    let values;
     try {
-        ledger = JSON.parse(raw).ledger;
+        const census = JSON.parse(raw);
+        ledger = census.ledger;
+        values = census.values?.classes ?? undefined;
     }
     catch {
         console.log(body(`${path} is not readable JSON.`));
@@ -42,7 +46,7 @@ export async function gaps(opts) {
         console.log(body(`This measurement was written by a tool version that did not count style fragments yet, so the numbers do not exist rather than being zero. Run \`synthesisui import --dry\` again with ${opts.cli} to measure.`));
         return;
     }
-    for (const line of describeTriage(triageLedger(ledger, opts.cli)))
+    for (const line of describeTriage(triageLedger(ledger, opts.cli), values))
         console.log(body(line));
     /**
      * E O QUE A CAMADA GLOBAL JÁ LEVOU - o desconto, sem o qual este comando repete a mentira que ele

package/dist/commands/import.js

@@ -1849,7 +1849,29 @@ export async function takeCensus(root, opts) {
      * AS LEIS DAS PÁGINAS, ditas onde a arquitetura já é dita - governam o sistema, não uma peça,
      * então `applies` é vazio e elas chegam a todo prompt. Ver `pageLaws`.
      */
-    const ledgerLines = describeLedger(ledger);
+    /**
+     * A CONTABILIDADE POR VALOR, contada AQUI porque o material é daqui: os tokens de classe que
+     * vestem cada componente admitido (os nós do sketch e as camadas condicionais cruas), contra
+     * os tokens que o CSS dele declara. Ver `Census.values` e `doctor/value-ledger.ts` - é a
+     * reconciliação do item 11, e a soma fecha com `seen` por construção.
+     *
+     * ANTES do relatório do ledger de propósito: "quanto vocês entenderam?" tem UMA resposta (dono,
+     * 26/08), e é esta régua - a mesma que a tela usa. A frase do ledger passa a liderar com ela.
+     */
+    const valueByComponent = {};
+    for (const [lookName, look] of Object.entries(looks)) {
+        const tokens = [];
+        for (const node of look.sketch ?? []) {
+            tokens.push(...(node.classes ?? "").split(/\s+/).filter(Boolean));
+        }
+        for (const layer of look.rawLayers ?? [])
+            tokens.push(...layer.classes);
+        if (tokens.length > 0) {
+            valueByComponent[lookName] = accountClasses(tokens, declaredValues);
+        }
+    }
+    const valuesTotal = sumAccounts(Object.values(valueByComponent));
+    const ledgerLines = describeLedger(ledger, valuesTotal);
     if (ledgerLines.length > 0) {
         say("");
         say(section("Every style fragment, accounted for"));
@@ -2138,25 +2160,6 @@ export async function takeCensus(root, opts) {
         const target = c?.canonical ?? (c?.bucket === "exclusive" ? c.name : null);
         return target ? safePartName(target) : null;
     }, (pkg) => versions[pkg]);
-    /**
-     * A CONTABILIDADE POR VALOR, contada AQUI porque o material é daqui: os tokens de classe que
-     * vestem cada componente admitido (os nós do sketch e as camadas condicionais cruas), contra
-     * os tokens que o CSS dele declara. Ver `Census.values` e `doctor/value-ledger.ts` - é a
-     * reconciliação do item 11, e a soma fecha com `seen` por construção.
-     */
-    const valueByComponent = {};
-    for (const [lookName, look] of Object.entries(looks)) {
-        const tokens = [];
-        for (const node of look.sketch ?? []) {
-            tokens.push(...(node.classes ?? "").split(/\s+/).filter(Boolean));
-        }
-        for (const layer of look.rawLayers ?? [])
-            tokens.push(...layer.classes);
-        if (tokens.length > 0) {
-            valueByComponent[lookName] = accountClasses(tokens, declaredValues);
-        }
-    }
-    const valuesTotal = sumAccounts(Object.values(valueByComponent));
     return {
         census: 1,
         project: {

package/dist/commands/template.js

@@ -2,6 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { fetchTemplate } from "../registry.js";
+import { inTheirTongue, projectTongue } from "../their-tongue.js";
 /**
  * Materializes a whole page from a DS template into the project (hybrid
  * codegen-first): the server codegens deterministic files, we write them, and
@@ -27,14 +28,46 @@ export async function template(slug, name, opts) {
     const defaultDir = join("templates", asName ?? name);
     const pageRel = opts.out ?? join(defaultDir, pageFile.filename);
     const pageDir = dirname(join(root, pageRel));
+    /**
+     * NENHUMA MATERIALIZAÇÃO VAZA VOCABULÁRIO INTERNO (INV-VOLTA-02) - a mesma porta do
+     * `component`. Uma página inteira saía com `var(--ds-*)` cru enquanto um componente avulso
+     * falava a língua dele; a promessa é uma só. Sem mapa no `.lock`, nada é traduzido e a folha
+     * instalada continua sendo o caminho - e a saída diz qual dos dois aconteceu.
+     */
+    const tongue = await projectTongue(root, slug);
+    const speak = (code) => (tongue ? inTheirTongue(code, tongue) : null);
+    let named = 0;
+    let inlined = 0;
+    const still = new Set();
     await mkdir(pageDir, { recursive: true });
-    await writeFile(join(root, pageRel), pageFile.code, "utf8");
+    const spokenPage = speak(pageFile.code);
+    if (spokenPage) {
+        named += spokenPage.named;
+        inlined += spokenPage.inlined;
+        for (const l of spokenPage.left)
+            still.add(l);
+    }
+    await writeFile(join(root, pageRel), spokenPage ? spokenPage.css : pageFile.code, "utf8");
     console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
     for (const f of siblings) {
         const rel = join(dirname(pageRel), f.filename);
-        await writeFile(join(root, rel), f.code, "utf8");
+        const spoken = speak(f.code);
+        if (spoken) {
+            named += spoken.named;
+            inlined += spoken.inlined;
+            for (const l of spoken.left)
+                still.add(l);
+        }
+        await writeFile(join(root, rel), spoken ? spoken.css : f.code, "utf8");
         console.log(`✓ wrote ${rel}`);
     }
+    if (named > 0 || inlined > 0) {
+        console.log(`  ${named} reference${named === 1 ? "" : "s"} now speak${named === 1 ? "s" : ""} the name YOUR code gives the value${inlined > 0 ? `, and ${inlined} carr${inlined === 1 ? "ies" : "y"} the value because your code names no token for it` : ""}.`);
+        if (still.size > 0) {
+            const sample = [...still].sort().slice(0, 3).join(", ");
+            console.log(`  ${still.size} still point${still.size === 1 ? "s" : ""} at our stylesheet (${sample}${still.size > 3 ? ", …" : ""}), so tokens.css is still needed here.`);
+        }
+    }
     console.log("");
     console.log("Next steps:");
     console.log(`  • use it in a route, e.g. ${join(config.pagesDir, "page.tsx")}:`);

package/dist/doctor/gap-triage.js

@@ -20,6 +20,7 @@
  * decisão de escrever é de quem lê - a esteira opinando sobre o nosso backlog no terminal do
  * cliente é ela falando de um assunto que não é dela (dono, 05/08).
  */
+import { describeValueRuler } from "./style-ledger.js";
 /**
  * QUEM É DONO DE CADA FORMA, hoje.
  *
@@ -151,8 +152,10 @@ export function triageLedger(ledger, triagedBy) {
     };
 }
 /** `0.16.133` é mais velha que `0.16.134`. Compara número por número, e o que não é número não
- *  desempata nada - uma pré-release não é motivo para dizer que a medição está velha. */
-function isOlder(measured, current) {
+ *  desempata nada - uma pré-release não é motivo para dizer que a medição está velha.
+ *  Exportada porque é a TERCEIRA cópia desta pergunta (cli-version.ts e reinterpret.ts na web têm
+ *  as outras) e a auditoria de 26/08 a encontrou fora do twin-drift - agora ele a amarra. */
+export function isOlder(measured, current) {
     const parts = (v) => v.split(".").map((p) => Number.parseInt(p, 10));
     const a = parts(measured);
     const b = parts(current);
@@ -173,11 +176,23 @@ function isOlder(measured, current) {
  * do não interpretado ser o portão funcionando é a informação mais importante da tela, e ela vem
  * antes de qualquer lista de tarefa.
  */
-export function describeTriage(t) {
+export function describeTriage(t, 
+/**
+ * A RÉGUA ÚNICA (ver `describeValueRuler`): quando o censo carrega o ledger de valores, o
+ * percentual que abre esta tela é o MESMO da tela do sistema e do fim do `import`. Era aqui
+ * que nascia a segunda resposta - "348 fragmentos, 36%" contra os 91% reais do codelevel
+ * (26/08) - e o agente do dono repassou a errada ao cliente.
+ */
+values) {
     const unread = t.counted - t.interpreted;
-    const lines = [
-        `${t.counted} style fragments accounted for, ${t.interpreted} interpreted (${t.percent}%). The ${unread} below are sorted by what to do about them.`,
-    ];
+    const lines = values
+        ? [
+            ...describeValueRuler(values),
+            `The ${unread} style fragments not interpreted are sorted below by what to do about them.`,
+        ]
+        : [
+            `${t.counted} style fragments accounted for, ${t.interpreted} interpreted (${t.percent}%). The ${unread} below are sorted by what to do about them.`,
+        ];
     if (t.stale) {
         lines.push("", `MEASURED BY CLI ${t.measuredBy}, TRIAGED BY ${t.triagedBy}. Re-run \`import\` before concluding anything from the numbers below - a gap here may already be closed, and the work already done.`);
     }

package/dist/doctor/style-ledger.js

@@ -278,14 +278,27 @@ function blank() {
  * nomeia cada lacuna com o número do repo dela. Um percentual sem a contagem atrás é número de
  * marketing, e um zero sem motivo lê como falha nossa.
  */
-export function describeLedger(l) {
+export function describeLedger(l, 
+/**
+ * A RÉGUA ÚNICA - o ledger de valores por declaração (ver `Census.values.classes`). Quando ela
+ * existe, "quanto vocês entenderam?" tem UMA resposta, e é esta: a mesma que a tela usa. O
+ * total de fragmentos continua dito - é a promessa de contabilidade -, mas sem um segundo
+ * percentual competindo (o agente do dono liderou com "36%" quando a leitura real era 91%,
+ * medido no codelevel em 26/08).
+ */
+values) {
     const total = sum(l.counted);
     if (total === 0)
         return [];
     const read = sum(l.interpreted);
-    const lines = [
-        `${total} style fragments in your files, and every one is accounted for: ${read} interpreted (${Math.round((read / total) * 100)}%), ${total - read} listed below with the file and line where each lives.`,
-    ];
+    const lines = values
+        ? [
+            ...describeValueRuler(values),
+            `And every one of the ${total} style fragments in your files is accounted for - the ${total - read} not interpreted are listed below with the file and line where each lives.`,
+        ]
+        : [
+            `${total} style fragments in your files, and every one is accounted for: ${read} interpreted (${Math.round((read / total) * 100)}%), ${total - read} listed below with the file and line where each lives.`,
+        ];
     /**
      * POR FORMA, ANTES DOS GRUPOS. O total responde "quanto"; esta tabela responde "de que jeito o
      * projeto escreve estilo", que é a pergunta que decide qual leitor vale construir. Sem ela, 56%
@@ -319,3 +332,16 @@ export function describeLedger(l) {
 function sum(counts) {
     return Object.values(counts).reduce((n, k) => n + k, 0);
 }
+/**
+ * A frase da régua única, com todo denominador em palavras - `import` e `gaps` a imprimem
+ * IDÊNTICA, porque duas variações da mesma frase viram duas respostas na cabeça de quem lê.
+ * A conta é a da tela: decisões = vistas - estrutura; fechadas = interpretadas + respondidas.
+ */
+export function describeValueRuler(values) {
+    const decisions = values.seen - values.structure;
+    const closed = values.interpreted + values.answered;
+    const percent = decisions > 0 ? Math.round((closed / decisions) * 100) : 0;
+    return [
+        `Of the ${values.seen} class declarations on your components, ${values.structure} are structure (layout plumbing, not design decisions). Of the ${decisions} design decisions, ${closed} are interpreted${values.answered > 0 ? ` (${values.answered} of them answered by you)` : ""} - ${percent}%.`,
+    ];
+}

package/dist/their-tongue.js

@@ -45,3 +45,43 @@ export function tongueOf(map, installedCss) {
     }
     return { names, values };
 }
+/**
+ * NENHUMA MATERIALIZAÇÃO VAZA VOCABULÁRIO INTERNO - a regra da camada, num lugar só (dono, 26/08).
+ *
+ * Toda saída que escreve código no repositório dele passa por ESTA porta: carrega o vocabulário do
+ * projeto (`projectTongue`) e traduz (`inTheirTongue`). O `template` entregava páginas inteiras com
+ * `--ds-*` cru enquanto o `component` traduzia - a mesma promessa, duas implementações, uma delas
+ * ausente. Um mecanismo novo de materialização que chamar esta função já nasce coberto; um que não
+ * chamar é reprovado pelo gate (ver contracts/camada-6-volta.md, INV-VOLTA-02).
+ *
+ * `null` quando não há mapa: projeto de destino, repositório que nunca buildou, ou install anterior
+ * a 0.16.290. Nos três casos nada é traduzido e a folha instalada continua sendo o caminho - e quem
+ * chama DIZ qual dos dois aconteceu.
+ */
+export async function projectTongue(root, slug) {
+    const { readFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const dir = join(root, "_synthesisui", "ds", slug);
+    const lock = await readFile(join(dir, ".lock"), "utf8").catch(() => null);
+    if (!lock)
+        return null;
+    let map = [];
+    let version = 0;
+    try {
+        const parsed = JSON.parse(lock);
+        map = parsed.tokenMap ?? [];
+        version = parsed.version ?? 0;
+    }
+    catch {
+        return null;
+    }
+    if (map.length === 0)
+        return null;
+    /**
+     * O VALOR COMPILADO MORA NA PASTA DA VERSÃO - a folha da raiz é um re-export de uma linha, escrito
+     * assim de propósito para que o `@import` dele nunca mude entre updates (ver `add.ts`). É de lá
+     * que sai o literal para as variáveis que não têm nome dele.
+     */
+    const installed = await readFile(join(dir, `v${version}`, "tokens.css"), "utf8").catch(() => "");
+    return tongueOf(map, installed);
+}

package/package.json

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