synthesisui 0.16.252 → 0.16.253

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 { 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 +395,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 +603,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);
@@ -1880,6 +1906,14 @@ 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 } : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
         classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
@@ -2055,8 +2089,37 @@ async function summarize(c, root, scope) {
         }
     }
     sayConventions(c);
+    sayCollisions(c);
     await sayBrokenRefs(c, root, scope);
 }
+/**
+ * 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;
+    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}`));
+    }
+    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.")));
+}
 /**
  * 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".

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 });
+        return false;
+    }
+    claims.by.set(name, file);
+    claims.collisions.push({ name, kept: file, dropped: held });
+    return true;
+}

package/package.json

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