synthesisui 0.16.296 → 0.16.298

package/dist/commands/import.js

@@ -47,8 +47,9 @@ import { body, paint, section } from "../output.js";
 import { outsideScope } from "../outside-scope.js";
 import { phase, startProgress } from "../progress.js";
 import { repoStateOf } from "../repo-state.js";
-import { runtimeDeclaredVars } from "../runtime-vars.js";
+import { runtimeDeclaredVars, runtimeDeclaredVarsIn } from "../runtime-vars.js";
 import { detectStack, resolveDeps, stackVersions } from "../stack.js";
+import { wiredSlugs, wiringWarning } from "../wired-slugs.js";
 import { placeInWorkspace } from "../workspace-place.js";
 import { add } from "./add.js";
 import { walk, walkAll } from "./doctor.js";
@@ -1945,6 +1946,27 @@ export async function takeCensus(root, opts) {
      */
     for (const name of runtimeDeclaredVars(sources))
         declaredNames.add(name);
+    /**
+     * E FORA DO ESCOPO TAMBÉM - senão o conserto acima não alcança um monorepo.
+     *
+     * Com um escopo estreitado este `root` É a pasta do escopo, então `sources` tem o escopo e mais
+     * nada. As fontes deste repositório são declaradas nos apps e CONSUMIDAS dentro da biblioteca - a
+     * divisão que o próprio Next recomenda, e não um acidente de organização.
+     *
+     * MEDIDO: com o leitor acima já publicado, a segunda corrida ainda reportou as quatro fontes como
+     * mortas. A promessa escrita acima é *"a name is only broken if NOTHING declares it, anywhere"*, e
+     * "anywhere" tem que incluir os roots que a pessoa nomeou em uso.
+     */
+    const usageRoots = (opts?.usage ?? []).map((u) => u.path);
+    if (usageRoots.length > 0) {
+        const outside = await runtimeDeclaredVarsIn(usageRoots, {
+            readdir: (p) => readdir(p, { withFileTypes: true, encoding: "utf8" }),
+            readFile: (p) => readFile(p, "utf8"),
+            join,
+        });
+        for (const name of outside)
+            declaredNames.add(name);
+    }
     /**
      * HOW SOMEBODY CALLS THE COMPONENT THEY ALREADY HAVE.
      *
@@ -2092,6 +2114,17 @@ export async function takeCensus(root, opts) {
             : {}),
         ...(animations.size > 0 ? { animations: [...animations].sort() } : {}),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
+        /**
+         * OS SISTEMAS QUE O CSS DELE JÁ CHAMA PELO NOME - ver `wiredSlugs`.
+         *
+         * Existe porque um import de 24/08 deixou o repositório do dono SEM COMPILAR: o CSS dele
+         * carrega `_synthesisui/ds/codelevel/`, o sistema nasceu como `codelevel-ds`, e o `next build`
+         * dele terminou em exit code 1 com `Can't resolve`. Não é cor errada - é o app parado.
+         *
+         * O campo é a metade medida da resposta; a outra é a pergunta do nome saber usá-lo. Aditivo e
+         * omitido quando não há nada cabeado, que é o caso de todo primeiro import limpo.
+         */
+        ...(wiredSlugs(css).length > 0 ? { wiredSlugs: wiredSlugs(css) } : {}),
         /**
          * OS NOMES DISPUTADOS - ver `name-claim.ts`.
          *
@@ -3974,6 +4007,26 @@ export async function runImport(opts) {
      * mais longa do produto ficar mais longa no lugar onde ela já é mais difícil de ler.
      */
     if (payload?.slug) {
+        /**
+         * A FIAÇÃO DELE CONTRA O SLUG QUE NASCEU - e este aviso sai do CLI, não da skill.
+         *
+         * MEDIDO em 24/08: o `globals.css` dele importa `_synthesisui/ds/codelevel/`, o nome escolhido
+         * derivou `codelevel-ds`, ninguém mencionou, e o `next build` dele terminou em exit code 1 com
+         * `Can't resolve`. O aplicativo do cliente parou de compilar por causa de um comando que a
+         * plataforma conduziu do começo ao fim.
+         *
+         * AQUI e não só no playbook porque o playbook é conselho e isto é fato: o slug chegou do
+         * servidor, a pasta vai ser escrita com ele, e a divergência é aritmética. Um aviso que depende
+         * de um agente ter lido o capítulo certo é um aviso que falta exatamente quando ele não leu -
+         * foi assim que este defeito passou.
+         */
+        const warning = wiringWarning(census.wiredSlugs ?? [], payload.slug);
+        if (warning) {
+            console.log("");
+            console.log(section("Your CSS points somewhere else"));
+            for (const line of warning.split("\n"))
+                console.log(body(line));
+        }
         try {
             await add(payload.slug, {
                 registry: opts.registry,

package/dist/runtime-vars.js

@@ -47,3 +47,56 @@ export function runtimeDeclaredVars(sources) {
     }
     return out;
 }
+/**
+ * E A DECLARAÇÃO PODE MORAR FORA DO ESCOPO - o caso que o conserto de 24/08 não alcançou.
+ *
+ * MEDIDO no `codelevel` na segunda corrida, já com o leitor acima publicado: as quatro fontes
+ * CONTINUARAM sendo reportadas como mortas. A causa não era o leitor - era o que chega nele.
+ *
+ * `--scope packages/ui` faz o `root` do censo ser a pasta do escopo, então a varredura vê
+ * `packages/ui` e mais nada. As fontes são declaradas em `apps/landing/app/fonts.ts` e
+ * `apps/web/app/fonts.ts`, e USADAS dentro de `packages/ui`. Essa divisão não é acidente de
+ * organização: num monorepo, o app carrega a fonte e a biblioteca a consome, e é a forma
+ * recomendada pelo próprio Next.
+ *
+ * O código já promete o contrário do que fazia - *"a name is only broken if NOTHING declares it,
+ * anywhere"* está escrito no ponto que monta a lista. "Anywhere" tem que incluir os roots de
+ * `--usage`, que a pessoa nomeou justamente para dizer onde o vocabulário é consumido.
+ *
+ * SÓ LEITURA, e só de arquivos de código: nada aqui escreve, e um root de uso já é lido para
+ * evidência - a diferença é que agora ele também pode DECLARAR.
+ */
+export async function runtimeDeclaredVarsIn(roots, read) {
+    const out = new Set();
+    const seen = new Set();
+    const walk = async (dir, depth) => {
+        /**
+         * O TETO DE PROFUNDIDADE é o que mantém isto barato num monorepo grande. Uma declaração de
+         * fonte mora no diretório de app (`app/fonts.ts`, `src/app/fonts.ts`, `styles/fonts.ts`) -
+         * quatro níveis cobrem as três formas com folga, e o custo não cresce com o tamanho do repo.
+         */
+        if (depth < 0 || seen.has(dir))
+            return;
+        seen.add(dir);
+        const entries = await read.readdir(dir).catch(() => []);
+        for (const e of entries) {
+            if (e.name.startsWith(".") || e.name === "node_modules")
+                continue;
+            const full = read.join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(full, depth - 1);
+                continue;
+            }
+            if (!/\.(ts|tsx|js|jsx|mjs)$/i.test(e.name))
+                continue;
+            const src = await read.readFile(full).catch(() => "");
+            if (!src)
+                continue;
+            for (const name of runtimeDeclaredVars([{ file: full, source: src }]))
+                out.add(name);
+        }
+    };
+    for (const r of roots)
+        await walk(r, 4);
+    return out;
+}

package/dist/wired-slugs.js

@@ -0,0 +1,86 @@
+/**
+ * OS SISTEMAS QUE O CSS DELE JÁ CHAMA PELO NOME - e o build que quebra quando o nome não bate.
+ *
+ * O QUE ACONTECEU, medido no repositório do dono em 24/08: o `globals.css` dele carrega
+ *
+ *     @import "../../../../_synthesisui/ds/codelevel/tokens.css";
+ *     @import "../../../../_synthesisui/ds/codelevel/theme.css";
+ *
+ * O import daquela corrida nasceu com o slug `codelevel-ds`, então o `add` escreveu
+ * `_synthesisui/ds/codelevel-ds/` e os dois `@import` passaram a apontar para uma pasta que não
+ * existe. O `next build` dele terminou em **exit code 1**:
+ *
+ *     Can't resolve '../../../../_synthesisui/ds/codelevel/tokens.css'
+ *
+ * Não é uma cor errada nem um token faltando: o aplicativo dele **não compila**. É o pior desfecho
+ * possível de uma esteira que existe para devolver o código dele funcionando, e ele sai de um
+ * comando que a plataforma conduziu do começo ao fim.
+ *
+ * POR QUE O SLUG PODE DIVERGIR: o nome é decisão dele, feita numa pergunta, e o slug deriva do
+ * nome. "CodeLevel" dá `codelevel`; "CodeLevel DS" dá `codelevel-ds`. As duas respostas são
+ * legítimas - o que não é legítimo é ninguém dizer que a segunda quebra o CSS que já está lá.
+ *
+ * ENTÃO A MEDIÇÃO VEM ANTES DA PERGUNTA. Este leitor responde "quais slugs o CSS deste repositório
+ * já espera encontrar", e o censo carrega a resposta. Com ela na mão, a pergunta do nome deixa de
+ * ser um campo em branco: existe um slug que faz a fiação resolver, e ele é dito em voz alta.
+ *
+ * DIZER, E NÃO DECIDIR. A plataforma não escolhe o nome do sistema dele nem reescreve o CSS dele -
+ * é o mesmo padrão do `add`, que imprime o `@import` e não o cola. O que ela deve é nunca deixá-lo
+ * escolher às cegas uma resposta que apaga o build.
+ */
+/**
+ * O caminho que a nossa própria instalação usa. Qualquer profundidade de `../`, porque a folha dele
+ * pode estar em qualquer nível - a do dono está quatro acima.
+ */
+const WIRED = /_synthesisui\/ds\/([a-z0-9][a-z0-9-]*)\//gi;
+/**
+ * Os slugs que o CSS dele já referencia, em ordem de aparição e sem repetir.
+ *
+ * Recebe o CSS já concatenado porque é isso que o censo tem em mão - uma segunda varredura de
+ * arquivos seria uma segunda medição, livre para discordar da primeira.
+ */
+export function wiredSlugs(css) {
+    const out = [];
+    for (const m of css.matchAll(WIRED))
+        if (!out.includes(m[1].toLowerCase()))
+            out.push(m[1].toLowerCase());
+    return out;
+}
+/**
+ * O QUE DIZER A ELE QUANDO O SISTEMA JÁ NASCEU COM OUTRO NOME.
+ *
+ * Roda DEPOIS do envio, com o slug que o servidor devolveu - então não é previsão, é fato: a pasta
+ * vai ser escrita com este nome e os `@import` dele apontam para outro.
+ *
+ * `null` quando o CSS não cabeia nada (todo primeiro import limpo) e quando o slug que nasceu já é
+ * um dos cabeados. Um aviso que aparece sempre é um aviso que ninguém lê.
+ *
+ * A frase carrega as três coisas que a decisão precisa: o que o CSS espera, o que existe agora, e o
+ * que acontece se ele não fizer nada. Sem a terceira isto é trivia - e foi a terceira que faltou na
+ * corrida que parou o build dele.
+ *
+ * DIZER, E NÃO CONSERTAR. O CSS é dele; reescrevê-lo por conta própria seria a plataforma editando
+ * o repositório de alguém sem pedir. É o mesmo padrão do `add`, que imprime o `@import` e não o
+ * cola.
+ */
+export function wiringWarning(
+/**
+ * A LISTA, e não o CSS - porque o censo já a carrega (`census.wiredSlugs`) e o CSS bruto não
+ * viaja nele. Recontar aqui seria uma segunda medição, livre para discordar da primeira.
+ */
+wired, slugThatWasBorn) {
+    if (wired.length === 0)
+        return null;
+    if (wired.includes(slugThatWasBorn.toLowerCase()))
+        return null;
+    return [
+        `Your CSS imports _synthesisui/ds/${wired[0]}/, and this system is "${slugThatWasBorn}".`,
+        `Those @import lines point at a folder that does not exist, and the build fails on them -`,
+        `not a missing colour, a build that stops. Point them at ${slugThatWasBorn} to fix it:`,
+        "",
+        `    @import ".../_synthesisui/ds/${slugThatWasBorn}/tokens.css";`,
+        `    @import ".../_synthesisui/ds/${slugThatWasBorn}/theme.css";`,
+        "",
+        "Yours to change - we do not edit your CSS.",
+    ].join("\n");
+}

package/package.json

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