synthesisui 0.16.132 → 0.16.134

package/dist/commands/import.js

@@ -16,6 +16,7 @@ import { crosswalk, floorSize, isLibrary, observedRules, useLiveCatalogue, } fro
 import { keyframeOffsets, moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from "../doctor/css-modules.js";
 import { dataContract } from "../doctor/data-contract.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
+import { fragmentsOfSource, fragmentsOfStylesheet, judgeFragments, } from "../doctor/fragments.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
 import { pageLaws } from "../doctor/page-laws.js";
 import { callSiteNode, placeLayers, } from "../doctor/place-layers.js";
@@ -25,6 +26,7 @@ import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
 import { sketchOf } from "../doctor/sketch.js";
 import { describeForeign, readStyleIslands, } from "../doctor/style-island.js";
+import { buildLedger, describeLedger, } from "../doctor/style-ledger.js";
 import { buildTable } from "../doctor/tokens.js";
 import { definitionSpan, readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
@@ -126,12 +128,28 @@ async function siblingProjects(root) {
  * this" - could not be said, and we ended up rediscovering by colour distance
  * what their stylesheet had spelled out all along.
  */
-async function harvestOwnCss(root) {
+async function harvestOwnCss(root, 
+/**
+ * O LEDGER TAMBÉM COME AQUI, e por um motivo de promessa: este é o único laço que vê TODO
+ * arquivo de estilo do escopo, inclusive o module de um componente que o portão não admite.
+ *
+ * O laço de componente lê o module do componente aceito, então sem isto 9 663 declarações
+ * continuariam invisíveis - e a promessa desta fatia é que nada é descartado em silêncio
+ * (dono, 04/08). O veredito de cada uma sai depois, em `judgeFragments`: pertencer a componente
+ * não admitido é um motivo, não um desaparecimento.
+ */
+into) {
     let css = "";
     for await (const file of walkAll([root])) {
         if (!/\.(css|scss|sass|less)$/i.test(file))
             continue;
-        css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+        const body = await readFile(file, "utf8").catch(() => "");
+        css += `\n${body}`;
+        if (into && body)
+            into.push({
+                file: relative(root, file),
+                fragments: fragmentsOfStylesheet(relative(root, file), body, /\.module\./.test(file)),
+            });
     }
     return css;
 }
@@ -255,7 +273,9 @@ export async function takeCensus(root, opts) {
      */
     const fetched = await fetchCatalogue(opts?.registry);
     useLiveCatalogue(fetched.ok ? asCatalogueTable(fetched.index) : null);
-    const css = await harvestOwnCss(root);
+    /** Todo arquivo de estilo do escopo, para o ledger - ver o parâmetro `into`. */
+    const styleFiles = [];
+    const css = await harvestOwnCss(root, styleFiles);
     const table = buildTable({ css, source: "yours" });
     const schemes = parseSchemeBlocks(css);
     const reports = [];
@@ -268,6 +288,10 @@ export async function takeCensus(root, opts) {
     const kindOf = new Map();
     /** A raiz e a composição de cada página, para as leis - ver `pageLaws`. */
     const pages = [];
+    /** Todo fragmento de estilo visto, para o ledger - ver `buildLedger`. */
+    const fragments = [];
+    /** Arquivos de estilo que pertencem a componente admitido - o veredito do `css` sai daqui. */
+    const admittedStyles = new Set();
     /** What the gate turned away, with the reason. Never dropped in silence. */
     const skips = [];
     // Kept for the reference check below, which needs every file at once: a name
@@ -313,9 +337,6 @@ export async function takeCensus(root, opts) {
     const projectsOf = new Map();
     /** Component → the axes its own `cva` declares. See `variant-read.ts`. */
     const variantAxes = new Map();
-    /** How much came out of CSS Modules, for the coverage report. */
-    let moduleFiles = 0;
-    let moduleDeclarations = 0;
     /**
      * THE KEYFRAMES THE READING NEEDS, by name - and this was collected and dropped.
      *
@@ -455,6 +476,11 @@ export async function takeCensus(root, opts) {
              * numa lista feita para biblioteca. O look já nasce aqui, com o arquivo e a fonte na mão,
              * e é aqui que a leitura tem que se pendurar.
              */
+            /**
+             * TODO FRAGMENTO DE ESTILO DESTE ARQUIVO, cego ao portão - ver `fragmentsOfSource`. É o que
+             * permite o relatório dizer o que existe e não foi lido, em vez de só o que foi.
+             */
+            fragments.push(fragmentsOfSource(rel, src));
             for (const d of found) {
                 sourceOf.set(d.name, { file: rel, source: src });
                 /** O que a peça É, do portão - ver `GateVerdict.kind` e `CensusLook.kind`. */
@@ -544,12 +570,16 @@ export async function takeCensus(root, opts) {
                     const usage = readModuleUsage(src, mod.local);
                     if (usage.length === 0)
                         continue;
+                    /**
+                     * ESTE MODULE PERTENCE A UM COMPONENTE ADMITIDO - o único fato que este laço tem e o
+                     * ledger precisa. Os fragmentos dele vêm do `harvestOwnCss`, que vê todos os arquivos
+                     * de estilo e não só os de componente aceito.
+                     */
+                    admittedStyles.add(relative(root, cssPath));
                     const readModule = transcribeModule(readModuleCss(moduleCss), usage, declaredValues);
                     if (readModule.read === 0)
                         continue;
                     fromModule = readModule;
-                    moduleFiles += 1;
-                    moduleDeclarations += readModule.read;
                     for (const [name, frames] of Object.entries(readModule.keyframes)) {
                         const offsets = keyframeOffsets(frames);
                         if (!keyframes[name] && Object.keys(offsets).length > 0)
@@ -1152,6 +1182,13 @@ export async function takeCensus(root, opts) {
             Object.keys(l.parts ?? {}).length === 0 &&
             (l.layers ?? []).length === 0);
     }).length;
+    /**
+     * O LEDGER, com o veredito dado pelos mesmos leitores da esteira - ver `judgeFragments`.
+     *
+     * Montado aqui porque é o primeiro momento em que as três coisas existem juntas: os fragmentos
+     * vistos, os tokens declarados, e quais arquivos de estilo pertencem a componente admitido.
+     */
+    const ledger = buildLedger(opts?.cli ?? "unknown", judgeFragments([...fragments.flat(), ...styleFiles.flatMap((s) => s.fragments)], declaredValues, admittedStyles));
     const coverageLines = describeCoverage(coverage, composition);
     if (coverageLines.length > 0) {
         console.log("");
@@ -1175,6 +1212,13 @@ export async function takeCensus(root, opts) {
      * AS LEIS DAS PÁGINAS, ditas onde a arquitetura já é dita - governam o sistema, não uma peça,
      * então `applies` é vazio e elas chegam a todo prompt. Ver `pageLaws`.
      */
+    const ledgerLines = describeLedger(ledger);
+    if (ledgerLines.length > 0) {
+        console.log("");
+        console.log(section("Every style fragment, accounted for"));
+        for (const line of ledgerLines.slice(0, 24))
+            console.log(body(line));
+    }
     const pageRules = pageLaws(pages);
     if (pageRules.length > 0) {
         console.log("");
@@ -1416,6 +1460,14 @@ export async function takeCensus(root, opts) {
         observed: distinctValues(d),
         ...(components.length > 0 ? { components } : {}),
         ...(defined.length > 0 ? { defined } : {}),
+        /**
+         * TODO FRAGMENTO DE ESTILO, CONTABILIZADO - ver `StyleLedger`.
+         *
+         * Viaja com o censo porque é a plataforma que mostra o número ao cliente, e é a partir daqui
+         * que a skill deste repositório descobre qual forma ainda não é lida e onde ela mora, sem
+         * ninguém ter que reportar (dono, 04/08).
+         */
+        ledger,
         /**
          * THE SHAPE, AND THE RULE IT BECOMES.
          *
@@ -1457,6 +1509,20 @@ export async function takeCensus(root, opts) {
                 skipped: skips
                     .slice(0, 400)
                     .map(({ name, why, because }) => ({ name, why, because })),
+                /**
+                 * OS NÚMEROS VERDADEIROS DO PORTÃO, porque a lista acima é cortada em 400 e num
+                 * monorepo real o corte estoura (712 recusados, 400 gravados). Contar a lista daria
+                 * 400 e pareceria completo.
+                 */
+                gate: {
+                    admitted: scoped.length,
+                    refused: skips.length,
+                    groups: groupSkips(skips).map((g) => ({
+                        why: g.why,
+                        label: g.label,
+                        count: g.names.length,
+                    })),
+                },
             }
             : {}),
         ...((opts?.usage ?? []).length > 0
@@ -2476,6 +2542,7 @@ export async function runImport(opts) {
         census = await takeCensus(readFrom, {
             ...(usage.length > 0 ? { usage } : {}),
             ...(scope ? { scopeLabel: scope } : {}),
+            ...(opts.cli ? { cli: opts.cli } : {}),
         });
         if (scope)
             census.scope = scope;

package/dist/doctor/fragments.js

@@ -0,0 +1,219 @@
+/**
+ * TODO FRAGMENTO QUE CARREGA ESTILO, com arquivo e linha.
+ *
+ * Esta é a metade que faltava para o ledger: a esteira lia estilo em cinco lugares diferentes e
+ * nenhum deles registrava o que tinha visto e não conseguido usar. O resultado é que "o que falta"
+ * era uma pergunta que só se respondia abrindo o repo do cliente à mão (dono, 04/08).
+ *
+ * A varredura aqui é DELIBERADAMENTE cega ao portão: ela vê o estilo de todo arquivo, inclusive de
+ * componente que não vai virar receita. O portão é uma decisão sobre a VITRINE, e usá-lo para
+ * decidir o que se mede é o que fez 9 663 declarações de module ficarem invisíveis.
+ *
+ * O VEREDITO NÃO É DADO AQUI. Esta função diz "vi este fragmento, desta forma, aqui"; quem sabe
+ * se ele foi lido é a interpretação, que roda depois. Juntar as duas coisas numa função seria
+ * repetir a mistura que a tabela de cobertura já paga: forma e veredito são fatos diferentes.
+ */
+import { readInlineStyle, transcribe } from "./transcribe.js";
+/** `className="…"` e `className={"…"}` - o literal puro. */
+const CLASS_LITERAL = /className=(?:"([^"]{0,400})"|\{\s*"([^"]{0,400})"\s*\})/g;
+/** `className={`… ${x} …`}` - metade literal, metade runtime. */
+const CLASS_TEMPLATE = /className=\{\s*`([^`]{0,400})`\s*\}/g;
+/** `className={algo}` sem literal nenhum: não existe na fonte. */
+const CLASS_RUNTIME = /className=\{\s*([A-Za-z_$][\w$.[\]]{0,60})\s*\}/g;
+/** Um literal dentro de `cn("…", …)` e amigos. */
+const CALL_LITERAL = /\b(?:cn|clsx|classNames|cx|twMerge|twJoin|classcat)\(([^)]{0,600})\)/g;
+const STRING_IN_CALL = /"([^"]{0,300})"|'([^']{0,300})'/g;
+/** `style={{ … }}`. */
+const INLINE = /style=\{\{([^}]{0,400})\}\}/g;
+/** `sx={{ … }}`. */
+const SX = /sx=\{\{([^}]{0,400})\}\}/g;
+/** `styled.div\`…\`` e `styled(X)\`…\``. */
+const STYLED = /styled[.(][^`]{0,60}`([^`]{0,400})`/g;
+/**
+ * Um pedaço de linha de estilo e o que o termina: `{` faz do pedaço um seletor, `;` e `}` fazem
+ * dele uma declaração. Ler a linha inteira de uma vez perde `.card { padding: 8px }` numa linha só,
+ * e um coletor que promete não deixar nada invisível não pode escolher a formatação do arquivo.
+ */
+const PIECES = /([^{};]*)([{};]|$)/g;
+/** Uma declaração `prop: value`, já sem o terminador. */
+const DECLARATION = /^(-{0,2}[a-zA-Z][\w-]*)\s*:\s*([^;{}]{1,200})$/;
+/** Uma classe que só um literal pode ter: começa com letra minúscula. */
+const LOOKS_LIKE_CLASS = /^[a-z[]/;
+/**
+ * `${styles.card}` dentro de um template: uma classe de CSS module, cujo valor mora no arquivo de
+ * estilo - que a esteira lê. É a mesma regra que `CLASS_RUNTIME` já aplica a `className={styles.x}`.
+ */
+const MODULE_REF = /\$\{\s*[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*\s*\}/g;
+/**
+ * Os fragmentos de um arquivo `.tsx`/`.jsx`, com a linha de cada um.
+ *
+ * `read` sai FALSO em todos: quem preenche o veredito é quem tem a interpretação em mão. As formas
+ * que nenhum leitor cobre (`sx`, `styled`, `runtime`) já saem com o motivo, porque nesses casos o
+ * motivo é a própria forma e não depende de leitura.
+ */
+export function fragmentsOfSource(file, source) {
+    const out = [];
+    const at = (index) => source.slice(0, index).split("\n").length;
+    const push = (shape, index, text, reason) => {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        out.push({
+            shape,
+            file,
+            line: at(index),
+            text: trimmed,
+            read: false,
+            ...(reason ? { reason } : {}),
+        });
+    };
+    for (const m of source.matchAll(CLASS_LITERAL))
+        push("class", m.index ?? 0, m[1] ?? m[2] ?? "");
+    for (const m of source.matchAll(CLASS_TEMPLATE))
+        push("template", m.index ?? 0, m[1] ?? "");
+    for (const m of source.matchAll(CLASS_RUNTIME)) {
+        /**
+         * `className={styles.content}` é uma classe de CSS module, que a esteira LÊ - o valor está no
+         * arquivo de estilo, não aqui. Só um identificador solto é genuinamente runtime.
+         */
+        const value = m[1] ?? "";
+        if (/^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$/.test(value))
+            continue;
+        push("runtime", m.index ?? 0, `className={${value}}`, "computed");
+    }
+    /**
+     * OS LITERAIS DENTRO DE UMA CHAMADA. `cn("flex p-4", cond && "gap-2")` tem dois, e os dois são
+     * classe escrita à mão - a forma mais comum do repo dele (113 arquivos).
+     */
+    for (const call of source.matchAll(CALL_LITERAL)) {
+        const body = call[1] ?? "";
+        const base = (call.index ?? 0) + (call[0].length - body.length - 1);
+        for (const s of body.matchAll(STRING_IN_CALL)) {
+            const text = s[1] ?? s[2] ?? "";
+            if (!LOOKS_LIKE_CLASS.test(text))
+                continue;
+            push("class", base + (s.index ?? 0), text);
+        }
+    }
+    for (const m of source.matchAll(INLINE))
+        push("inline", m.index ?? 0, m[1] ?? "");
+    for (const m of source.matchAll(SX))
+        push("sx", m.index ?? 0, m[1] ?? "", "shape-not-read");
+    for (const m of source.matchAll(STYLED))
+        push("styled", m.index ?? 0, m[1] ?? "", "shape-not-read");
+    return out;
+}
+/**
+ * Os fragmentos de um arquivo de estilo: uma declaração é um fragmento.
+ *
+ * `scoped` diz se aquele arquivo é um CSS module. A distinção importa para o veredito e não para a
+ * contagem: um global com regra de CLASSE é forma que nenhum leitor cobre hoje - 399 declarações
+ * no repo dele, e a única lacuna que estava calada em vez de declarada (04/08).
+ */
+export function fragmentsOfStylesheet(file, css, scoped) {
+    const out = [];
+    let selector = "";
+    for (const [i, raw] of css.split("\n").entries()) {
+        const line = raw.replace(/\/\*.*?\*\//g, "");
+        for (const piece of line.matchAll(PIECES)) {
+            const text = (piece[1] ?? "").trim();
+            if (piece[2] === "{") {
+                selector = text;
+                continue;
+            }
+            /**
+             * Sem terminador não há declaração: `padding: 8px` no fim de uma linha pode ser a primeira
+             * metade de um valor que continua na próxima.
+             */
+            if (!piece[2] || !text)
+                continue;
+            const m = DECLARATION.exec(text);
+            if (!m)
+                continue;
+            /**
+             * UM TOKEN NÃO É UM FRAGMENTO DE COMPONENTE. `--color-ocean-500: #…` é a paleta, e ela tem
+             * o seu próprio caminho e o seu próprio relatório; contá-la aqui inflaria o total com o que
+             * já está coberto em outro lugar.
+             */
+            if (m[1].startsWith("--"))
+                continue;
+            out.push({
+                shape: "css",
+                file,
+                line: i + 1,
+                text: `${selector ? `${selector} ` : ""}{ ${m[1]}: ${m[2].trim()} }`,
+                read: false,
+                ...(scoped ? {} : { reason: "shape-not-read" }),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * O VEREDITO DE CADA FRAGMENTO, dado pelos MESMOS leitores que a esteira usa.
+ *
+ * Não é aproximação: para uma class string, "foi lida" é literalmente `transcribe` devolver ao
+ * menos uma declaração - a mesma chamada que produz o look. Um segundo julgamento, escrito à parte,
+ * seria a maneira mais rápida de o relatório e a receita começarem a discordar.
+ *
+ * `admitted` é o conjunto de arquivos de estilo que pertencem a componente que o escopo admite. É
+ * o que separa "esta forma não é lida" de "esta forma é lida e este componente não entra" - dois
+ * fatos diferentes que, somados num número só, fizeram 36% parecer defeito de leitura quando era
+ * o portão funcionando (dono, 04/08).
+ */
+export function judgeFragments(seen, declared, admitted) {
+    return seen.map((f) => {
+        if (f.reason)
+            return f;
+        switch (f.shape) {
+            case "class":
+            case "template": {
+                /**
+                 * UMA INTERPOLAÇÃO DE MODULE NÃO É UMA LACUNA. `` `${styles.card} ${styles.open}` `` é
+                 * classe de CSS module, e o valor dela está no arquivo de estilo - que a esteira lê. São
+                 * 262 dos 277 templates não lidos do dashboard dele (95%), e reportá-los como valor não
+                 * lido inventa uma lacuna onde a captura está completa por outra forma. Um relatório com
+                 * lacuna falsa custa o mesmo que um com lacuna escondida: manda alguém consertar o que
+                 * não está quebrado (medido, 04/08).
+                 */
+                const modules = f.text.match(MODULE_REF) ?? [];
+                const literal = f.text
+                    .replace(MODULE_REF, " ")
+                    .replace(/\$\{[^}]*\}/g, " ");
+                /**
+                 * Sem literal nenhum: ou o module responde por tudo, ou o que sobrou é `${className}` -
+                 * um valor que só existe em tempo de execução, e o motivo disso é `computed`, nunca
+                 * "valor não lido". A esteira não viu valor algum para não ler.
+                 */
+                if (f.shape === "template" && !/[a-z]/i.test(literal))
+                    return modules.length > 0
+                        ? { ...f, read: true }
+                        : { ...f, read: false, reason: "computed" };
+                const t = transcribe(literal.split(/\s+/).filter(Boolean), declared);
+                const read = Object.keys(t.base).length +
+                    Object.keys(t.dark).length +
+                    Object.values(t.states ?? {}).reduce((n, b) => n + Object.keys(b).length, 0) >
+                    0;
+                return read
+                    ? { ...f, read: true }
+                    : { ...f, read: false, reason: "value-not-read" };
+            }
+            case "inline": {
+                const read = Object.keys(readInlineStyle(`style={{${f.text}}}`)).length > 0;
+                return read
+                    ? { ...f, read: true }
+                    : { ...f, read: false, reason: "computed" };
+            }
+            case "css":
+                return admitted.has(f.file)
+                    ? { ...f, read: true }
+                    : {
+                        ...f,
+                        read: false,
+                        reason: "component-not-admitted",
+                    };
+            default:
+                return { ...f, read: false, reason: "shape-not-read" };
+        }
+    });
+}

package/dist/doctor/style-ledger.js

@@ -0,0 +1,146 @@
+/**
+ * O LEDGER DE ESTILO: todo fragmento que carrega aparência, contabilizado.
+ *
+ * A esteira sempre soube dizer o que ela LÊ. O que ela nunca soube dizer é o que ela viu e não
+ * leu, onde aquilo mora, e quanto disso existe - e sem isso não existe ciclo de conserto: alguém
+ * precisa reportar, e um cliente que importou uma vez e foi embora nunca reporta (dono, 04/08).
+ *
+ * Medido no dashboard dele: 20 541 fragmentos que carregam estilo, 3,0 MB se guardados verbatim -
+ * do mesmo tamanho da fonte inteira. Guardar tudo seria dobrar o censo para reter o que a
+ * interpretação já extraiu.
+ *
+ * ENTÃO A CONTABILIDADE É ESTA, e ela é o que "sem perda" significa aqui:
+ *
+ *     contado        todo fragmento entra num total, por forma. Nada é invisível.
+ *     interpretado   o valor dele já vive no look, que é de onde a receita lê
+ *     não lido       o TEXTO vem verbatim, com arquivo e linha, agrupado por forma e motivo
+ *
+ * Um fragmento interpretado não precisa do texto original, porque a gente tem a interpretação; um
+ * não lido só serve com o texto e o lugar. O resultado pesa quilobytes, é acionável linha por
+ * linha, e nunca guarda o arquivo inteiro de ninguém - que é a resposta que a gente quer poder
+ * dar, olhando o schema, quando um cliente perguntar se guardamos o código dele.
+ *
+ * O QUE ELE NÃO PROMETE: 100% de interpretação. `className={cx(getVariant(props))}` monta a
+ * classe em tempo de execução e ela não existe na fonte, em nenhum nível. A promessa é 100%
+ * CONTABILIZADO - todo fragmento ou interpretado ou listado com motivo, arquivo e linha - com a
+ * interpretação como um número que se move. Dizer 100% de cobertura existindo uma classe
+ * calculada em runtime seria exatamente a mentira que esta esteira existe para não contar.
+ */
+const SHAPES = [
+    "class",
+    "template",
+    "inline",
+    "css",
+    "sx",
+    "styled",
+    "runtime",
+];
+/**
+ * Como cada forma se chama no terminal. É cópia do RELATÓRIO, não do contrato: a tela da
+ * plataforma escreve a sua própria (o dado que viaja é a chave da forma), porque uma linha de
+ * terminal alinhada em coluna e um rótulo de painel não são o mesmo texto.
+ */
+const SHAPE_LABEL = {
+    class: "class lists",
+    template: "template strings",
+    inline: "style={{ }}",
+    css: "stylesheet declarations",
+    sx: "sx props",
+    styled: "styled-components",
+    runtime: "classes built at runtime",
+};
+const BECAUSE = {
+    "shape-not-read": "no reader in this version understands this shape, so the styles it holds reach no recipe",
+    "value-not-read": "the shape is read and this value is not - a utility or property outside the scales this project declares",
+    computed: "the value is assembled at render time, so it is not in the source at any level and there is nothing to read",
+    "component-not-admitted": "read, and it belongs to a component this scope does not admit into the system - the styles exist and no recipe claims them",
+};
+/**
+ * O ledger de uma varredura, a partir dos fragmentos vistos.
+ *
+ * Puro: quem chama junta os fragmentos onde já abre os arquivos, e isto só conta e agrupa. O
+ * texto de um fragmento LIDO é descartado aqui de propósito - a interpretação dele já vive no
+ * look, e reter as duas cópias é o que dobraria o censo.
+ */
+export function buildLedger(cli, seen) {
+    const counted = blank();
+    const interpreted = blank();
+    const groups = new Map();
+    for (const f of seen) {
+        counted[f.shape] += 1;
+        if (f.read) {
+            interpreted[f.shape] += 1;
+            continue;
+        }
+        const reason = f.reason ?? "shape-not-read";
+        const key = `${f.shape}:${reason}`;
+        const group = groups.get(key) ?? {
+            shape: f.shape,
+            reason,
+            uses: 0,
+            files: 0,
+            because: BECAUSE[reason],
+            examples: [],
+            seenFiles: new Set(),
+        };
+        group.uses += 1;
+        group.seenFiles.add(f.file);
+        if (group.examples.length < 3 &&
+            !group.examples.some((e) => e.file === f.file))
+            group.examples.push({
+                file: f.file,
+                line: f.line,
+                text: f.text.replace(/\s+/g, " ").trim().slice(0, 160),
+            });
+        groups.set(key, group);
+    }
+    return {
+        cli,
+        counted,
+        interpreted,
+        unread: [...groups.values()]
+            .map(({ seenFiles, ...group }) => ({ ...group, files: seenFiles.size }))
+            .sort((a, b) => b.uses - a.uses),
+    };
+}
+function blank() {
+    return Object.fromEntries(SHAPES.map((s) => [s, 0]));
+}
+/**
+ * O relatório, na ordem em que uma pessoa decide se aquilo a incomoda.
+ *
+ * Lidera com o que foi CONTABILIZADO, porque é a única promessa que a esteira pode cumprir, e
+ * nomeia cada lacuna com o número do repo dela. Um percentual sem a contagem atrás é número de
+ * marketing, e um zero sem motivo lê como falha nossa.
+ */
+export function describeLedger(l) {
+    const total = sum(l.counted);
+    if (total === 0)
+        return [];
+    const read = sum(l.interpreted);
+    const lines = [
+        `${total} style fragments in your files, and every one is accounted for: ${read} interpreted (${Math.round((read / total) * 100)}%), ${total - read} listed below with the file and line where each lives.`,
+    ];
+    /**
+     * POR FORMA, ANTES DOS GRUPOS. O total responde "quanto"; esta tabela responde "de que jeito o
+     * projeto escreve estilo", que é a pergunta que decide qual leitor vale construir. Sem ela, 56%
+     * num app dominado por CSS Modules e 56% num app de Tailwind leem igual e pedem trabalhos
+     * opostos.
+     */
+    for (const shape of SHAPES) {
+        const seen = l.counted[shape];
+        if (seen === 0)
+            continue;
+        const got = l.interpreted[shape];
+        lines.push(`  ${SHAPE_LABEL[shape].padEnd(28)} ${String(seen).padStart(6)} seen  ${String(got).padStart(6)} interpreted${got === seen ? "" : `  (${seen - got} listed below)`}`);
+    }
+    for (const g of l.unread) {
+        lines.push(`  ${g.uses} ${g.shape}${g.uses === 1 ? "" : "s"} in ${g.files} file${g.files === 1 ? "" : "s"} - ${g.because}`);
+        for (const e of g.examples)
+            lines.push(`      ${e.file}:${e.line}  ${e.text.slice(0, 80)}`);
+    }
+    return lines;
+}
+function sum(counts) {
+    return Object.values(counts).reduce((n, k) => n + k, 0);
+}

package/dist/index.js

@@ -180,6 +180,8 @@ async function main() {
             // The census is arithmetic over their files; --dry keeps it on disk.
             await runImport({
                 root: dir,
+                /** A versão que mediu, para o ledger - ver `StyleLedger.cli`. */
+                cli: CLI_VERSION,
                 dry: flags.dry === true,
                 census: typeof flags.census === "string" ? flags.census : undefined,
                 name: typeof flags.name === "string" ? flags.name : undefined,

package/package.json

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