synthesisui 0.16.251 → 0.16.252

package/dist/commands/import.js

@@ -3,6 +3,7 @@ import { basename, dirname, join, relative } from "node:path";
 import { anatomyFromSketch } from "../anatomy-from-sketch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
+import { declaredElsewhere } from "../declared-elsewhere.js";
 import { architectureRule, describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { nestingRules, propRules, readDefinitionProps, readNesting, readRuntime, } from "../doctor/call-sites.js";
@@ -37,6 +38,7 @@ import { withLibraryStructure } from "../library-structure.js";
 import { body, paint, section } from "../output.js";
 import { phase, startProgress } from "../progress.js";
 import { detectStack, resolveDeps, stackVersions } from "../stack.js";
+import { placeInWorkspace } from "../workspace-place.js";
 import { walk, walkAll } from "./doctor.js";
 /**
  * How many distinct values travel, PER KIND.
@@ -1996,7 +1998,15 @@ export async function takeCensus(root, opts) {
         },
     };
 }
-function summarize(c) {
+/**
+ * O RESUMO RECEBE O LUGAR JUNTO COM O CENSO - e não a metade dele.
+ *
+ * `sayBrokenRefs` precisa saber ONDE procurar a declaração que o escopo não viu,
+ * e um parâmetro opcional aqui seria a mesma porta que o §6 do método manda
+ * fechar: uma função que pode ser chamada pela metade vai ser, e o sintoma seria
+ * o relatório voltando a dizer "your CSS never declares" sem que nada falhe.
+ */
+async function summarize(c, root, scope) {
     const byKind = new Map();
     for (const v of c.observed)
         byKind.set(v.kind, (byKind.get(v.kind) ?? 0) + v.count);
@@ -2045,7 +2055,7 @@ function summarize(c) {
         }
     }
     sayConventions(c);
-    sayBrokenRefs(c);
+    await sayBrokenRefs(c, root, scope);
 }
 /**
  * THEIR VOCABULARY, MEASURED. This section exists so every later finding can be
@@ -2076,14 +2086,70 @@ function sayConventions(c) {
  * finding that needs no agreement with us: the convention being broken is
  * theirs.
  */
