synthesisui 0.16.252 → 0.16.254

package/dist/commands/import.js

@@ -35,6 +35,8 @@ 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";
 import { detectStack, resolveDeps, stackVersions } from "../stack.js";
@@ -394,6 +396,16 @@ export async function takeCensus(root, opts) {
     const internal = await internalSpecifiers(root);
     const defined = [];
     /** Nome → arquivo e fonte, para toda leitura por componente - ver o preenchimento abaixo. */
+    /**
+     * QUEM DETÉM CADA NOME - e o registro de quem pediu o mesmo.
+     *
+     * Os oito mapas deste laço são indexados por nome de componente, então dois
+     * `Card.tsx` disputam a mesma chave e o último do `walk` sobrescrevia os
+     * outros em silêncio. Medido no repo do dono: 20 nomes colidem no repo
+     * inteiro, 14 dentro de um app, e um dos quatro `Card` é o do design system
+     * dele. Ver `name-claim.ts` para o desempate e por que ele é por estrutura.
+     */
+    const claims = { by: new Map(), collisions: [] };
     const sourceOf = new Map();
     /** Nome → o que a peça é, quando o portão soube dizer. Ver `CensusLook.kind`. */
     const kindOf = new Map();
@@ -592,6 +604,21 @@ export async function takeCensus(root, opts) {
                     because: verdict.because,
                 });
             }
