synthesisui 0.16.286 → 0.16.290

package/dist/anatomy-read.js

@@ -32,6 +32,7 @@
 import { readSxProps } from "./doctor/style-props.js";
 import { transcribe, } from "./doctor/transcribe.js";
 import { frontierKind, packageRoot } from "./frontier-kind.js";
+import { withGlobal } from "./global-wear.js";
 /** The ten forms, closed. A renderer that accepts any tag draws anything. */
 const FORMS = new Set([
     "image",
@@ -252,7 +253,18 @@ sketch,
  * A escala de espaçamento que o projeto DELES declara para o `sx`. Ausente = o default
  * documentado do MUI, que é fato da biblioteca que eles escolheram - ver `spacingOf`.
  */
-sxSpacing) {
+sxSpacing, 
+/**
+ * AS CLASSES DA FOLHA GLOBAL DELE - ver `Census.globalClasses` e `wearGlobal`.
+ *
+ * O QUE ISSO ALCANÇA QUE NADA MAIS ALCANÇAVA: uma utility que ele escreve num NÓ FILHO. O
+ * `LeaderboardRow` do `codelevel-ui` põe `text-grad-xp` num `<span>` dentro de um ternário, e o
+ * `QuestItem` põe `text-grad` numa tabela que pertence ao filho - as duas passam por aqui, e não
+ * pela raiz nem pela tabela de variantes do componente.
+ *
+ * Ausente é a resposta de quem não tem folha global, e nesse caso nada muda.
+ */
+globals) {
     /**
      * THE PACKAGE THE RETURNED ELEMENT CAME FROM, measured rather than spelled.
      * Node 0 of the sketch IS what the component returns, and the reader stamped its
@@ -474,7 +486,7 @@ sxSpacing) {
                         ? (sketch?.[node.at]?.classes ?? "")
                         : "";
                 const classes = raw.split(/\s+/).filter(Boolean);
-                const t = transcribe(classes, declared);
+                const t = withGlobal(transcribe(classes, declared), classes, globals);
                 /**
                  * A PROP DE ESTILO DESTE NÓ, sob a classe dele.
                  *
@@ -618,7 +630,7 @@ sxSpacing) {
      * otherwise. So a drawn root sends nothing here at all.
      */
     const rootStyle = rootPainted
-        ? transcribe(rootPainted.split(/\s+/).filter(Boolean), declared)
+        ? withGlobal(transcribe(rootPainted.split(/\s+/).filter(Boolean), declared), rootPainted.split(/\s+/).filter(Boolean), globals)
         : null;
     const paints = rootStyle && Object.keys(rootStyle.base).length > 0
         ? { style: rootStyle.base }
@@ -710,13 +722,16 @@ sxSpacing) {
  * correctly, and the absence of a tree means the preview lays them out in a row
  * exactly as it did before.
  */
-export function resolveFlatParts(read, declared) {
+export function resolveFlatParts(read, declared, 
+/** As classes da folha global dele - ver `wearGlobal`. */
+globals) {
     const parts = {};
     for (const part of read) {
         const name = safePartName(String(part?.name ?? ""));
         if (!name || typeof part.classes !== "string")
             continue;
-        const t = transcribe(part.classes.split(/\s+/).filter(Boolean), declared);
+        const partClasses = part.classes.split(/\s+/).filter(Boolean);
+        const t = withGlobal(transcribe(partClasses, declared), partClasses, globals);
         parts[name] = { base: t.base, dark: t.dark, states: t.states };
     }
     return { parts, tree: [], composes: [], external: [], notes: [], partAt: {} };

package/dist/commands/add.js

@@ -268,6 +268,8 @@ export async function add(slug, opts) {
          * repositório, e é ele que avisa quando uma delas deixa de resolver.
          */
         ...(theirVars.pointed > 0 ? { theirVars: theirVars.pointed } : {}),
+        /** Ver `RootLock.tokenMap`: o fato, ao lado do número que ele produz. */
+        ...(theirVars.pairs.length > 0 ? { tokenMap: theirVars.pairs } : {}),
         ...(scope ? { scope } : {}),
         ...(systems.length > 0 ? { scopes: systems } : {}),
         ...(usage.length > 0 ? { usage } : {}),
@@ -394,6 +396,29 @@ export async function add(slug, opts) {
      * `var(--color-ink-500)` num arquivo "gerenciado pelo synthesisui" e não tem como saber de onde
      * veio. Dito assim, ele lê a linha como o que ela é - o sistema seguindo o vocabulário dele.
      */
+    /**
+     * ELE RENOMEOU UM TOKEN, E A GENTE DIZ - antes era um silêncio que o sistema pagava.
+     *
+     * `their-vars.ts` decidiu NÃO emitir `var(--x, #valor)` justamente para não pintar o valor velho
+     * por cima de um rename dele: *"se ele renomear, quebra, e o `doctor` diz qual"* (dono, 22/08). A
+     * quebra é deliberada e continua. O que faltava era ele saber ANTES de abrir a tela e ver a cor
+     * sumida - o mapa anterior está no `.lock`, o novo acabou de ser calculado, e a diferença é uma
+     * comparação.
+     *
+     * SÓ O RENAME, e não a troca de valor: trocar o valor não quebra nada - a folha aponta para o nome
+     * dele e a cor nova passa a valer, que é o comportamento que a gente promete. Renomear é o que
+     * deixa a referência apontando para o vazio.
+     */
+    const renamed = (prev?.tokenMap ?? []).filter((before) => {
+        const now = theirVars.pairs.find((p) => p.ours === before.ours);
+        return now && now.theirs !== before.theirs;
+    });
+    if (renamed.length > 0) {
+        console.log(`  ${renamed.length} token${renamed.length === 1 ? "" : "s"} you renamed since the last install: ${renamed
+            .slice(0, 3)
+            .map((r) => `${r.theirs} → ${theirVars.pairs.find((p) => p.ours === r.ours)?.theirs ?? "?"}`)
+            .join(", ")}${renamed.length > 3 ? ", …" : ""}. The system follows the new name from here.`);
+    }
     if (theirVars.pointed > 0)
         console.log(`  ${theirVars.pointed} value${theirVars.pointed === 1 ? "" : "s"} in tokens.css now point at the name YOUR code already gives ${theirVars.pointed === 1 ? "it" : "them"} - change yours and the system follows${theirVars.pruned > 0 ? `; ${theirVars.pruned} matched but your build does not emit ${theirVars.pruned === 1 ? "that name" : "those names"}, so ${theirVars.pruned === 1 ? "it keeps" : "they keep"} the value` : ""}`);
     /**

package/dist/commands/component.js

@@ -8,6 +8,7 @@ import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-tem
 import { body, section, snippet } from "../output.js";
 import { findCollision, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
+import { inTheirTongue, tongueOf } from "../their-tongue.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -65,12 +66,41 @@ export async function component(slug, name, opts) {
     // o .tsx é materializado logo abaixo, ninguém as lê depois (medido na
     // auditoria de 16/08), e cada arquivo a mais no repo dele é superfície.
     const config = await readProjectConfig(root);
+    /**
+     * O CSS PASSA A FALAR A LÍNGUA DELE - ver `inTheirTongue`.
+     *
+     * O QUE MUDA NO ARQUIVO QUE ELE ABRE: `color: var(--ds-color-ink-900)` vira
+     * `color: var(--color-ink-900)`, o nome que o código dele já dá àquele valor. É isso que faz a
+     * nossa folha de 3945 linhas deixar de ser necessária no repositório de origem - o `globals.css`
+     * dele já declara o token, e a decisão continua sendo dele.
+     *
+     * AQUI E NÃO NO SERVIDOR, que é onde o CSS é compilado: o mapa descreve ESTE repositório. O mesmo
+     * sistema instalado em outro projeto dele não tem os mesmos nomes declarados, e traduzir lá
+     * apagaria a cor. Um projeto de destino chega sem mapa no `.lock`, nada é traduzido, e a folha
+     * continua sendo o caminho - o comando DIZ qual dos dois aconteceu.
+     */
+    const tongue = await tongueFor(root, slug);
+    const spoken = tongue ? inTheirTongue(res.css, tongue) : null;
+    const css = spoken ? spoken.css : res.css;
+    /**
+     * E ELE FICA SABENDO - traduzir em silêncio é a outra metade do mesmo erro.
+     *
+     * A última linha é a que decide se a nossa folha ainda é necessária aqui, e ela é a diferença
+     * entre "seu repositório dispensa a folha" e "quase" - dizer a primeira quando a verdade é a
+     * segunda é a promessa que quebra na tela dele.
+     */
+    if (spoken && (spoken.named > 0 || spoken.inlined > 0)) {
+        console.log(`  ${spoken.named} reference${spoken.named === 1 ? "" : "s"} now speak${spoken.named === 1 ? "s" : ""} the name YOUR code gives the value${spoken.inlined > 0 ? `, and ${spoken.inlined} carr${spoken.inlined === 1 ? "ies" : "y"} the value because your code names no token for it` : ""}.`);
+        console.log(spoken.left.length === 0
+            ? `  Nothing in this file points at our stylesheet - it renders on your own tokens alone.`
+            : `  ${spoken.left.length} still point${spoken.left.length === 1 ? "s" : ""} at our stylesheet (${spoken.left.slice(0, 3).join(", ")}${spoken.left.length > 3 ? ", …" : ""}), so tokens.css is still needed here.`);
+    }
     const artifactsAreTheProduct = opts.artifactsOnly === true || config.target !== "next";
     if (artifactsAreTheProduct) {
         const dir = join(root, "_synthesisui", "ds", slug, "components");
         await mkdir(dir, { recursive: true });
         await writeFile(join(dir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
-        await writeFile(join(dir, `${res.name}.css`), `${res.css}\n`, "utf8");
+        await writeFile(join(dir, `${res.name}.css`), `${css}\n`, "utf8");
         console.log(`✓ ${res.name} → _synthesisui/ds/${slug}/components/${res.name}.{json,css}  (${slug} v${res.version})`);
     }
     // 2. YOUR component - a real, importable `export function <Pascal>()` in the
@@ -151,12 +181,12 @@ export async function component(slug, name, opts) {
             // template drives itself off the .ds-* classes.
             const tsx = interactiveTemplate(res.name);
             await writeFile(join(compDir, `${res.name}.tsx`), tsx, "utf8");
-            await writeFile(join(compDir, `${res.name}.css`), `${res.css}\n`, "utf8");
+            await writeFile(join(compDir, `${res.name}.css`), `${css}\n`, "utf8");
             await writeFile(join(compDir, "index.ts"), `export * from "./${res.name}";\n`, "utf8");
             filenames = [`${res.name}.tsx`, `${res.name}.css`, "index.ts"];
         }
         else {
-            const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles, await reactMajorOf(root), 
+            const files = generateComponentFiles(slug, res.name, res.recipe, css, res.version, config.styles, await reactMajorOf(root), 
             /**
              * THE SPELLING, FROM THE VERSION WE JUST FETCHED.
              *
@@ -246,3 +276,35 @@ export async function component(slug, name, opts) {
     }
     console.log("");
 }
+/**
+ * O VOCABULÁRIO DESTE REPOSITÓRIO, do que o `add` já deixou na pasta - ver `tongueOf`.
+ *
+ * `null` quando não há mapa: é a resposta de um projeto de destino, de um repositório que nunca
+ * buildou, ou de um install feito por um CLI anterior a 0.16.290. Nos três casos nada é traduzido e
+ * a folha instalada continua sendo o caminho, que é o comportamento de sempre.
+ */
+async function tongueFor(root, slug) {
+    const dir = join(root, "_synthesisui", "ds", slug);
+    const lock = await readFile(join(dir, ".lock"), "utf8").catch(() => null);
+    if (!lock)
+        return null;
+    let map = [];
+    let version = 0;
+    try {
+        const parsed = JSON.parse(lock);
+        map = parsed.tokenMap ?? [];
+        version = parsed.version ?? 0;
+    }
+    catch {
+        return null;
+    }
+    if (map.length === 0)
+        return null;
+    /**
+     * O VALOR COMPILADO MORA NA PASTA DA VERSÃO - a folha da raiz é um re-export de uma linha, escrito
+     * assim de propósito para que o `@import` dele nunca mude entre updates (ver `add.ts`). É de lá
+     * que sai o literal para as variáveis que não têm nome dele.
+     */
+    const installed = await readFile(join(dir, `v${version}`, "tokens.css"), "utf8").catch(() => "");
+    return tongueOf(map, installed);
+}

package/dist/commands/import.js

@@ -40,7 +40,9 @@ import { keyframesInSheets } from "../global-keyframes.js";
 import { withLibraryStructure } from "../library-structure.js";
 import { mergeCensus } from "../merge-census.js";
 import { claimName } from "../name-claim.js";
+import { mergeNamespacePairs } from "../namespace-pairs.js";
 import { namingQueue } from "../naming-queue.js";
+import { notExpressed } from "../not-expressed.js";
 import { body, paint, section } from "../output.js";
 import { outsideScope } from "../outside-scope.js";
 import { phase, startProgress } from "../progress.js";
@@ -367,6 +369,8 @@ function screenOf(rel) {
     const after = parts.slice(i + 1).filter((p) => !p.startsWith("("));
     return `${parts[i]}/${after.slice(0, 2).join("/")}`;
 }
+/** Quantas classes da folha global viajam no censo. Ver o aviso em `takeCensus`. */
+const MAX_GLOBAL_CLASSES = 300;
 export async function takeCensus(root, opts) {
     /**
      * O RELATÓRIO SÓ SAI QUANDO ALGUÉM O PEDIU - `say` cala quando o chamador é uma RE-medição.
@@ -450,6 +454,17 @@ export async function takeCensus(root, opts) {
      * porque é isso que o juiz do ledger precisa para chamar a classe e a regra de LIDAS.
      */
     const globalClasses = readGlobalClasses(globalSheets, declaredValues);
+    /**
+     * TETO DAS CLASSES GLOBAIS QUE VIAJAM NO CENSO - e quando ele corta, ele fala.
+     *
+     * Medido nas três populações: 24 classes na folha do `codelevel-ui`, 22 na nossa, 0 no
+     * `apps/web-dashboard` do repo real, que é CSS Modules. O teto é para a folha de um app que
+     * escreva utilitário por atacado, e existe porque um censo que dobra de tamanho em silêncio é o
+     * tipo de surpresa que ninguém pede.
+     */
+    if (globalClasses.size > MAX_GLOBAL_CLASSES) {
+        console.log(body(paint.faint(`${globalClasses.size} classes in your global sheet, and ${globalClasses.size - MAX_GLOBAL_CLASSES} of them are not travelling with this census - the first ${MAX_GLOBAL_CLASSES} are.`)));
+    }
     /**
      * OS KEYFRAMES DA FOLHA DELE, colhidos onde as folhas globais já estão na mão.
      *
@@ -735,16 +750,18 @@ export async function takeCensus(root, opts) {
                             /**
                              * Ver `CensusLook.aside` - o segundo componente do arquivo também.
                              *
-                             * AQUI OS EIXOS NÃO SÃO CONHECIDOS: `transcribeVariants` roda para o primeiro
-                             * componente do arquivo, e este é o segundo. Passar `undefined` é dizer a verdade
-                             * ("não sei se declara"), e não uma omissão - e é por isso que o veto final, em
-                             * `exclusive-contract.ts`, pergunta pelos eixos em vez de confiar só neste campo.
+                             * E COM OS EIXOS QUE O TIPO DELE DECLARA. `transcribeVariants` roda para o primeiro
+                             * componente do arquivo, então aqui não há tabela de variantes - mas `extra.axes` é a
+                             * declaração da interface, lida por `scanDefinitions` para TODA definição do arquivo.
+                             * Era `undefined`, e isso pôs de lado o `ToastIcon` dele: terceiro componente do
+                             * `Toast.tsx`, cinco tons declarados no tipo, um gradiente para cada. Ver
+                             * `classifyAside`.
                              */
-                            ...(classifyAside({ name: extra.name, declaredAxes: undefined })
+                            ...(classifyAside({ name: extra.name, declaredAxes: extra.axes })
                                 ? {
                                     aside: classifyAside({
                                         name: extra.name,
-                                        declaredAxes: undefined,
+                                        declaredAxes: extra.axes,
                                     }),
                                 }
                                 : {}),
@@ -782,7 +799,7 @@ export async function takeCensus(root, opts) {
                  * for the result, which is the "valid and unread" failure this pipeline has
                  * paid for twice already.
                  */
-                const v = transcribeVariants(src, declaredValues);
+                const v = transcribeVariants(src, declaredValues, globalClasses);
                 /**
                  * THE RESTING OPTION, from the definition itself. `cva` says it in
                  * `defaultVariants`; a lookup-record component says it in the destructuring -
@@ -1040,14 +1057,20 @@ export async function takeCensus(root, opts) {
                         /**
                          * Ver `CensusLook.aside`: o fato viaja, a regra fica de um lado só.
                          *
-                         * `v.axes` é a DECLARAÇÃO de variação deste componente, e é ela que separa um glifo de
-                         * um componente cujo nome só parece com um. Ver `classifyAside`.
+                         * AS DUAS FONTES DE EIXO, e é a mesma decisão do autor nas duas. `found[0].axes` é o que
+                         * o TIPO declara (`interface ToastIconProps { tone?: "gold" | "cool" }`); `v.axes` é o
+                         * que a TABELA declara (`cva({ variants: … })`). Consultar só a segunda pôs de lado um
+                         * componente que pinta por `Record<tone, gradiente>` - forma que a tabela não vê.
+                         * Ver `classifyAside`.
                          */
-                        ...(classifyAside({ name: found[0].name, declaredAxes: v.axes })
+                        ...(classifyAside({
+                            name: found[0].name,
+                            declaredAxes: { ...found[0].axes, ...v.axes },
+                        })
                             ? {
                                 aside: classifyAside({
                                     name: found[0].name,
-                                    declaredAxes: v.axes,
+                                    declaredAxes: { ...found[0].axes, ...v.axes },
                                 }),
                             }
                             : {}),
@@ -1864,7 +1887,14 @@ export async function takeCensus(root, opts) {
             list.push(kebab(pair.child));
         companionsOf.set(pair.component, list);
     }
-    const components = merged.map((c) => ({
+    /**
+     * `Modal.Header` E `ModalHeader` CONTADOS UMA VEZ - ver `mergeNamespacePairs`.
+     *
+     * Antes do enriquecimento porque veredito, leis e companheiros são indexados por NOME: fundir
+     * depois deixaria metade do que se sabe sobre a peça pendurado no nome que deixou de existir.
+     */
+    const paired = mergeNamespacePairs(merged, new Set(defined.map((d) => d.name)));
+    const components = paired.map((c) => ({
         ...c,
         ...(verdicts.get(idOf(c)) ?? {}),
         ...(laws.has(c.name) ? { laws: laws.get(c.name) } : {}),
@@ -2071,6 +2101,25 @@ export async function takeCensus(root, opts) {
             }
             : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
+        /**
+         * AS CLASSES DA FOLHA GLOBAL DELE - ver `Census.globalClasses`.
+         *
+         * TODAS AS QUE A FOLHA DECLARA, e não só as que a raiz vestiu. A primeira tentativa levou apenas
+         * as reivindicadas por `globalWear`, que só roda na raiz do componente - e as utilities usadas
+         * numa tabela de variantes ou num nó filho, que são a maioria, ficavam de fora justamente do
+         * campo que existe para alcançá-las. Duas de 24 chegavam.
+         *
+         * O CUSTO ESTÁ MEDIDO: a folha do `codelevel-ui` declara 24 classes, a nossa 22, e o
+         * `apps/web-dashboard` do repo real declara 0 - ele é CSS Modules. Nas três populações isso é
+         * ruído no tamanho do censo. O teto de `MAX_GLOBAL_CLASSES` existe para a folha de um app que
+         * escreva utilitário por atacado, e quando ele corta, o número cortado é DITO em vez de
+         * desaparecer.
+         */
+        ...(globalClasses.size > 0
+            ? {
+                globalClasses: Object.fromEntries([...globalClasses.entries()].slice(0, MAX_GLOBAL_CLASSES)),
+            }
+            : {}),
         classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
         ...(naming.components > 0 ? { naming } : {}),
@@ -3166,6 +3215,16 @@ export function rootBehaviour(tag, sketch) {
 export async function resolveReadParts(census, root, 
 /** `true` numa re-medição: o resumo desta etapa fica para o `sync --full` - ver `say`. */
 quiet = false) {
+    /**
+     * AS CLASSES DA FOLHA GLOBAL DELE, DO CENSO - ver `Census.globalClasses`.
+     *
+     * Esta etapa roda depois da medição, e também no `sync` e do lado da plataforma, sobre censo já
+     * guardado - então ela não tem como voltar à folha no disco. Vindo do censo, uma utility que ele
+     * escreve num NÓ FILHO chega ao look: o `LeaderboardRow` põe `text-grad-xp` num `<span>` dentro de
+     * um ternário, e é aqui que aquele nó é lido.
+     */
+    const globalClasses = new Map(Object.entries(census
+        .globalClasses ?? {}));
     const say = quiet
         ? () => { }
         : (line) => {
@@ -3278,13 +3337,13 @@ quiet = false) {
             ? resolveAnatomy(framed, declared, deps, resolveRef, entry?.root, 
             // The component's own sketch, so a node naming itself by index reads
             // the exact class string the census measured (dono, 01/08).
-            looks[component]?.sketch, census.sxSpacing)
+            looks[component]?.sketch, census.sxSpacing, globalClasses)
             : patched
-                ? resolveAnatomy(patched.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing)
+                ? resolveAnatomy(patched.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing, globalClasses)
                 : derived && derived.read.length > 0
-                    ? resolveAnatomy(derived.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing)
+                    ? resolveAnatomy(derived.read, declared, deps, resolveRef, entry?.root, looks[component]?.sketch, census.sxSpacing, globalClasses)
                     : Array.isArray(entry?.parts) && entry.parts.length > 0
-                        ? resolveFlatParts(entry.parts, declared)
+                        ? resolveFlatParts(entry.parts, declared, globalClasses)
                         : null;
         if (!resolved)
             continue;
@@ -3699,6 +3758,23 @@ export async function runImport(opts) {
     const out = opts.census ?? join(root, "_synthesisui", "census.json");
     await mkdir(dirname(out), { recursive: true });
     await writeFile(out, `${JSON.stringify(census, null, 2)}\n`, "utf8");
+    /**
+     * O QUE NÃO CHEGOU, DECLARADO PELA ESTEIRA - ver `notExpressed`.
+     *
+     * Escrito ao lado do censo e na mesma rodada, porque a lacuna e a medição são a mesma verdade
+     * vista dos dois lados. Era o agente que escrevia este arquivo, instruído por uma frase dentro da
+     * descrição de uma tool - e em 23/08 o mesmo repositório foi importado duas vezes, a primeira
+     * declarando 37 linhas de lacuna e a segunda nenhuma, com as lacunas todas no lugar. Um pedido a
+     * um modelo não é um artefato.
+     *
+     * O agente ainda ACRESCENTA o que só ele vê. O piso deixou de depender dele.
+     */
+    const gaps = notExpressed(census);
+    if (gaps) {
+        const gapFile = join(dirname(out), "not-expressed.md");
+        await writeFile(gapFile, gaps, "utf8");
+        console.log(body(`Gaps written to ${paint.strong(relative(root, gapFile))}`));
+    }
     console.log("");
     console.log(body(`Written to ${paint.strong(relative(root, out))}`));
     if (opts.dry) {

package/dist/doctor/broken-refs.js

@@ -19,6 +19,8 @@
  */
 import { frontierKind } from "../frontier-kind.js";
 import { importMap } from "./imports.js";
+/** Quantos lugares viajam por referência quebrada. Ver `BrokenRef.at`. */
+const MAX_PLACES = 3;
 /** `var(--x)`, including inside a Tailwind arbitrary value: `bg-[var(--x)]`. */
 const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
 /**
@@ -96,9 +98,20 @@ export function findBrokenRefs(sources, declared) {
                 continue;
             if (runtime && (RUNTIME_ANCHOR.has(name) || RUNTIME_PREFIX.test(name)))
                 continue;
-            const hit = seen.get(name) ?? { count: 0, files: new Set() };
+            const hit = seen.get(name) ?? {
+                count: 0,
+                files: new Set(),
+                at: [],
+            };
             hit.count += 1;
             hit.files.add(file);
+            /** A linha contada do índice do match - ver `BrokenRef.at` para o teto. */
+            if (hit.at.length < MAX_PLACES) {
+                hit.at.push({
+                    file,
+                    line: source.slice(0, m.index ?? 0).split("\n").length,
+                });
+            }
             seen.set(name, hit);
         }
     }
@@ -111,6 +124,7 @@ export function findBrokenRefs(sources, declared) {
             count: hit.count,
             files: hit.files.size,
             ...(meant ? { meant } : {}),
+            ...(hit.at.length > 0 ? { at: hit.at } : {}),
         });
     }
     // A broken reference somebody typed nine times is worse than one typed once,

package/dist/doctor/component-gate.js

@@ -61,6 +61,8 @@ const PROVIDER_SUFFIX = /(Provider|Providers|Context|Boundary|Guard|Wrapper)$/;
 /** Any JSX at all in the file. A capitalised export with none is a constant, a
  *  config object or a helper - `export const ROUTES = {…}` is not a component. */
 const HAS_JSX = /<[A-Za-z][^>]*>|<>/;
+/** `ICON_SIZE`, `AURORA_PALETTES`, `ARTICLE_TAB` - a convenção universal para valor, não para peça. */
+const SCREAMING_SNAKE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
 /**
  * Any sign that this file decides how something LOOKS.
  *
@@ -71,7 +73,30 @@ const HAS_JSX = /<[A-Za-z][^>]*>|<>/;
 const HAS_STYLING = /className|class=|style=|styled[.(]|css`|cva\(|\btv\(|makeStyles|sx=|tw`/;
 /** `createContext` + a `.Provider` in the return is a provider whatever it is
  *  called - `RootWrapper` and `CommonProviders` both read this way. */
-const IS_CONTEXT = /createContext\s*[<(]/;
+/**
+ * QUEM RECEBE O `createContext` - o nome, e não o arquivo em volta dele.
+ *
+ * O QUE O CLIENTE PERDIA: o `Tabs` inteiro. `Tabs.tsx` declara `const TabsCtx = createContext(…)`, e
+ * a pergunta era se o ARQUIVO tem contexto - então `Tabs`, `TabsList`, `TabsTrigger` e `TabsPanel`
+ * saíram juntos, com `cn("flex flex-col gap-4")` escrito neles (`codelevel-ui`, 23/08). Composto com
+ * contexto é o padrão dominante de React - Tabs, Accordion, Select, Dropdown -, então recusar o
+ * arquivo recusa a família toda.
+ *
+ * É a mesma falha de forma que `HAS_JSX` já cometeu do outro lado: uma pergunta sobre o arquivo
+ * respondendo sobre o export. Um provider é UM nome; os vizinhos respondem por si.
+ *
+ * Medido em três populações - `codelevel-ui` recupera 4, o dashboard do `frontend-hub` recupera 7
+ * (o `Pagination` inteiro), e os 6 que terminam em `Provider` continuam fora pelo sufixo.
+ */
+const CONTEXT_OWNER = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]*)?=\s*(?:React\.)?createContext\s*[<(]/g;
+/** Os nomes que ESTE arquivo atribui a um `createContext`. */
+function contextNames(source) {
+    CONTEXT_OWNER.lastIndex = 0;
+    const out = new Set();
+    for (const m of source.matchAll(CONTEXT_OWNER))
+        out.add(m[1]);
+    return out;
+}
 /** A lowercase JSX tag: an html element this file renders ITSELF. */
 const OWN_ELEMENT = /<(?:[a-z][a-z0-9]*)(\s|>|\/)/;
 /** Every capitalised JSX tag the file opens, dots included. */
@@ -205,7 +230,7 @@ export function gateComponent(input) {
             because: `\`${name}\` names a screen, and composes ${shape.composes} piece${shape.composes === 1 ? "" : "s"} across ${shape.nodes} element${shape.nodes === 1 ? "" : "s"} - too thin to be a template of yours. A design system is made of the pieces a screen is built FROM`,
         };
     }
-    if (PROVIDER_SUFFIX.test(name) || IS_CONTEXT.test(source)) {
+    if (PROVIDER_SUFFIX.test(name) || contextNames(source).has(name)) {
         return {
             ok: false,
             why: "provider",
@@ -232,6 +257,38 @@ export function gateComponent(input) {
      */
     if (STYLED_FACTORY.test(source))
         return { ok: true };
+    /**
+     * UMA CONSTANTE NÃO É COMPONENTE, e o arquivo em volta dela não muda isso.
+     *
+     * O QUE O CLIENTE VIA: `ICON_SIZE` e `AURORA_PALETTES` ocupando vaga na vitrine do
+     * `codelevel-ui`, e uma delas com forma desenhada - um mapa de tamanhos renderizado como se fosse
+     * peça. Ele contava 59 componentes no design system dele e dois não existiam.
+     *
+     * O teste de markup logo abaixo já recusa constante, e ele pergunta pelo ARQUIVO INTEIRO:
+     * `ICON_SIZE` mora dentro do `Icon.tsx`, que tem JSX de sobra, então ela entrava pela porta do
+     * vizinho. Vem ANTES dele por isso - é a mesma falha de forma que o teste de contexto acima
+     * corrigiu do outro lado.
+     *
+     * MEDIDO EM QUATRO POPULAÇÕES, e as três encontradas são objeto literal no código real:
+     *
+     *     codelevel-ui packages/ui         75 nomes ·  2  (ICON_SIZE, AURORA_PALETTES)
+     *     frontend-hub packages/ui         69 nomes ·  0
+     *     frontend-hub apps/web-dashboard 526 nomes ·  1  (ARTICLE_TAB, um enum de aba)
+     *     synthesisui apps/web                       ·  0
+     *
+     * Nenhum componente das quatro usa este formato de nome - JSX escreve `<Button>` e nunca
+     * `<ICON_SIZE>` -, então a regra não recusa peça de ninguém. E ela só pôde entrar junto com o
+     * leitor de `export default` em linha própria: sozinha, ela deixava órfãs as 294 declarações de
+     * CSS Modules do único arquivo do dashboard onde a constante era a ÚNICA coisa que o leitor via.
+     * O dono daquele arquivo é o `CurateContentSection`, que agora é lido.
+     */
+    if (SCREAMING_SNAKE.test(name)) {
+        return {
+            ok: false,
+            why: "config",
+            because: `\`${name}\` is spelled as a constant - a value the code reads, not a component anything renders`,
+        };
+    }
     if (!HAS_JSX.test(source)) {
         return {
             ok: false,