-function sayBrokenRefs(c) {
-    const broken = c.brokenRefs ?? [];
-    if (broken.length === 0)
+/**
+ * A PASTA QUE CONTÉM TODOS ESTES CAMINHOS - o `--scope` que traria as
+ * declarações junto, derivado dos endereços e não sugerido de cabeça.
+ *
+ * Devolve `null` quando os caminhos não compartilham pasta nenhuma: aí não existe
+ * um escopo único que resolva, e inventar um seria pior que dizer a regra geral.
+ */
+function commonPrefix(paths) {
+    if (paths.length === 0)
+        return null;
+    const out = [];
+    for (let i = 0;; i++) {
+        const seg = paths[0][i];
+        // O último segmento é o arquivo, e um arquivo não é um escopo.
+        if (seg == null || i >= paths[0].length - 1)
+            break;
+        if (!paths.every((p) => p[i] === seg && i < p.length - 1))
+            break;
+        out.push(seg);
+    }
+    return out.length > 0 ? out.join("/") : null;
+}
+async function sayBrokenRefs(c, root, scope) {
+    const all = c.brokenRefs ?? [];
+    if (all.length === 0)
         return;
+    /**
+     * DUAS PERGUNTAS DIFERENTES, E O RELATÓRIO FAZIA UMA SÓ.
+     *
+     * "Não resolve no que eu medi" e "não existe no seu código" são coisas
+     * distintas, e o texto afirmava a segunda. Com `--scope src/components` no
+     * monorepo do dono são 1021 referências contra 2 declarações, enquanto o CSS
+     * dele declara 118 em `src/app/**` e 764 em `packages/ui` (medido 19/08).
+     *
+     * Culpar o CSS de quem confiou o repositório por um recorte NOSSO é o pior
+     * lugar para errar: o relatório é o que a pessoa lê depois, sozinha.
+     */
+    const at = await declaredElsewhere(root, scope, all.map((b) => b.name)).catch(() => new Map());
+    const outside = all.filter((b) => at.has(b.name));
+    const broken = all.filter((b) => !at.has(b.name));
+    if (outside.length > 0) {
+        const uses = outside.reduce((n, b) => n + b.count, 0);
+        console.log("");
+        console.log(section("These are declared outside what was measured"));
+        console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${outside.length} token${outside.length === 1 ? "" : "s"} your code DOES declare - just not inside ${paint.strong(scope ?? "this folder")}. Your CSS is fine; the recipes carry the value you typed instead of the name you gave it, because the name was not in what we read.`));
+        console.log("");
+        for (const b of outside.slice(0, 6)) {
+            console.log(body(`${paint.strong(`var(${b.name})`)} ${paint.faint(`${b.count}× here`)} - declared in ${paint.strong(at.get(b.name) ?? "")}`));
+        }
+        if (outside.length > 6)
+            console.log(body(paint.faint(`(${outside.length - 6} more)`)));
+        console.log("");
+        /** O caminho comum dos endereços é o escopo que traria todos de uma vez. */
+        const wider = commonPrefix([...at.values()].map((v) => v.split("/")));
+        console.log(body(wider
+            ? `A wider ${paint.strong("--scope")} keeps your names: ${paint.strong(`--scope ${wider}`)} covers the declarations above.`
+            : "A wider --scope keeps your names, because the declarations come along with the code that uses them."));
+        if (broken.length === 0)
+            return;
+    }
     const uses = broken.reduce((n, b) => n + b.count, 0);
     console.log("");
     console.log(section("These resolve to nothing"));
-    console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${broken.length} token${broken.length === 1 ? "" : "s"} your CSS never declares. A ${paint.strong("var()")} with no declaration paints no colour - not a different colour. Where exactly one declared token differs by a namespace, the recipe now uses THAT one, so the look survives; the rest travel as the value you typed.`));
+    console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${broken.length} token${broken.length === 1 ? "" : "s"} nothing in this repository declares. A ${paint.strong("var()")} with no declaration paints no colour - not a different colour. Where exactly one declared token differs by a namespace, the recipe now uses THAT one, so the look survives; the rest travel as the value you typed.`));
     console.log("");
     for (const b of broken.slice(0, 8)) {
         const where = `${b.count}× in ${b.files} file${b.files === 1 ? "" : "s"}`;
@@ -2286,6 +2352,75 @@ function printAgentContract() {
  * just stops letting a person believe the average of three apps is their design
  * system.
  */
+/**
+ * O LUGAR, DITO ANTES DO ESCOPO - e o comando que a resposta implica.
+ *
+ * A detecção de monorepo olhava só para BAIXO (`siblingProjects` lê `apps/`,
+ * `packages/`, `libs/` dentro do root), então quem roda o import de dentro do app
+ * que está migrando recebia silêncio: `apps/web-dashboard` não contém `apps/`.
+ * Medido no monorepo do dono (19/08): 5 pacotes, `packages/ui` declarando 764
+ * tokens em 3 arquivos contra 114 em 6 no app onde ele rodou, e o aviso que
+ * ensina `--scope packages/ui --usage apps/web-dashboard` nunca apareceu.
+ *
+ * A ORDEM É A DA DÚVIDA DE QUEM LÊ: onde eu estou, onde mora o vocabulário, e só
+ * então o comando. Um comando oferecido antes das duas primeiras respostas é uma
+ * receita para copiar sem entender.
+ */
+async function sayAboutPlace(root, scope) {
+    const place = await placeInWorkspace(root);
+    /** Sem workspace acima, a pergunta antiga ainda vale: há projetos AQUI dentro? */
+    if (!place) {
+        if (!scope)
+            await sayIfWorkspace(root);
+        return;
+    }
+    /** Na raiz do workspace o aviso que já existia é o certo - ele lista os apps. */
+    if (place.here === null) {
+        if (!scope)
+            await sayIfWorkspace(root);
+        return;
+    }
+    const vocab = place.vocabulary;
+    const mine = place.packages.find((p) => p.rel === place.here);
+    /**
+     * NADA A DIZER quando o vocabulário está aqui mesmo: a pessoa escolheu o
+     * pacote que declara os tokens, e repetir o que ela acertou é ruído.
+     */
+    if (!vocab || vocab.rel === place.here)
+        return;
+    /** Nem quando o escopo dado já aponta para lá - ela já sabe. */
+    if (scope && join(place.here, scope) === vocab.rel)
+        return;
+    const up = relative(root, place.workspaceRoot).split("\\").join("/") || ".";
+    /**
+     * SÓ QUEM CONSOME A BIBLIOTECA doa evidência. Oferecer `--usage apps/web-admin`
+     * para um app que nunca a importa ensina a medir escolhas de um lugar que não
+     * vota - e `--usage` existe justamente para dizer quais escolhas já são lei.
+     * Medido no monorepo do dono: dos dois outros apps, nenhum declara a
+     * biblioteca, e a primeira versão desta mensagem oferecia os dois.
+     */
+    const consumers = place.packages.filter((p) => p.rel !== vocab.rel &&
+        p.rel !== place.here &&
+        vocab.name != null &&
+        p.dependsOn.includes(vocab.name));
+    const usage = [place.here, ...consumers.map((c) => c.rel)]
+        .slice(0, 3)
+        .map((a) => `--usage ${a}`)
+        .join(" ");
+    console.log("");
+    console.log(section("This folder is one package of a workspace"));
+    console.log(body(`${paint.strong(place.here)} is one of ${place.packages.length} packages under ${paint.strong(place.workspaceRoot)}.`));
+    console.log("");
+    console.log(body(`And the vocabulary is not here: ${paint.strong(vocab.rel)} declares ${vocab.declarations} token${vocab.declarations === 1 ? "" : "s"} across ${vocab.files} file${vocab.files === 1 ? "" : "s"}, while this package declares ${mine?.declarations ?? 0} across ${mine?.files ?? 0}.`));
+    console.log(body(paint.faint("A system built from the app is the average of one consumer; the tokens live where the library declares them.")));
+    console.log("");
+    console.log(body("The system is one place, and the evidence is another:"));
+    console.log("");
+    console.log(body(`    ${paint.strong(`synthesisui import --dir ${up} --scope ${vocab.rel} ${usage}`)}`));
+    console.log(body(paint.faint(`      --dir points at the workspace root, so --scope and --usage are read from there.`)));
+    console.log("");
+    console.log(body(paint.dim("Nothing you ran is wasted - this census is a fine diagnosis of this app. It is a system for one consumer, which is the part worth knowing before you publish it.")));
+}
 async function sayIfWorkspace(root) {
     const { apps, shared } = await siblingProjects(root);
     if (apps.length < 2)
@@ -3058,11 +3193,22 @@ export async function runImport(opts) {
      */
     if (!opts.census)
         await resolveReadParts(census, root);
-    summarize(census);
-    // Only when nobody has scoped yet. Telling someone to scope to the folder
-    // they just scoped to reads as the tool not having noticed.
-    if (!opts.census && !scope)
-        await sayIfWorkspace(root);
+    await summarize(census, root, scope);
+    /**
+     * ONDE ESTOU vem antes de O QUE EU LEIO, e o `!scope` calava exatamente quem
+     * mais precisava ouvir.
+     *
+     * A condição era "só quando ninguém escopou ainda", pelo motivo certo: mandar
+     * escopar para a pasta que a pessoa acabou de escopar lê como a ferramenta não
+     * ter percebido. Só que ela também calava o caso em que o escopo escolhido não
+     * é onde o vocabulário mora - e aí o silêncio não é discrição, é perder a
+     * única chance de dizer que o sistema está em outro pacote.
+     *
+     * `sayAboutPlace` faz as duas perguntas na ordem: onde este comando está, e
+     * onde as declarações estão. Ele só fala quando as respostas divergem.
+     */
+    if (!opts.census)
+        await sayAboutPlace(root, scope);
     // A census handed to us is written BACK TO ITSELF; one we took lands at the
     // ROOT, whatever it measured. Everything else in `_synthesisui/` is anchored
     // there - config, `ds/<slug>/`, the hook's marker - and the census was the

package/dist/declared-elsewhere.js

@@ -0,0 +1,77 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { placeInWorkspace } from "./workspace-place.js";
+/**
+ * ONDE ESTE TOKEN É DECLARADO, QUANDO NÃO É NO QUE FOI MEDIDO.
+ *
+ * `findBrokenRefs` compara os `var()` do escopo contra as declarações do escopo,
+ * e o relatório chama o resto de *"tokens your CSS never declares"*. Com
+ * `--scope` isso pode ser falso, e no monorepo do dono era (19/08):
+ * `--scope src/components` deixa 1021 referências contra 2 declarações, e o CSS
+ * dele declara 118 em `src/app/**` e 764 em `packages/ui`.
+ *
+ * Afirmar um defeito que não existe no código de quem confiou o repositório é
+ * pior do que não dizer nada - o relatório é o documento que a pessoa lê depois,
+ * sozinha, e ele estava culpando o CSS dela por uma escolha de recorte NOSSA.
+ *
+ * Então a pergunta muda de "existe?" para "existe ONDE?", em duas camadas: fora
+ * do escopo mas dentro do que foi apontado, e nos outros pacotes do mesmo
+ * workspace - que é onde uma biblioteca de design system mora.
+ */
+const SHEET = /\.(css|scss|sass|less)$/i;
+const DECL = /(^|[\s{;])(--[a-zA-Z0-9-]+)\s*:/g;
+/** Onde cada nome aparece declarado, primeiro achado ganha - basta um endereço. */
+async function harvest(dir, label, skip, into) {
+    const visit = async (at, depth) => {
+        if (depth > 8)
+            return;
+        for (const e of await readdir(at, { withFileTypes: true }).catch(() => [])) {
+            if (e.name.startsWith(".") || e.name === "node_modules")
+                continue;
+            const full = join(at, e.name);
+            if (skip && full === skip)
+                continue;
+            if (e.isDirectory()) {
+                await visit(full, depth + 1);
+                continue;
+            }
+            if (!SHEET.test(e.name))
+                continue;
+            const body = await readFile(full, "utf8").catch(() => "");
+            for (const m of body.matchAll(DECL)) {
+                const name = m[2];
+                if (!into.has(name))
+                    into.set(name, `${label}${relative(dir, full).split("\\").join("/")}`);
+            }
+        }
+    };
+    await visit(dir, 0);
+}
+/**
+ * NOME -> CAMINHO onde ele é declarado, fora do que foi medido.
+ *
+ * Só roda quando há algo a explicar: sem referências pendentes não há pergunta,
+ * e um walk a mais por nada é um walk a mais.
+ */
+export async function declaredElsewhere(root, scope, names) {
+    const out = new Map();
+    if (names.length === 0)
+        return out;
+    const wanted = new Set(names);
+    const found = new Map();
+    /** Camada 1: o resto do que a pessoa apontou, sem reler o escopo. */
+    await harvest(root, "", scope ? join(root, scope) : null, found);
+    /** Camada 2: os outros pacotes do workspace - onde uma biblioteca mora. */
+    const place = await placeInWorkspace(root);
+    if (place) {
+        for (const pkg of place.packages) {
+            if (pkg.rel === place.here)
+                continue;
+            await harvest(join(place.workspaceRoot, pkg.rel), `${pkg.rel}/`, null, found);
+        }
+    }
+    for (const [name, where] of found)
+        if (wanted.has(name))
+            out.set(name, where);
+    return out;
+}

package/dist/stack.js

@@ -27,6 +27,15 @@ import { join } from "node:path";
  * app que usa o sistema, então o manifesto daquele app é evidência tanto quanto
  * o da raiz.
  */
+/**
+ * O RANGE QUE DIZ "ISTO É DESTE REPOSITÓRIO" - o mesmo prefixo que
+ * `frontier-kind.ts` já reconhece como local, escrito aqui uma vez.
+ *
+ * Sobrescrever o range com este valor é mais verdadeiro do que preservar o que o
+ * app digitou: um `*` num monorepo NÃO significa "qualquer versão do npm", e era
+ * assim que ele estava sendo lido.
+ */
+const LOCAL_RANGE = "workspace:*";
 export async function resolveDeps(root) {
     const deps = {};
     const workspaceDirs = [];
@@ -84,6 +93,47 @@ export async function resolveDeps(root) {
     }
     for (const w of workspaceDirs)
         await readManifest(w);
+    /**
+     * O NOME DE UM PACOTE DESTE WORKSPACE É LOCAL, QUALQUER QUE SEJA O RANGE - e
+     * é a lei 13 se aplicando a si mesma: a ORIGEM decide, não o nome.
+     *
+     * Medido no monorepo do dono (19/08): `apps/web-dashboard` declara
+     * `"@frontend-hub/ui": "*"`, que é como npm e yarn workspaces apontam para o
+     * pacote ao lado. `LOCAL_RANGE` em `frontier-kind.ts` reconhece
+     * `workspace:|file:|link:|portal:`, então `frontierOf` respondia `opaque` -
+     * "de terceiro, se desenha sozinha" - sobre a biblioteca que É o design
+     * system dele, em 52 arquivos daquele app. Um monorepo que versiona de
+     * verdade (`"^2.1.0"`) caía igual.
+     *
+     * Quem decidia era o FORMATO DO RANGE, que não é a origem nem o nome: é uma
+     * terceira coisa. A origem está aqui - a raiz declara `workspaces`, e um
+     * daqueles diretórios tem um `package.json` cujo `name` é aquele
+     * especificador. Este laço grava esse fato, e ele SOBRESCREVE o range que o
+     * app escreveu, porque um pacote deste repositório não deixa de ser deste
+     * repositório por causa de como alguém o apontou.
+     *
+     * Corrigido aqui e não em `frontier-kind.ts` por dois motivos: a informação já
+     * passa por esta função, e aquele arquivo é gêmeo byte-idêntico de
+     * `libs/ds-contracts/src/frontier-kind.ts` - mudar a pergunta lá custaria os
+     * dois, e a pergunta lá está certa.
+     *
+     * ENTRA MESMO SEM O APP DECLARAR: alias de tsconfig, import direto ou
+     * dependência esquecida - o pacote existe no repositório, e é isso que a lei
+     * pergunta.
+     */
+    for (const w of workspaceDirs) {
+        const raw = await readFile(join(w, "package.json"), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        try {
+            const name = JSON.parse(raw).name;
+            if (typeof name === "string" && name)
+                deps[name] = LOCAL_RANGE;
+        }
+        catch {
+            // manifesto ilegível custa a detecção daquele pacote, nunca a corrida
+        }
+    }
     return deps;
 }
 /**

package/dist/workspace-place.js

@@ -0,0 +1,140 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+const MANIFEST = "package.json";
+const SHEET = /\.(css|scss|sass|less)$/i;
+const DECL = /(^|[\s{;])--[a-zA-Z0-9-]+\s*:/g;
+async function manifest(dir) {
+    const raw = await readFile(join(dir, MANIFEST), "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Os globs que um manifesto usa para declarar workspaces, nas duas formas reais. */
+function workspaceGlobs(p) {
+    const w = p.workspaces;
+    const list = Array.isArray(w)
+        ? w
+        : Array.isArray(w?.packages)
+            ? w.packages
+            : [];
+    return list.filter((g) => typeof g === "string");
+}
+/**
+ * Quantas custom properties um pacote declara - o mesmo peso que
+ * `siblingProjects` já usa para escolher entre `packages/core` e `packages/ui`.
+ *
+ * Diretório com ponto e `node_modules` ficam fora pelo mesmo motivo que o `walk`
+ * do doctor os ignora: `.next/` guarda CSS COMPILADO, e contá-lo faria o build
+ * output votar em onde mora o vocabulário.
+ */
+async function weigh(dir) {
+    let declarations = 0;
+    let files = 0;
+    const visit = async (at, depth) => {
+        if (depth > 8)
+            return;
+        for (const e of await readdir(at, { withFileTypes: true }).catch(() => [])) {
+            if (e.name.startsWith(".") || e.name === "node_modules")
+                continue;
+            const full = join(at, e.name);
+            if (e.isDirectory()) {
+                // Um pacote aninhado fala o próprio sistema - ver `walk`, mesma regra.
+                if (await manifest(full))
+                    continue;
+                await visit(full, depth + 1);
+                continue;
+            }
+            if (!SHEET.test(e.name))
+                continue;
+            const body = await readFile(full, "utf8").catch(() => "");
+            const n = (body.match(DECL) ?? []).length;
+            if (n > 0) {
+                declarations += n;
+                files += 1;
+            }
+        }
+    };
+    await visit(dir, 0);
+    return { declarations, files };
+}
+/**
+ * O LUGAR, ou `null` quando não há workspace nenhum acima - e aí não há nada a
+ * anunciar, que é o caso da maioria dos projetos.
+ *
+ * Sobe no máximo quatro níveis, o mesmo teto de `resolveDeps`: cobre todo layout
+ * pnpm/npm/yarn sem sair andando pela pasta pessoal de quem roda.
+ */
+export async function placeInWorkspace(root) {
+    let dir = root;
+    let workspaceRoot = null;
+    let globs = [];
+    for (let up = 0; up < 4; up++) {
+        const p = await manifest(dir);
+        if (p) {
+            const g = workspaceGlobs(p);
+            if (g.length > 0) {
+                workspaceRoot = dir;
+                globs = g;
+                break;
+            }
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (!workspaceRoot)
+        return null;
+    const dirs = [];
+    for (const g of globs) {
+        if (g.endsWith("/*")) {
+            const parent = join(workspaceRoot, g.slice(0, -2));
+            for (const e of await readdir(parent, { withFileTypes: true }).catch(() => []))
+                if (e.isDirectory())
+                    dirs.push(join(parent, e.name));
+        }
+        else if (!g.includes("*")) {
+            dirs.push(join(workspaceRoot, g));
+        }
+    }
+    const packages = [];
+    const local = new Set();
+    const read = [];
+    for (const d of dirs) {
+        const p = await manifest(d);
+        if (!p)
+            continue;
+        read.push({ p, d });
+        if (typeof p.name === "string")
+            local.add(p.name);
+    }
+    for (const { p, d } of read) {
+        const { declarations, files } = await weigh(d);
+        const deps = {
+            ...(p.dependencies ?? {}),
+            ...(p.devDependencies ?? {}),
+        };
+        packages.push({
+            rel: relative(workspaceRoot, d).split("\\").join("/"),
+            name: typeof p.name === "string" ? p.name : null,
+            declarations,
+            files,
+            dependsOn: Object.keys(deps).filter((k) => local.has(k)),
+        });
+    }
+    if (packages.length === 0)
+        return null;
+    const rel = relative(workspaceRoot, root).split("\\").join("/");
+    const ranked = [...packages].sort((a, b) => b.declarations - a.declarations);
+    return {
+        workspaceRoot,
+        here: rel === "" ? null : rel,
+        packages,
+        vocabulary: ranked[0]?.declarations > 0 ? ranked[0] : null,
+    };
+}

package/package.json

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