+            /**
+             * O NOME É DISPUTADO AQUI, ANTES DE QUALQUER ESCRITA.
+             *
+             * Filtrar `found` fecha a porta de uma vez: os oito mapas deste laço
+             * derivam dele, então um componente que não detém o nome simplesmente não
+             * chega a nenhum deles - em vez de oito guardas que alguém esquece de
+             * repetir na nona escrita.
+             *
+             * O descarte NÃO é silencioso: `claims.collisions` guarda os dois caminhos
+             * e o censo os carrega. Trazer as duas receitas exige o contexto viajando
+             * na chave, que é a fatia dos grupos.
+             */
+            const claimed = found.filter((d) => claimName(claims, d.name, rel));
+            found.length = 0;
+            found.push(...claimed);
             for (const d of found) {
                 const props = readDefinitionProps(d.name, src);
                 propsOf.set(d.name, props);
@@ -1121,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)) {
@@ -1880,6 +1933,26 @@ export async function takeCensus(root, opts) {
         ...(Object.keys(keyframes).length > 0 ? { keyframes } : {}),
         ...(animations.size > 0 ? { animations: [...animations].sort() } : {}),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
+        /**
+         * OS NOMES DISPUTADOS - ver `name-claim.ts`.
+         *
+         * Aditivo e omitido quando vazio, que é o caso de toda biblioteca sã: no repo
+         * do dono, `packages/ui` produz zero e o repo inteiro produz 20. Um campo que
+         * 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 } : {}),
@@ -1995,6 +2068,8 @@ export async function takeCensus(root, opts) {
             named: d.named,
             tokenUses: d.tokenUses,
             coverage: d.coverage,
+            ownUses: d.ownUses,
+            phantomUses: d.phantomUses,
         },
     };
 }
@@ -2055,8 +2130,120 @@ 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.
+ *
+ * O silêncio aqui era o pior tipo: a pessoa recebe 36 componentes onde o repo
+ * tem 39, e nada no relatório sugere que três existiram. Medido no monorepo do
+ * dono: 20 nomes no repo inteiro, e um dos quatro `Card.tsx` é o do design system
+ * dele competindo com dois que vivem sob rotas.
+ *
+ * A frase diz o que fazer, e são duas coisas diferentes: um escopo mais estreito
+ * quando os homônimos são de outro projeto, ou um rename quando são do mesmo.
+ */
+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 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)`)));
+    }
+    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.")));
+}
 /**
  * THEIR VOCABULARY, MEASURED. This section exists so every later finding can be
  * phrased as "you already do X, and here you did not" instead of "adopt ours".
@@ -3095,8 +3282,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
@@ -3171,13 +3368,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.

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/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

@@ -0,0 +1,71 @@
+/**
+ * UM NOME, UM COMPONENTE - e o que fazer quando dois pedem o mesmo.
+ *
+ * O laço de leitura do import escreve em oito mapas indexados por NOME de
+ * componente (`looks`, `sourceOf`, `kindOf`, `propsOf`, `runtimeOf`,
+ * `variantAxes`, `islands`, `keyframes`). Dois `Card.tsx` em pastas diferentes
+ * disputam a mesma chave, e até aqui o último que o `walk` visitou sobrescrevia
+ * os outros - em silêncio, e por uma ordem que é do sistema de arquivos e não
+ * uma decisão de ninguém.
+ *
+ * Medido no monorepo do dono (19/08): 20 nomes colidem no repo inteiro, 14 dentro
+ * de `apps/web-dashboard/src`, e quatro arquivos se chamam `Card.tsx` - um deles
+ * é o `Card` do design system dele, e dois estão sob `_legacy`. `packages/ui`
+ * sozinho não tem colisão nenhuma: o problema mora em escopo largo, que é
+ * exatamente o default que a flexibilidade pede.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O DESEMPATE É POR ESTRUTURA, E DETERMINÍSTICO
+ *
+ * A intuição primeira era "quem o pacote EXPORTA fica com o nome", e ela não
+ * responde: `publicApi().exports` é um conjunto de NOMES, e os dois candidatos
+ * têm o mesmo nome. Escolher pelo que o pacote realmente publica exige o grafo a
+ * partir da entrada do manifesto, e essa é a fatia que também entrega os grupos.
+ *
+ * Então: menos segmentos de caminho vence, e empate resolve alfabeticamente. É
+ * pouco, e é honesto - a diferença que importa é que a resposta deixa de mudar
+ * conforme a ordem em que o disco devolve os arquivos.
+ *
+ * E NUNCA POR NOME DE PASTA. Descartar `_legacy` por se chamar `_legacy` é a lei
+ * 14 sendo furada: no repo dele `_legacy` tem 178 arquivos e 106 estão VIVOS,
+ * montados por rota (medido 07/08). Classificação é por estrutura, nunca por nome.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O PERDEDOR NÃO ENTRA, E ISSO É DITO
+ *
+ * Esta fatia não traz as duas receitas - trazer os dois `Card` exige o contexto
+ * viajando na chave, que é a fatia dos GRUPOS. O que ela conserta é a perda
+ * calada: cada descarte vira uma linha do censo com os dois caminhos, e o
+ * relatório os imprime. Uma lacuna declarada é confiança; calada é bug.
+ */
+/** Profundidade como o caminho a declara - o número de pastas até o arquivo. */
+const depth = (file) => file.split("/").length;
+/**
+ * ESTE ARQUIVO FICA COM ESTE NOME?
+ *
+ * `true` quando ele detém o nome depois desta chamada - e aí quem chamou pode
+ * escrever nos mapas. `false` quando outro arquivo o detém, e a disputa foi
+ * registrada em `collisions`.
+ *
+ * Idempotente para o mesmo arquivo: o laço lê um arquivo uma vez, mas um
+ * componente pode ser reivindicado por mais de um caminho de código, e cobrar
+ * uma colisão de um arquivo contra si mesmo seria inventar um conflito.
+ */
+export function claimName(claims, name, file) {
+    const held = claims.by.get(name);
+    if (held === undefined) {
+        claims.by.set(name, file);
+        return true;
+    }
+    if (held === file)
+        return true;
+    const incumbentWins = depth(held) < depth(file) ||
+        (depth(held) === depth(file) && held.localeCompare(file) <= 0);
+    if (incumbentWins) {
+        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, by: "path" });
+    return true;
+}

package/package.json

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