synthesisui 0.16.255 → 0.16.257

package/dist/claude-md.js

@@ -24,6 +24,7 @@ async function readInstalled(projectRoot) {
                 name: lock.name,
                 version: lock.version,
                 adopted: lock.adopted === true,
+                ...(lock.reference ? { reference: lock.reference } : {}),
             });
         }
         catch {
@@ -310,6 +311,25 @@ async function renderRegion(projectRoot, installed) {
     // writes a line. An INSTALLED system speaks `--ds-*` and is scoped with
     // `data-ds`; an ADOPTED one is the project's own vocabulary, already wired,
     // with no `data-ds` anywhere to scope to.
+    /**
+     * QUANDO ESTE REPO CARREGA MAIS DE UM SISTEMA, o agente precisa saber qual
+     * manda - e é a única coisa que ele não consegue deduzir lendo os dois.
+     *
+     * O `loadSystem` sempre leu todos os sistemas instalados lado a lado, porque
+     * cada token é prefixado `--ds-` e é isso que o app rodando vê. O que faltava
+     * era a relação: um deles é a referência para onde os outros convergem, ou eles
+     * são independentes. Sem esta frase, um agente diante de dois vocabulários
+     * escolhe por proximidade no arquivo, que é o mesmo que escolher no par ou
+     * ímpar.
+     *
+     * "Independentes" NÃO é dito: a ausência é o caso comum, e uma linha em todo
+     * repo de um sistema só para negar uma relação que ninguém cogitou é ruído no
+     * arquivo mais lido do projeto.
+     */
+    const ref = installed.find((d) => d.reference)?.reference;
+    if (installed.length > 1 && ref) {
+        sections.push(`\n**${ref.name}** (\`${ref.slug}\`) is the reference system of this group. When two of the systems above name the same thing differently, its answer is the one to follow - the others are moving towards it.`);
+    }
     const onlyAdopted = installed.every((d) => d.adopted);
     const selfCheck = (await hasHook(projectRoot))
         ? SELF_CHECK_HOOKED

package/dist/commands/add.js

@@ -192,6 +192,18 @@ export async function add(slug, opts) {
         ...(scope ? { scope } : {}),
         ...(systems.length > 0 ? { scopes: systems } : {}),
         ...(usage.length > 0 ? { usage } : {}),
+        /**
+         * A RELAÇÃO ENTRE OS SISTEMAS DESTE REPO, vinda da plataforma.
+         *
+         * Preservada quando o registry não a manda: um servidor mais antigo não sabe
+         * do campo, e apagar a relação por causa disso faria a resposta oscilar entre
+         * dois `add` seguidos.
+         */
+        ...(payload.groupReference
+            ? { reference: payload.groupReference }
+            : prev?.reference
+                ? { reference: prev.reference }
+                : {}),
     };
     const landed = (() => {
         if (!prev?.fetchedAt)

package/dist/commands/align.js

@@ -97,12 +97,34 @@ opts = {}) {
     /** Sem sistema instalado não há alinho a cobrar - não é desalinho, é um repo sem DS. */
     if (locks.length === 0)
         return out;
-    if (locks.length > 1)
-        out.push({
-            says: `${locks.length} design systems are installed here (${locks
-                .map((l) => l.slug)
-                .join(", ")}) - commands act on the first, so one of them is not being governed`,
-        });
+    /**
+     * DOIS SISTEMAS DEIXA DE SER SUSPEITA QUANDO A RELAÇÃO ESTÁ DECLARADA.
+     *
+     * Este aviso nasceu para o caso real de um clone de outro projeto na mesma
+     * pasta, e ele continua certo ali. Mas um monorepo com uma biblioteca
+     * compartilhada e o vocabulário de um app tem DOIS sistemas de propósito, e
+     * dizer que "um deles não está sendo governado" é chamar de acidente uma
+     * decisão que alguém tomou na tela do grupo.
+     *
+     * Com a referência declarada, a frase muda de queixa para informação: os
+     * comandos seguem agindo sobre o primeiro, e agora dá para dizer QUAL deveria
+     * ser. Sem referência, o aviso é o de sempre.
+     */
+    const declared = locks.find((l) => l.reference)?.reference;
+    if (locks.length > 1) {
+        const names = locks.map((l) => l.slug).join(", ");
+        if (declared && locks.some((l) => l.slug === declared.slug)) {
+            if (locks[0].slug !== declared.slug)
+                out.push({
+                    says: `${locks.length} design systems here (${names}), and this group's reference is \`${declared.slug}\` - but commands act on \`${locks[0].slug}\`, which is first alphabetically.`,
+                });
+        }
+        else {
+            out.push({
+                says: `${locks.length} design systems are installed here (${names}) - commands act on the first, so one of them is not being governed. If that is on purpose, name the reference on the group's screen.`,
+            });
+        }
+    }
     const lock = locks[0];
     const creds = await credentials(home);
     if (!creds)

package/dist/commands/import.js

@@ -2155,6 +2155,31 @@ function sayScopes(c) {
     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.`));
+    /**
+     * A CONVERGÊNCIA VEM ANTES DOS CONFLITOS, porque ela decide se a lista de
+     * conflitos é o assunto.
+     *
+     * Com 60% compartilhado, três divergências são o trabalho. Com 0%, elas são um
+     * detalhe de dois vocabulários que não se encontram - e a conversa que precisa
+     * acontecer é outra: isto é um sistema ou são dois? Medido no monorepo do dono,
+     * `packages/ui` e `apps/web-dashboard` dão exatamente 0%.
+     */
+    const conv = c.scopeConvergence;
+    if (conv) {
+        console.log("");
+        console.log(body(conv.shared === 0
+            ? `${paint.strong("These scopes share no token names at all")} - ${conv.union} names between them, and not one is declared in more than one. They are not drifting apart; they are different vocabularies.`
+            : `${paint.strong(`${conv.percent}% convergence`)} - of the ${conv.union} names between them, ${conv.shared} ${conv.shared === 1 ? "is" : "are"} declared in more than one scope and ${conv.agree} of those already resolve to the same value.`));
+        /**
+         * E A PERGUNTA, dita em voz alta em vez de assumida.
+         *
+         * A fusão presume que os escopos são um sistema só. Abaixo de um terço de
+         * convergência essa premissa deixa de se sustentar sozinha, e quem decide não
+         * é a esteira - é quem conhece os dois produtos.
+         */
+        if (conv.percent < 34)
+            console.log(body(paint.faint("Worth answering before this becomes one system: are these two ONE vocabulary, or two that live in the same repo? Two is a legitimate answer - import each scope on its own, and name which of them is the reference on the group's screen.")));
+    }
     if (conflicts.length === 0)
         return;
     console.log("");

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.255";
+export const MATERIALISER_SINCE = "0.16.256";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/merge-census.js

@@ -227,5 +227,37 @@ export function mergeCensus(list) {
         out.collisions = collisions;
     if (conflicts.length > 0)
         out.scopeConflicts = conflicts;
+    /**
+     * A CONVERGÊNCIA ENTRE OS ESCOPOS, calculada aqui porque é aqui que os
+     * vocabulários separados ainda existem - depois da fusão eles são um só.
+     *
+     * `shared` conta os nomes que mais de um escopo declara; `agree` são os que
+     * resolvem igual. Zero compartilhado não é "quase lá": é a informação de que
+     * não há design em comum, e que fundir produziria a média de dois sistemas que
+     * não se parecem.
+     */
+    {
+        const seen = new Map();
+        let shared = 0;
+        let agree = 0;
+        for (const c of list) {
+            for (const [name, value] of Object.entries(asRecord(c.declared))) {
+                const held = seen.get(name);
+                if (held === undefined) {
+                    seen.set(name, value);
+                    continue;
+                }
+                shared += 1;
+                if (held === value)
+                    agree += 1;
+            }
+        }
+        out.scopeConvergence = {
+            shared,
+            agree,
+            union: seen.size,
+            percent: seen.size === 0 ? 0 : Math.round((agree / seen.size) * 100),
+        };
+    }
     return out;
 }

package/package.json

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