synthesisui 0.16.253 → 0.16.255

package/dist/commands/add.js

@@ -154,7 +154,20 @@ export async function add(slug, opts) {
      * censo (um `add` puro, sem import antes), o que o lock já dizia é preservado.
      */
     const measured = await censusScope(projectRoot);
-    const scope = measured.system ?? prev?.scope ?? null;
+    /**
+     * OS DOIS CAMPOS: `scopes` com tudo e `scope` com o primeiro.
+     *
+     * O lock é o arquivo que um time COMMITA, e é o que faz um clone fresco saber de
+     * onde o sistema foi medido sem ida à rede. Guardar só o primeiro escopo ali
+     * fazia o `sync` de um clone novo remedir metade de um sistema de dois escopos.
+     * Um CLI anterior lê `scope` e segue funcionando.
+     */
+    const systems = measured.systems.length > 0
+        ? measured.systems
+        : measured.system
+            ? [measured.system]
+            : (prev?.scopes ?? (prev?.scope ? [prev.scope] : []));
+    const scope = systems[0] ?? null;
     const usage = measured.usage.length > 0 ? measured.usage : (prev?.usage ?? []);
     /**
      * `fetchedAt` SÓ ANDA QUANDO ALGO ATERROU - e a alternativa sujava o git de um time inteiro.
@@ -177,6 +190,7 @@ export async function add(slug, opts) {
         ...(payload.compiler != null ? { compiler: payload.compiler } : {}),
         ...(payload.rulesStamp ? { rules: payload.rulesStamp } : {}),
         ...(scope ? { scope } : {}),
+        ...(systems.length > 0 ? { scopes: systems } : {}),
         ...(usage.length > 0 ? { usage } : {}),
     };
     const landed = (() => {

package/dist/commands/doctor.js

@@ -42,7 +42,21 @@ import { resolveDeps } from "../stack.js";
 /** Files that compose components to SHOW them, not to ship them. */
 const IS_ASIDE = /(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/;
 const EXTS = [".tsx", ".ts", ".jsx", ".js", ".css", ".scss", ".vue", ".svelte"];
-const SKIP = new Set([
+/**
+ * EXPORTADO porque quem mede o repositório fora deste arquivo tem que pular as
+ * MESMAS pastas.
+ *
+ * `workspace-place.ts` contava as declarações de cada pacote com a sua própria
+ * regra (dotdir + node_modules) e somava `packages/ui/dist/index.css`: 496
+ * declarações de bundle contra 97 de fonte no repo do dono, medido em 19/08. O
+ * número que decidia qual pasta recomendar era cinco sextos build output - e o
+ * censo, que usa este SKIP, nunca leu nada daquilo.
+ *
+ * Duas listas de pastas a ignorar é a mesma classe de divergência que
+ * `loadSystem` existe para matar: nenhuma delas está errada isolada, e juntas
+ * dizem números diferentes sobre o mesmo repositório.
+ */
+export const SKIP = new Set([
     "node_modules",
     ".next",
     ".git",
@@ -551,7 +565,7 @@ export async function doctor(opts) {
      * lista de prioridades tirada de um app consumidor num repo de 2787 arquivos (dono, 06/08).
      */
     const measured = (opts.scopes ?? []).length > 0
-        ? { system: null, usage: [], from: "none" }
+        ? { system: null, systems: [], usage: [], from: "none" }
         : await measuredScope(root);
     const relScopes = (opts.scopes ?? []).length > 0
         ? opts.scopes

package/dist/commands/import.js

@@ -35,6 +35,7 @@ import { definitionSpan, parseClass, readInlineStyle, rootClasses, rootTag, tran
 import { transcribeVariants } from "../doctor/variant-read.js";
 import { frontierKind, packageRoot } from "../frontier-kind.js";
 import { withLibraryStructure } from "../library-structure.js";
+import { mergeCensus } from "../merge-census.js";
 import { claimName } from "../name-claim.js";
 import { body, paint, section } from "../output.js";
 import { phase, startProgress } from "../progress.js";
@@ -1147,13 +1148,39 @@ export async function takeCensus(root, opts) {
     const edges = new Map();
     /** Por raiz: `@/` é uma pasta diferente em cada app - ver `reachabilityOf`. */
     const graphRoots = [];
+    /**
+     * A DISTÂNCIA, contada onde os arquivos já estão abertos - ver `Census.adoption`.
+     *
+     * `scopePkg` é o nome do pacote do escopo, que é como um consumidor o importa.
+     * Um arquivo conta quando ele NOMEIA esse especificador, e a régua é o texto do
+     * import: um alias de tsconfig que aponta para a mesma pasta contaria como
+     * "não usa", e essa é a diferença entre um número menor e um número inventado.
+     */
+    const adoption = new Map();
     for (const u of opts?.usage ?? []) {
         const uInternal = await internalSpecifiers(u.path);
         graphRoots.push({ path: u.path, aliases: await aliasesOf(u.path) });
+        const tally = adoption.get(u.label) ?? { files: 0, using: 0 };
+        adoption.set(u.label, tally);
         for await (const file of walk(u.path)) {
             const src = await readFile(file, "utf8").catch(() => "");
             if (!src)
                 continue;
+            /**
+             * O DENOMINADOR SÓ CONTA QUEM PINTA.
+             *
+             * A primeira versão contava todo `.ts` - hooks, tipos, clientes http - e o
+             * app do dono saiu como 105 de 1578 (7%), quando 105 de 356 arquivos de
+             * marcação é 29%. Um arquivo de tipos não deixa de usar o design system:
+             * ele nunca teve como. Diluir o denominador com ele faz a migração parecer
+             * mais atrasada do que é, e um número pessimista é tão falso quanto um
+             * otimista.
+             */
+            if (/\.(tsx|jsx|vue|svelte)$/i.test(file)) {
+                tally.files += 1;
+                if (scopePkg && src.includes(scopePkg))
+                    tally.using += 1;
+            }
             edges.set(file, edgesIn(src));
             const rel = join(u.label, relative(u.path, file));
             if (/(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/.test(rel)) {
@@ -1914,6 +1941,18 @@ export async function takeCensus(root, opts) {
          * só aparece quando há algo a dizer não muda nada para quem já lê o censo.
          */
         ...(claims.collisions.length > 0 ? { collisions: claims.collisions } : {}),
+        ...(scopePkg && adoption.size > 0
+            ? {
+                adoption: {
+                    specifier: scopePkg,
+                    consumers: [...adoption.entries()].map(([label, t]) => ({
+                        label,
+                        files: t.files,
+                        using: t.using,
+                    })),
+                },
+            }
+            : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
         classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
@@ -2029,6 +2068,8 @@ export async function takeCensus(root, opts) {
             named: d.named,
             tokenUses: d.tokenUses,
             coverage: d.coverage,
+            ownUses: d.ownUses,
+            phantomUses: d.phantomUses,
         },
     };
 }
@@ -2089,9 +2130,73 @@ async function summarize(c, root, scope) {
         }
     }
     sayConventions(c);
+    sayScopes(c);
+    sayAdoption(c);
     sayCollisions(c);
     await sayBrokenRefs(c, root, scope);
 }
+/**
+ * OS ESCOPOS QUE VIRARAM UM SISTEMA, e o que cada um perdeu no empate.
+ *
+ * `--scope` aceita mais de um, e a ordem é uma declaração: o primeiro vence. Um
+ * token que os dois declaram diferente não é erro de ninguém - é divergência, e
+ * a lei do dono (§8.6) é que a plataforma não decide sozinha. Ela mostra os
+ * dois, diz quem é a fonte declarada, e propõe alinhar o outro lado.
+ *
+ * Medido no monorepo dele: `packages/ui` e `apps/web-dashboard/src` declaram os
+ * mesmos três `--gradient-gray-*` com valores opostos - claros na biblioteca,
+ * escuros no app. Nenhum dos dois está errado, e um deles ia desaparecer calado.
+ */
+function sayScopes(c) {
+    const scopes = c.scopes ?? [];
+    if (scopes.length < 2)
+        return;
+    const conflicts = c.scopeConflicts ?? [];
+    console.log("");
+    console.log(section("Two folders, one system"));
+    console.log(body(`Measured ${scopes.length} scopes and fused them: ${scopes.map((x, i) => (i === 0 ? paint.strong(x) : x)).join(" · ")}. The first one is the authority - it wins a tie, and nothing from the others is dropped without a line.`));
+    if (conflicts.length === 0)
+        return;
+    console.log("");
+    console.log(body(`${conflicts.length} token${conflicts.length === 1 ? "" : "s"} ${conflicts.length === 1 ? "is" : "are"} declared differently in two of them:`));
+    console.log("");
+    for (const x of conflicts.slice(0, 5)) {
+        console.log(body(`${paint.strong(x.name)}\n      ${paint.faint("kept")}  ${x.kept.value} ${paint.faint(`(${x.kept.scope})`)}\n      ${paint.faint("also")}  ${x.lost.value} ${paint.faint(`(${x.lost.scope})`)}`));
+    }
+    if (conflicts.length > 5)
+        console.log(body(paint.faint(`(${conflicts.length - 5} more)`)));
+    console.log("");
+    console.log(body(paint.faint("Neither value is wrong - one of them is a different scheme, or a fork that drifted. The system carries the first; the screen can show both.")));
+}
+/**
+ * QUANTO DA MIGRAÇÃO JÁ ACONTECEU - o número que faltava.
+ *
+ * O `intent` já dizia que alguém está migrando design para o pacote
+ * compartilhado (`init --intent migrate`, versionado em `_synthesisui/config.json`
+ * com a data). O que nenhuma superfície dizia é QUANTO já chegou. Medido no
+ * monorepo do dono: 103 de 356 arquivos do `web-dashboard` importam
+ * `@frontend-hub/ui`, e o `web-review` não o conhece.
+ *
+ * É a diferença entre medir estado e medir progresso: um relatório de estado é
+ * igual em janeiro e em junho; este muda a cada versão.
+ */
+function sayAdoption(c) {
+    const a = c.adoption;
+    if (!a || a.consumers.length === 0)
+        return;
+    const total = a.consumers.reduce((n, x) => n + x.files, 0);
+    const using = a.consumers.reduce((n, x) => n + x.using, 0);
+    console.log("");
+    console.log(section("How far the system already reaches"));
+    console.log(body(`${using} of ${total} source files across the folders you named import ${paint.strong(a.specifier)}. Everything else in them is still painting on its own.`));
+    console.log("");
+    for (const x of a.consumers) {
+        const pct = x.files > 0 ? Math.round((x.using / x.files) * 100) : 0;
+        console.log(body(`${paint.strong(x.label.padEnd(24))} ${String(x.using).padStart(4)} of ${String(x.files).padStart(4)} files ${paint.faint(`· ${pct}%`)}${x.using === 0 ? paint.faint("  - does not know the system yet") : ""}`));
+    }
+    console.log("");
+    console.log(body(paint.faint("This is the number a migration is measured by, and it is the one that moves. Run the import again after a batch and the difference is the progress.")));
+}
 /**
  * DOIS ARQUIVOS, UM NOME - dito, com os dois caminhos.
  *
@@ -2107,16 +2212,35 @@ function sayCollisions(c) {
     const all = c.collisions ?? [];
     if (all.length === 0)
         return;
+    /**
+     * DUAS REGRAS, DUAS FRASES. Dentro de um escopo vence quem está mais perto da
+     * raiz; entre escopos vence o primeiro `--scope`. Explicar um empate com a
+     * regra do outro é descrever algo que não aconteceu.
+     */
+    const crossScope = all.filter((x) => x.by === "scope");
+    const inScope = all.filter((x) => x.by !== "scope");
     const names = new Set(all.map((x) => x.name));
     console.log("");
-    console.log(section("Two files, one name"));
-    console.log(body(`${names.size} name${names.size === 1 ? "" : "s"} ${names.size === 1 ? "is" : "are"} defined more than once in what was measured, so ${all.length} definition${all.length === 1 ? "" : "s"} did not make it into this system. The one closest to the root of the scope kept the name - never the order the disk happened to return.`));
-    console.log("");
-    for (const x of all.slice(0, 6)) {
-        console.log(body(`${paint.strong(x.name)} ${paint.faint("kept")} ${x.kept}\n      ${paint.faint("dropped")} ${x.dropped}`));
+    console.log(section("Two places, one name"));
+    console.log(body(`${names.size} name${names.size === 1 ? "" : "s"} ${names.size === 1 ? "is" : "are"} defined more than once in what was measured, so ${all.length} definition${all.length === 1 ? "" : "s"} did not make it into this system.`));
+    if (crossScope.length > 0) {
+        console.log("");
+        console.log(body(`${crossScope.length} of them in two different scopes - the FIRST --scope kept the name:`));
+        console.log("");
+        for (const x of crossScope.slice(0, 6))
+            console.log(body(`${paint.strong(x.name.padEnd(22))} ${paint.faint("kept in")} ${x.kept}  ${paint.faint("· also in")} ${x.dropped}`));
+        if (crossScope.length > 6)
+            console.log(body(paint.faint(`(${crossScope.length - 6} more)`)));
+    }
+    if (inScope.length > 0) {
+        console.log("");
+        console.log(body(`${inScope.length} inside a single scope - the file closest to its root kept the name, never the order the disk happened to return:`));
+        console.log("");
+        for (const x of inScope.slice(0, 6))
+            console.log(body(`${paint.strong(x.name)}\n      ${paint.faint("kept")} ${x.kept}\n      ${paint.faint("dropped")} ${x.dropped}`));
+        if (inScope.length > 6)
+            console.log(body(paint.faint(`(${inScope.length - 6} more)`)));
     }
-    if (all.length > 6)
-        console.log(body(paint.faint(`(${all.length - 6} more)`)));
     console.log("");
     console.log(body(paint.faint("If the homonyms belong to different projects, a narrower --scope is the answer and nothing is lost. If they belong to the same one, renaming in your code is - two components with one name is one name your agent cannot resolve either.")));
 }
@@ -2474,8 +2598,21 @@ async function sayAboutPlace(root, scope) {
     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(body(
+    /**
+     * A FRASE SEGUE O CRITÉRIO, e o critério é estrutural.
+     *
+     * Enquanto a contagem incluía `dist`, dizer "o vocabulário não está aqui"
+     * fechava com os números: 764 contra 114. Com o build output fora, a
+     * biblioteca declara 97 e o APP declara 114 - a frase antiga passaria a
+     * contradizer os dois números que ela mesma imprime.
+     *
+     * O que faz `packages/ui` ser a fonte de verdade não é volume: é os outros
+     * pacotes o importarem. Dizer isso é dizer a razão verdadeira, e ela
+     * sobrevive ao caso em que o app declara mais.
+     */
+    `${paint.strong(vocab.rel)} is what the other ${vocab.importedBy} package${vocab.importedBy === 1 ? "" : "s"} here import${vocab.importedBy === 1 ? "s" : ""} - that is the shared vocabulary, ${vocab.declarations} token${vocab.declarations === 1 ? "" : "s"} across ${vocab.files} file${vocab.files === 1 ? "" : "s"}. This package declares ${mine?.declarations ?? 0} of its own across ${mine?.files ?? 0}, and those are this app's.`));
+    console.log(body(paint.faint("A system measured from the app is one consumer's set of choices; the shared vocabulary is where the library declares it.")));
     console.log("");
     console.log(body("The system is one place, and the evidence is another:"));
     console.log("");
@@ -3158,8 +3295,18 @@ export async function runImport(opts) {
         .trim()
         .replace(/^\.\/+/, "")
         .replace(/\/+$/, "");
-    const scope = opts.scope ? tidy(opts.scope) : undefined;
-    const readFrom = scope ? join(root, scope) : root;
+    /**
+     * OS ESCOPOS, na ordem em que a pessoa os escreveu - e `scope` é o primeiro.
+     *
+     * O parser de flags já acumula uma flag repetida (`--usage` usa isso desde
+     * 01/08), então `--scope packages/ui --scope packages/charts` chega aqui como
+     * array sem nenhuma mudança de gramática.
+     */
+    const scopes = (Array.isArray(opts.scope) ? opts.scope : opts.scope ? [opts.scope] : [])
+        .map(tidy)
+        .filter(Boolean)
+        .filter((v, i, all) => all.indexOf(v) === i);
+    const scope = scopes[0];
     /**
      * THE SECOND ROLE. `--scope` is the SYSTEM - one place, and the only source of
      * the palette, the scales and the convention. `--usage` is the EVIDENCE - as
@@ -3234,13 +3381,33 @@ export async function runImport(opts) {
          */
         phase(1, 3, "Measuring the repository");
         console.log(section("Reading your project"));
-        census = await takeCensus(readFrom, {
-            ...(usage.length > 0 ? { usage } : {}),
-            ...(scope ? { scopeLabel: scope } : {}),
-            ...(opts.cli ? { cli: opts.cli } : {}),
-        });
-        if (scope)
-            census.scope = scope;
+        /**
+         * UMA MEDIÇÃO POR ESCOPO, E DEPOIS A FUSÃO.
+         *
+         * `takeCensus` recebe UM `root` em cinco pontos estruturais que são por
+         * PACOTE e não por sistema (`harvestOwnCss`, `internalSpecifiers`,
+         * `publicApi`, o `walk`, `aliasesOf`), então ensiná-la a medir N raízes
+         * seria refatorar a função de 1855 linhas que o corpus dourado protege.
+         * Medir N vezes e fundir troca esse risco por uma função pura - e as regras
+         * de empate ficam num arquivo em vez de espalhadas por um laço.
+         *
+         * A EVIDÊNCIA VIAJA COM O PRIMEIRO: `--usage` doa contagem e lei, e somar a
+         * mesma evidência N vezes multiplicaria os números que decidem o que é
+         * hábito. Ela entra uma vez, na medição do escopo que declara.
+         */
+        const measured = [];
+        for (const [i, one] of (scopes.length > 0 ? scopes : [""]).entries()) {
+            const at = one ? join(root, one) : root;
+            const c = await takeCensus(at, {
+                ...(i === 0 && usage.length > 0 ? { usage } : {}),
+                ...(one ? { scopeLabel: one } : {}),
+                ...(opts.cli ? { cli: opts.cli } : {}),
+            });
+            if (one)
+                c.scope = one;
+            measured.push(c);
+        }
+        census = mergeCensus(measured);
     }
     /**
      * DERIVE THE ANATOMY ON THE MEASURING PATH TOO.
@@ -3270,8 +3437,30 @@ export async function runImport(opts) {
      * `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)
+    /**
+     * OS CANDIDATOS ENTRAM NO CENSO, e é o mesmo `placeInWorkspace` que a mensagem
+     * de lugar já usa - uma medição, dois consumidores.
+     *
+     * Vive aqui e não dentro de `takeCensus` porque a pergunta é sobre o
+     * WORKSPACE, e `takeCensus` mede um escopo: chamá-la de lá faria cada escopo
+     * medido recontar os mesmos cinco pacotes.
+     */
+    if (!opts.census) {
+        const place = await placeInWorkspace(root).catch(() => null);
+        if (place)
+            census.workspace = {
+                root: place.workspaceRoot,
+                here: place.here,
+                packages: place.packages.map((p) => ({
+                    rel: p.rel,
+                    name: p.name,
+                    declarations: p.declarations,
+                    files: p.files,
+                    importedBy: p.importedBy,
+                })),
+            };
         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/commands/mcp.js

@@ -1042,6 +1042,23 @@ async function describeComponent(root, name) {
     if ((recipe.companions ?? []).length > 0) {
         out.push("", `Goes with: ${(recipe.companions ?? []).join(", ")} - measured pairings; call describe_component on one before composing them together.`);
     }
+    /**
+     * ONDE ELE MORA, E COMO CHEGAR NELE - a linha que decide se o agente importa
+     * ou reescreve.
+     *
+     * `api.from` é o especificador do pacote que o EXPORTA (a lei 13 já o mediu), e
+     * ele só existe para um componente de biblioteca. Quando há um, importar é a
+     * resposta e escrever de novo é duplicar. Quando não há, o caminho é o que
+     * localiza o arquivo - e num sistema de dois escopos ele é a única coisa que
+     * diz de qual dos dois este componente é.
+     */
+    if (recipe.source?.file || recipe.api?.from) {
+        const where = recipe.source?.file;
+        const pkg = recipe.api?.from;
+        out.push("", pkg
+            ? `Lives in: ${where ?? pkg} - exported by ${pkg}. Import it from there; writing it again duplicates a component this system already owns.`
+            : `Lives in: ${where}${recipe.source?.scope ? ` (scope ${recipe.source.scope})` : ""} - local to that folder, and not exported by a package.`);
+    }
     if (recipe.usageStats && recipe.usageStats.count > 0) {
         const u = recipe.usageStats;
         out.push("", `In use: ${u.count} instance${u.count === 1 ? "" : "s"} across ${u.files} file${u.files === 1 ? "" : "s"}${u.projects?.length ? ` in ${u.projects.join(", ")}` : ""}.`);

package/dist/commands/sync.js

@@ -6,10 +6,11 @@ import { markSent, readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { describeDelta, fingerprintReadings, readSyncMark, writeSyncMark, } from "../last-sync.js";
 import { measuredScope, rememberScope } from "../measured-scope.js";
+import { mergeCensus } from "../merge-census.js";
 import { body, paint, section, snippet } from "../output.js";
 import { repoStateOf } from "../repo-state.js";
 import { reportWhatIsLeft } from "./align.js";
-import { resolveReadParts, siblingProjects, takeCensus } from "./import.js";
+import { resolveReadParts, siblingProjects, takeCensus, } from "./import.js";
 /**
  * What each decision means ON THIS MACHINE - the card decides, the sync
  * enacts. The web never touches the local file; this line is printed right
@@ -247,7 +248,25 @@ export async function remeasure(args) {
      * O servidor continua valendo como segunda fonte: um clone fresco tem o `.lock` e não tem censo.
      */
     const local = await measuredScope(root);
-    let scope = local.system ?? stored.scope ?? null;
+    /**
+     * TODOS os escopos do sistema, não só o primeiro.
+     *
+     * Esta linha lia `local.system` - singular - e um sistema importado de dois
+     * escopos remedia só um deles: 351 componentes nasciam e 36 eram remedidos. Os
+     * outros 315 não eram apagados (`presenceOf` os conta como fora do escopo
+     * medido, de propósito) e também nunca mais eram atualizados - uma feature que
+     * emudece no dia seguinte.
+     *
+     * A queda para `scope` mantém todo sistema anterior lendo como antes.
+     */
+    let scopes = local.systems.length > 0
+        ? local.systems
+        : local.system
+            ? [local.system]
+            : stored.scope
+                ? [stored.scope]
+                : [];
+    let scope = scopes[0] ?? null;
     let usage = local.usage.length > 0 ? local.usage : (stored.usage ?? []);
     /**
      * E QUANDO NINGUÉM SABE, ESTE COMANDO PERGUNTA - uma vez, e grava a resposta.
@@ -263,26 +282,43 @@ export async function remeasure(args) {
         const asked = await askForScope(root);
         if (asked) {
             scope = asked.scope;
+            scopes = [asked.scope];
             if (asked.usage.length > 0)
                 usage = asked.usage;
-            await rememberScope(root, slug, scope, usage);
+            await rememberScope(root, slug, scopes, usage);
         }
     }
     console.log(section("Measuring your repository again"));
-    console.log(body(paint.faint(`${scope ? `reading ${scope}` : "the whole repo"}${local.system && local.system !== stored.scope
+    console.log(body(paint.faint(`${scopes.length > 1 ? `reading ${scopes.join(" + ")}` : scope ? `reading ${scope}` : "the whole repo"}${local.system && local.system !== stored.scope
         ? " · read from _synthesisui/census.json, where the last measurement recorded it"
         : ""} · what you already wrote about your app travels unchanged`)));
-    const census = await takeCensus(scope ? join(root, scope) : root, {
-        ...(scope ? { scopeLabel: scope } : {}),
-        ...(args.cli ? { cli: args.cli } : {}),
-        /** Uma RE-medição conta o que MUDOU; o relatório inteiro fica no `--full` - ver `say`. */
-        ...(args.full ? {} : { quiet: true }),
-        /** O `--usage` é EVIDÊNCIA e leva rótulo: sem ele o censo não sabe de que app o número veio. */
-        usage: usage.map((u) => ({
-            path: join(root, u),
-            label: u,
-        })),
-    }).catch(() => null);
+    /**
+     * UMA MEDIÇÃO POR ESCOPO, FUNDIDAS - o mesmo desenho do `import`.
+     *
+     * `takeCensus` recebe um `root` em cinco pontos que são por PACOTE, então medir
+     * N raízes de dentro dela seria refatorar a função que o corpus dourado guarda.
+     * A evidência (`--usage`) entra UMA vez, com o primeiro escopo: somá-la N vezes
+     * multiplicaria as contagens que decidem o que é hábito.
+     */
+    const measuredList = [];
+    for (const [i, one] of (scopes.length > 0 ? scopes : [""]).entries()) {
+        const c = await takeCensus(one ? join(root, one) : root, {
+            ...(one ? { scopeLabel: one } : {}),
+            ...(args.cli ? { cli: args.cli } : {}),
+            /** Uma RE-medição conta o que MUDOU; o relatório inteiro fica no `--full` - ver `say`. */
+            ...(args.full ? {} : { quiet: true }),
+            /** O `--usage` é EVIDÊNCIA e leva rótulo: sem ele o censo não sabe de que app o número veio. */
+            usage: i === 0 ? usage.map((u) => ({ path: join(root, u), label: u })) : [],
+        }).catch(() => null);
+        if (!c)
+            break;
+        if (one)
+            c.scope = one;
+        measuredList.push(c);
+    }
+    const census = measuredList.length === (scopes.length > 0 ? scopes.length : 1)
+        ? mergeCensus(measuredList)
+        : null;
     if (!census) {
         console.log(body("The measurement failed, so nothing was sent."));
         return;

package/dist/index.js

@@ -89,7 +89,8 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
-  --scope <path>     import: the SYSTEM - tokens, components, convention. One folder.
+  --scope <path>     import: the SYSTEM - tokens, components, convention. Repeatable;
+                     the first one wins a tie.
   --usage <path>     import: the EVIDENCE - counts, chosen values, laws. Repeatable.
   --scheme <s>       dark|light - which end of your ladder is the default
   --target <t>       template/init target: next | general (default: next)
@@ -160,7 +161,16 @@ async function main() {
                 // Only these two words. Anything else is a typo that would silently
                 // invert a system, so it falls through to being measured and asked.
                 // WHAT to read. `--dir` stays WHERE the project is, in every command.
-                scope: typeof flags.scope === "string" ? flags.scope : undefined,
+                /**
+                 * `--scope` REPETÍVEL: um sistema pode viver em dois pacotes, e o parser
+                 * já acumula flag repetida (`--usage` usa isso). A ordem é a que a pessoa
+                 * escreveu, e ela decide os empates - ver `merge-census.ts`.
+                 */
+                scope: Array.isArray(flags.scope)
+                    ? flags.scope
+                    : typeof flags.scope === "string"
+                        ? flags.scope
+                        : undefined,
                 // WHERE THE EVIDENCE IS. Repeatable, and comma-separated works too - a
                 // person typing one path with a comma in it means two paths.
                 usage: [flags.usage]

package/dist/install-marks.js

@@ -100,7 +100,7 @@
  *
  * Quem instalou antes desta versão tem o stub que estanca: o `upgrade`/`connect` é o que alcança.
  */
-export const MATERIALISER_SINCE = "0.16.241";
+export const MATERIALISER_SINCE = "0.16.255";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/measured-scope.js

@@ -1,6 +1,11 @@
 import { readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-const EMPTY = { system: null, usage: [], from: "none" };
+const EMPTY = {
+    system: null,
+    systems: [],
+    usage: [],
+    from: "none",
+};
 /**
  * O ESCOPO NO PONTEIRO DO SISTEMA, que é onde ele não se perde.
  *
@@ -27,22 +32,42 @@ async function scopeInLock(root) {
         catch {
             continue;
         }
-        const scope = typeof lock.scope === "string" && lock.scope.trim()
-            ? lock.scope.trim()
-            : null;
+        /**
+         * `scopes` PRIMEIRO, `scope` como queda - e nunca o contrário.
+         *
+         * Um lock escrito antes desta versão só tem `scope`, e ele continua sendo lido
+         * exatamente como antes. Um lock novo tem os dois, e a lista é a verdade
+         * completa: ler o singular ali daria um sistema de um escopo onde há dois.
+         */
+        const listed = Array.isArray(lock.scopes)
+            ? lock.scopes.filter((x) => typeof x === "string" && !!x.trim())
+            : [];
+        const scope = listed[0] ??
+            (typeof lock.scope === "string" && lock.scope.trim()
+                ? lock.scope.trim()
+                : null);
+        const declared = listed.length > 0 ? listed : scope ? [scope] : [];
         const usage = Array.isArray(lock.usage)
             ? lock.usage.filter((u) => typeof u === "string" && !!u.trim())
             : [];
-        if (!scope && usage.length === 0)
+        if (declared.length === 0 && usage.length === 0)
             continue;
-        const system = scope && (await present(root, scope)) ? scope : null;
+        const systems = [];
+        for (const d of declared)
+            if (await present(root, d))
+                systems.push(d);
         const kept = [];
         for (const u of usage)
             if (await present(root, u))
                 kept.push(u);
-        if (!system && kept.length === 0)
+        if (systems.length === 0 && kept.length === 0)
             continue;
-        return { system, usage: kept, from: "lock" };
+        return {
+            system: systems[0] ?? null,
+            systems,
+            usage: kept,
+            from: "lock",
+        };
     }
     return null;
 }
@@ -81,20 +106,29 @@ export async function censusScope(root) {
     catch {
         return EMPTY;
     }
-    const scope = typeof parsed.scope === "string" && parsed.scope.trim()
-        ? parsed.scope.trim()
-        : null;
+    /** `scopes` primeiro, `scope` como queda - ver `scopeInLock`, mesma regra. */
+    const listed = Array.isArray(parsed.scopes)
+        ? parsed.scopes.filter((x) => typeof x === "string" && !!x.trim())
+        : [];
+    const scope = listed[0] ??
+        (typeof parsed.scope === "string" && parsed.scope.trim()
+            ? parsed.scope.trim()
+            : null);
+    const declared = listed.length > 0 ? listed : scope ? [scope] : [];
     const usage = Array.isArray(parsed.usage)
         ? parsed.usage.filter((u) => typeof u === "string" && !!u.trim())
         : [];
-    const system = scope && (await present(root, scope)) ? scope : null;
+    const systems = [];
+    for (const d of declared)
+        if (await present(root, d))
+            systems.push(d);
     const kept = [];
     for (const u of usage)
         if (await present(root, u))
             kept.push(u);
-    if (!system && kept.length === 0)
+    if (systems.length === 0 && kept.length === 0)
         return EMPTY;
-    return { system, usage: kept, from: "census" };
+    return { system: systems[0] ?? null, systems, usage: kept, from: "census" };
 }
 /**
  * As pastas a LER, na ordem em que importam - o sistema primeiro.
@@ -103,7 +137,12 @@ export async function censusScope(root) {
  * anotações no CI, decide o que chega ao PR.
  */
 export function scopePaths(m) {
-    return [...(m.system ? [m.system] : []), ...m.usage];
+    /**
+     * TODOS os sistemas, não só o primeiro - senão `absorb` e `summary` veem meia
+     * biblioteca num sistema importado de dois escopos.
+     */
+    const systems = m.systems.length > 0 ? m.systems : m.system ? [m.system] : [];
+    return [...systems, ...m.usage];
 }
 /** Como dizer o que foi lido. Uma leitura que não declara o universo é um número sem denominador. */
 export function describeScope(m) {
@@ -131,7 +170,18 @@ export function describeScope(m) {
  *
  * Silencioso quando não há lock: não é erro, é um repo sem sistema instalado.
  */
-export async function rememberScope(root, slug, scope, usage) {
+export async function rememberScope(root, slug, 
+/**
+ * OS ESCOPOS, na ordem em que a pessoa os pediu - o primeiro é a autoridade.
+ *
+ * Aceita a lista e grava OS DOIS campos: `scopes` com tudo e `scope` com o
+ * primeiro. Um CLI anterior lê `scope` e continua funcionando; um lock antigo
+ * lido por este CLI cai no singular. É a compatibilidade nos dois sentidos, e
+ * ela custa uma linha.
+ */
+scopes, usage) {
+    const list = (Array.isArray(scopes) ? scopes : scopes ? [scopes] : []).filter(Boolean);
+    const scope = list[0] ?? null;
     const path = join(root, "_synthesisui", "ds", slug, ".lock");
     const raw = await readFile(path, "utf8").catch(() => null);
     if (!raw)
@@ -146,6 +196,7 @@ export async function rememberScope(root, slug, scope, usage) {
     await writeFile(path, `${JSON.stringify({
         ...lock,
         ...(scope ? { scope } : {}),
+        ...(list.length > 0 ? { scopes: list } : {}),
         ...(usage.length > 0 ? { usage } : {}),
     }, null, 2)}\n`, "utf8");
 }

package/dist/merge-census.js

@@ -0,0 +1,231 @@
+const asRecord = (v) => (v ?? {});
+/** Nome do escopo para as mensagens - `.` quando a medição não escopou nada. */
+const nameOf = (c, i) => c.scope ?? (i === 0 ? "." : `#${i + 1}`);
+/**
+ * OS TOKENS, com o primeiro escopo mandando - e o conflito registrado.
+ *
+ * `declared` é o coração: é dele que saem os nomes que viajam para a tela. Um
+ * `--brand-500` que vale `#1394dc` na biblioteca e `#0f6fa8` no pacote de
+ * gráficos não é um erro de ninguém, é uma divergência - e a lei do dono
+ * (§8.6) é que a plataforma não decide sozinha: ela mostra os dois e diz quem é
+ * a fonte declarada.
+ */
+function mergeDeclared(into, from, keptScope, fromScope, conflicts) {
+    for (const [name, value] of Object.entries(from)) {
+        const held = into[name];
+        if (held === undefined) {
+            into[name] = value;
+            continue;
+        }
+        if (held === value)
+            continue;
+        conflicts.push({
+            kind: "token",
+            name,
+            kept: { scope: keptScope, value: held },
+            lost: { scope: fromScope, value },
+        });
+    }
+}
+/** Os valores medidos, somados por (natureza, valor) - e o nome vem de quem o tem. */
+function mergeObserved(a, b) {
+    const out = a.map((v) => ({ ...v }));
+    const at = new Map(out.map((v, i) => [`${v.kind}:${v.value}`, i]));
+    for (const v of b) {
+        const key = `${v.kind}:${v.value}`;
+        const i = at.get(key);
+        if (i === undefined) {
+            at.set(key, out.length);
+            out.push({ ...v });
+            continue;
+        }
+        out[i].count += v.count;
+        out[i].files += v.files;
+        /** Um nome não se apaga por o outro escopo não ter um. */
+        if (!out[i].token && v.token)
+            out[i].token = v.token;
+    }
+    return out.sort((x, y) => y.count - x.count);
+}
+/** União preservando a ordem de chegada - a do primeiro escopo primeiro. */
+const union = (a, b) => [
+    ...new Set([...(a ?? []), ...(b ?? [])]),
+];
+const concat = (a, b) => [
+    ...(a ?? []),
+    ...(b ?? []),
+];
+/** Soma campo a campo dois objetos de contagem, mantendo o que só um tem. */
+function sumInto(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b)) {
+        const mine = out[k];
+        if (typeof v === "number" && typeof mine === "number")
+            out[k] = mine + v;
+        else if (mine === undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * OS CENSOS, FUNDIDOS NA ORDEM EM QUE A PESSOA OS PEDIU.
+ *
+ * Devolve o próprio objeto quando há um só: o caminho comum - um escopo - não
+ * paga nada por esta função existir.
+ */
+export function mergeCensus(list) {
+    if (list.length === 0)
+        throw new Error("mergeCensus needs at least one census");
+    if (list.length === 1)
+        return list[0];
+    const first = list[0];
+    const conflicts = [];
+    const collisions = [
+        ...(first.collisions ?? []),
+    ];
+    const declared = { ...asRecord(first.declared) };
+    const declaredAlt = { ...asRecord(first.declaredAlt) };
+    const keyframes = { ...(first.keyframes ?? {}) };
+    const looks = { ...(first.looks ?? {}) };
+    let observed = first.observed.map((v) => ({ ...v }));
+    let totals = { ...first.totals };
+    let coverage = first.coverage;
+    let gate = first.gate;
+    let reachability = first.reachability;
+    let usage = first.usage ?? undefined;
+    let animations = first.animations ?? undefined;
+    let skipped = first.skipped ?? undefined;
+    let brokenRefs = first.brokenRefs ?? undefined;
+    let conventions = first.conventions ?? undefined;
+    let architectures = first.architectures ?? undefined;
+    let components = first.components ?? undefined;
+    let defined = first.defined ?? undefined;
+    const stack = [...(first.project.stack ?? [])];
+    for (let i = 1; i < list.length; i++) {
+        const c = list[i];
+        const scopeName = nameOf(c, i);
+        const firstName = nameOf(first, 0);
+        mergeDeclared(declared, asRecord(c.declared), firstName, scopeName, conflicts);
+        mergeDeclared(declaredAlt, asRecord(c.declaredAlt), firstName, scopeName, conflicts);
+        /**
+         * O COMPONENTE QUE OS DOIS DEFINEM fica com a receita do primeiro escopo, e
+         * o descarte entra em `collisions` - a mesma lista que `name-claim.ts`
+         * alimenta dentro de UM escopo. Uma lista, dois níveis: o arquivo e o
+         * pacote, e a tela não precisa saber a diferença para dizer a verdade.
+         */
+        for (const [name, look] of Object.entries(c.looks ?? {})) {
+            if (looks[name] === undefined) {
+                looks[name] = look;
+                continue;
+            }
+            /** `by` diz que este empate foi resolvido pela ORDEM DOS ESCOPOS. */
+            collisions.push({
+                name,
+                kept: firstName,
+                dropped: scopeName,
+                by: "scope",
+            });
+        }
+        for (const [name, frames] of Object.entries(c.keyframes ?? {}))
+            if (keyframes[name] === undefined)
+                keyframes[name] = frames;
+        observed = mergeObserved(observed, c.observed);
+        totals = {
+            scanned: totals.scanned + c.totals.scanned,
+            values: totals.values + c.totals.values,
+            named: totals.named + c.totals.named,
+            tokenUses: totals.tokenUses + c.totals.tokenUses,
+            ownUses: (totals.ownUses ?? 0) + (c.totals.ownUses ?? 0),
+            phantomUses: (totals.phantomUses ?? 0) + (c.totals.phantomUses ?? 0),
+            /** Recalculado abaixo - somar percentuais não significa nada. */
+            coverage: 0,
+        };
+        coverage = sumInto(coverage, c.coverage);
+        gate = sumInto(gate, c.gate);
+        reachability = sumInto(reachability, c.reachability);
+        usage = union(usage, c.usage);
+        animations = union(animations, c.animations);
+        skipped = concat(skipped, c.skipped);
+        brokenRefs = concat(brokenRefs, c.brokenRefs);
+        conventions = concat(conventions, c.conventions);
+        architectures = concat(architectures, c.architectures);
+        components = concat(components, c.components);
+        defined = concat(defined, c.defined);
+        for (const s of c.project.stack ?? [])
+            if (!stack.includes(s))
+                stack.push(s);
+    }
+    /**
+     * A COBERTURA, RECALCULADA COM A FÓRMULA DE VERDADE.
+     *
+     * `(tokenUses + ownUses) / (tokenUses + ownUses + values + phantomUses)` - a
+     * mesma de `doctor/scan.ts:796`. A primeira versão desta função usou
+     * `named/values`, que parece razoável e não é a fórmula: fundir 48% e 30%
+     * devolvia 10% no monorepo do dono. Um número que não descreve nenhuma das
+     * medições é pior que não ter o número.
+     *
+     * Quando os censos vêm de um CLI que não gravava `ownUses`, a soma perde esses
+     * termos e o resultado seria menor que a verdade - então neste caso a
+     * cobertura do PRIMEIRO escopo é preservada, que é uma medição real de uma
+     * parte real, em vez de uma conta feita com metade dos termos.
+     */
+    const named = totals.tokenUses + (totals.ownUses ?? 0);
+    const denominator = named + totals.values + (totals.phantomUses ?? 0);
+    const complete = list.every((c) => c.totals.ownUses !== undefined);
+    totals.coverage = !complete
+        ? first.totals.coverage
+        : denominator > 0
+            ? Math.round((named / denominator) * 100)
+            : 100;
+    const out = {
+        ...first,
+        project: { ...first.project, stack },
+        /**
+         * `scope` SEGUE SENDO O PRIMEIRO, e não uma lista, porque há quem compare por
+         * igualdade: `live-census.ts:44` faz `census.scope === LIBRARY_SCOPE`, e um
+         * array ali seria um falso silencioso. `scopes` é aditivo - quem não sabe
+         * dele continua lendo o censo como antes.
+         */
+        scopes: list.map((c, i) => nameOf(c, i)),
+        declared,
+        observed,
+        totals,
+    };
+    if (Object.keys(declaredAlt).length > 0)
+        out.declaredAlt = declaredAlt;
+    if (Object.keys(keyframes).length > 0)
+        out.keyframes = keyframes;
+    if (Object.keys(looks).length > 0)
+        out.looks = looks;
+    if (coverage)
+        out.coverage = coverage;
+    if (gate)
+        out.gate = gate;
+    if (reachability)
+        out.reachability = reachability;
+    if (usage && usage.length > 0)
+        out.usage = usage;
+    if (animations && animations.length > 0)
+        out.animations = animations;
+    if (skipped && skipped.length > 0)
+        out.skipped = skipped;
+    if (brokenRefs && brokenRefs.length > 0)
+        out.brokenRefs = brokenRefs;
+    if (conventions && conventions.length > 0)
+        out.conventions = conventions;
+    if (architectures && architectures.length > 0)
+        out.architectures = architectures;
+    if (components && components.length > 0)
+        out.components = components;
+    if (defined && defined.length > 0)
+        out.defined = defined;
+    if (collisions.length > 0)
+        out.collisions = collisions;
+    if (conflicts.length > 0)
+        out.scopeConflicts = conflicts;
+    return out;
+}

package/dist/name-claim.js

@@ -62,10 +62,10 @@ export function claimName(claims, name, file) {
     const incumbentWins = depth(held) < depth(file) ||
         (depth(held) === depth(file) && held.localeCompare(file) <= 0);
     if (incumbentWins) {
-        claims.collisions.push({ name, kept: held, dropped: file });
+        claims.collisions.push({ name, kept: held, dropped: file, by: "path" });
         return false;
     }
     claims.by.set(name, file);
-    claims.collisions.push({ name, kept: file, dropped: held });
+    claims.collisions.push({ name, kept: file, dropped: held, by: "path" });
     return true;
 }

package/dist/workspace-place.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
+import { SKIP } from "./commands/doctor.js";
 const MANIFEST = "package.json";
 const SHEET = /\.(css|scss|sass|less)$/i;
 const DECL = /(^|[\s{;])--[a-zA-Z0-9-]+\s*:/g;
@@ -28,9 +29,11 @@ function workspaceGlobs(p) {
  * 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.
+ * A LISTA DE PASTAS IGNORADAS É A DO `walk`, importada e não reescrita. A primeira
+ * versão pulava dotdir e `node_modules` por conta própria e somava
+ * `packages/ui/dist/index.css`: 496 declarações de bundle contra 97 de fonte no
+ * repo do dono (19/08). O número que escolhia a pasta recomendada era cinco
+ * sextos build output, e o censo - que usa o SKIP - nunca leu nada daquilo.
  */
 async function weigh(dir) {
     let declarations = 0;
@@ -39,7 +42,7 @@ async function weigh(dir) {
         if (depth > 8)
             return;
         for (const e of await readdir(at, { withFileTypes: true }).catch(() => [])) {
-            if (e.name.startsWith(".") || e.name === "node_modules")
+            if (e.name.startsWith(".") || SKIP.has(e.name))
                 continue;
             const full = join(at, e.name);
             if (e.isDirectory()) {
@@ -125,16 +128,29 @@ export async function placeInWorkspace(root) {
             declarations,
             files,
             dependsOn: Object.keys(deps).filter((k) => local.has(k)),
+            /** Preenchido no passo seguinte, quando todos os `dependsOn` existem. */
+            importedBy: 0,
         });
     }
+    for (const pkg of packages) {
+        if (!pkg.name)
+            continue;
+        pkg.importedBy = packages.filter((other) => other !== pkg && other.dependsOn.includes(pkg.name)).length;
+    }
     if (packages.length === 0)
         return null;
     const rel = relative(workspaceRoot, root).split("\\").join("/");
-    const ranked = [...packages].sort((a, b) => b.declarations - a.declarations);
+    /**
+     * A ORDEM: quem os outros importam vem primeiro, e a contagem só desempata.
+     * Um pacote que ninguém importa e que declara muito é um consumidor com
+     * vocabulário próprio - é um candidato legítimo, e não é a biblioteca.
+     */
+    const ranked = [...packages].sort((a, b) => b.importedBy - a.importedBy || b.declarations - a.declarations);
+    const lead = ranked[0];
     return {
         workspaceRoot,
         here: rel === "" ? null : rel,
         packages,
-        vocabulary: ranked[0]?.declarations > 0 ? ranked[0] : null,
+        vocabulary: lead && (lead.declarations > 0 || lead.importedBy > 0) ? lead : null,
     };
 }

package/package.json

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