synthesisui 0.16.131 → 0.16.133

package/dist/commands/import.js

@@ -16,7 +16,9 @@ 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";
 import { publicApi, requiredProps } from "../doctor/public-api.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
@@ -24,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";
@@ -125,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;
 }
@@ -254,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 = [];
@@ -263,6 +284,14 @@ export async function takeCensus(root, opts) {
     const defined = [];
     /** Nome → arquivo e fonte, para toda leitura por componente - ver o preenchimento abaixo. */
     const sourceOf = new Map();
+    /** Nome → o que a peça é, quando o portão soube dizer. Ver `CensusLook.kind`. */
+    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
@@ -308,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.
      *
@@ -391,9 +417,33 @@ export async function takeCensus(root, opts) {
                     internal,
                 });
                 if (verdict.ok) {
-                    found.push(d);
+                    /**
+                     * O QUE A PEÇA É viaja com ela - ver `GateVerdict.kind`. Um template decide arranjo e
+                     * não aparência, e três superfícies precisam saber disso para não cobrar cor de quem
+                     * nunca prometeu cor.
+                     */
+                    found.push(verdict.kind ? { ...d, kind: verdict.kind } : d);
                     continue;
                 }
+                /**
+                 * A RAIZ DE UMA PÁGINA E O QUE ELA COMPÕE, para as leis - ver `pageLaws`.
+                 *
+                 * Uma rota individualmente não vale receita: 5 elementos de média e a raiz repetindo o
+                 * que outras oito já disseram. Juntas elas dizem como é a casca deste projeto, que é o
+                 * que falta para alguém escrever a próxima (04/08).
+                 */
+                if (verdict.why === "route" || verdict.why === "screen") {
+                    const sketch = sketchOf(src, d.name);
+                    const root = sketch[0];
+                    pages.push({
+                        root: root?.classes
+                            ? transcribe(root.classes.split(/\s+/).filter(Boolean), declaredValues).base
+                            : {},
+                        composes: sketch
+                            .filter((n) => /^[A-Z]/.test(n.tag))
+                            .map((n) => n.tag.split(".")[0]),
+                    });
+                }
                 skips.push({
                     name: d.name,
                     file: rel,
@@ -426,8 +476,17 @@ 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.
              */
-            for (const d of found)
+            /**
+             * 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`. */
+                if (d.kind)
+                    kindOf.set(d.name, d.kind);
+            }
             // THE LOOK, from their own class names. One transcription per file, keyed
             // by the component it defines - the root element's classes are the
             // component's own look, and everything below it is a part this slice does
@@ -511,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)
@@ -733,6 +796,18 @@ export async function takeCensus(root, opts) {
     if (hasScreens) {
         const keep = [];
         for (const d of defined) {
+            /**
+             * UM TEMPLATE VIVE NUMA TELA SÓ POR DEFINIÇÃO - ele É a tela.
+             *
+             * A regra de duas telas existe para separar "decisão que o produto compartilha" de
+             * "markup daquela tela", e está certa para uma PEÇA. Aplicada a um template ela recusa
+             * exatamente o que o portão acabou de aceitar: as 16 telas do dashboard dele passavam o
+             * portão como `template` e caíam aqui, aparecendo no relatório como `feature` (04/08).
+             */
+            if (d.kind === "template") {
+                keep.push(d);
+                continue;
+            }
             const screens = screensOf.get(d.name)?.size ?? 0;
             if (screens >= SCREENS_FOR_SYSTEM) {
                 keep.push(d);
@@ -1107,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("");
@@ -1126,6 +1208,26 @@ export async function takeCensus(root, opts) {
      * The skill asks which has priority; the chosen one becomes a system-wide rule that
      * reaches CLAUDE.md, so every prompt after this respects where a new component goes.
      */
+    /**
+     * 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("");
+        console.log(section("What your pages agree on"));
+        for (const law of pageRules) {
+            console.log(body(law.text));
+            console.log(body(paint.faint(`  ${law.evidence}`)));
+        }
+    }
     if (architectures.length > 0) {
         console.log("");
         console.log(section("How this project is organised"));
@@ -1332,8 +1434,12 @@ export async function takeCensus(root, opts) {
         if (c)
             c.api = stamped;
         const look = looks[name];
-        if (look)
+        if (look) {
             look.api = stamped;
+            const kind = kindOf.get(name);
+            if (kind)
+                look.kind = kind;
+        }
     }
     const brokenRefs = findBrokenRefs(sources, declaredNames);
     const conventions = detectConventions(sources);
@@ -1354,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.
          *
@@ -2414,6 +2528,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/component-gate.js

@@ -43,6 +43,19 @@ const RESERVED_FILE_OTHER = /(^|[/\\])(\+page|\+layout|\+server|_app|_document|_
  * hundred libraries. It only counts when the file itself is a route.
  */
 const SCREEN_SUFFIX = /(Page|Screen|Route|Template|Layout)$/;
+/**
+ * Quantos elementos uma tela tem e quantos deles são peça de alguém - o que separa um template
+ * de uma casca. Contado no arquivo, sem sketch: este portão roda antes de qualquer leitura.
+ */
+function screenShape(source, name) {
+    const at = source.indexOf(name);
+    const body = at === -1 ? source : source.slice(at);
+    const tags = [...body.matchAll(/<([A-Za-z][\w.]*)/g)].map((m) => m[1]);
+    return {
+        nodes: tags.length,
+        composes: new Set(tags.filter((t) => /^[A-Z]/.test(t)).map((t) => t.split(".")[0])).size,
+    };
+}
 /** Something that carries context down the tree rather than drawing. */
 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
@@ -174,11 +187,22 @@ export function gateComponent(input) {
             because: `\`${file}\` is a file name the framework reserves - it is a route, not a component somebody can import`,
         };
     }
+    /**
+     * UMA TELA ENTRA COMO TEMPLATE, e o que decide é o que ela FAZ.
+     *
+     * O nome é a pista (`…Template`, `…Screen`, `…Page`) e não a prova: uma tela que compõe três
+     * ou mais peças numa árvore de dez ou mais nós é uma decisão de arranjo que vale receita -
+     * `CurateTemplate` tem 89 nós e 237 declarações. Uma que não alcança isso é casca, e casca é
+     * lei, não peça.
+     */
     if (SCREEN_SUFFIX.test(name)) {
+        const shape = screenShape(source, name);
+        if (shape.composes >= 3 && shape.nodes >= 10)
+            return { ok: true, kind: "template" };
         return {
             ok: false,
             why: "screen",
-            because: `\`${name}\` names a whole screen or the frame around one. A design system is made of the pieces a screen is built FROM`,
+            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)) {

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/page-laws.js

@@ -0,0 +1,106 @@
+/**
+ * O QUE AS PÁGINAS DE UM APP CONCORDAM, quando nenhuma delas vale uma receita.
+ *
+ * As 129 rotas do dashboard dele têm média de 5 elementos e 2 peças compostas, e a raiz de uma
+ * repete o que outras oito já disseram. Cada uma individualmente não tem o que uma receita
+ * carrega - virar 129 entradas na vitrine seria o problema de escala sem o benefício.
+ *
+ * Mas juntas elas dizem uma coisa que hoje não existe em lugar nenhum do sistema. Medido nas 129
+ * (04/08):
+ *
+ *     width: 100%              12 páginas
+ *     position: sticky          8      ┐
+ *     top: 0                    8      ├ juntos: o cabeçalho fixo de página
+ *     z-index: 50               8      ┘
+ *     padding: 1rem             8
+ *     min-height: 100vh         6        a casca da página
+ *     ContentWrapper           22 páginas compõem
+ *     PageHeader               14
+ *
+ * Três ou mais arquivos concordando é hábito - a mesma escada que o resto da esteira usa. E uma
+ * lei com a contagem atrás vale mais que a receita de qualquer uma das 129, porque é isso que
+ * alguém precisa saber para escrever a 130ª.
+ *
+ * O QUE ELA NUNCA FAZ: propor. Uma lei aqui é a descrição do que eles já fazem, com o número, e
+ * o que NÃO se repete não vira lei - duas páginas concordando é coincidência, e chamar isso de
+ * convenção do projeto seria inventar uma decisão que ninguém tomou.
+ */
+/** O mínimo para um hábito, e é o mesmo número que o resto da esteira usa. */
+const AGREE = 3;
+/** Propriedades que descrevem a MOLDURA de uma página, e não a aparência de uma peça. */
+const SHELL = /^(minHeight|height|width|maxWidth|padding|paddingTop|paddingBottom|margin|marginTop|display|gridTemplateColumns|gap|position|top|zIndex|overflow|justifyContent|alignItems)$/;
+/**
+ * As leis que as páginas de um escopo concordam, ou nada quando não concordam.
+ *
+ * `pages` é uma entrada por página: o que a RAIZ dela declara e quais peças ela compõe. Quem
+ * chama já leu as duas coisas para o relatório do portão, então isto não abre nenhum arquivo.
+ */
+export function pageLaws(pages) {
+    if (pages.length < AGREE)
+        return [];
+    const values = new Map();
+    const composed = new Map();
+    for (const page of pages) {
+        for (const [prop, value] of Object.entries(page.root)) {
+            if (!SHELL.test(prop))
+                continue;
+            const key = `${prop}: ${value}`;
+            values.set(key, (values.get(key) ?? 0) + 1);
+        }
+        for (const name of new Set(page.composes))
+            composed.set(name, (composed.get(name) ?? 0) + 1);
+    }
+    const agreed = [...values.entries()]
+        .filter(([, n]) => n >= AGREE)
+        .sort((a, b) => b[1] - a[1]);
+    const laws = [];
+    /**
+     * A CASCA: o que a raiz de uma página deste projeto declara. Uma altura mínima de viewport e um
+     * padding de container não são a aparência de uma peça - são a moldura, e é o que falta a quem
+     * vai escrever a próxima página.
+     */
+    const shell = agreed.filter(([key]) => !/^(position|top|zIndex):/.test(key));
+    if (shell.length > 0) {
+        laws.push({
+            text: `A page of this project is ${shell
+                .slice(0, 4)
+                .map(([key]) => `\`${key}\``)
+                .join(", ")}` +
+                `${composed.size > 0 && (composed.get(topOf(composed)) ?? 0) >= AGREE ? ` and puts its content inside \`${topOf(composed)}\`` : ""}` +
+                `. Write the next one the same way, or change all of them.`,
+            applies: [],
+            kind: "implementation",
+            evidence: shell
+                .slice(0, 4)
+                .map(([key, n]) => `${key} in ${n} of ${pages.length} pages`)
+                .join("; "),
+        });
+    }
+    /**
+     * O CABEÇALHO FIXO: os três juntos são um padrão, e separados não dizem nada. Só vale como lei
+     * quando os três concordam, porque `position: sticky` sozinho pode ser qualquer coisa.
+     */
+    const sticky = agreed.filter(([key]) => /^(position: sticky|top: 0|zIndex:)/.test(key));
+    if (sticky.length >= 3) {
+        const header = [...composed.entries()]
+            .filter(([name, n]) => n >= AGREE && /header/i.test(name))
+            .sort((a, b) => b[1] - a[1])[0];
+        laws.push({
+            text: `The header of a page is ${sticky
+                .map(([key]) => `\`${key}\``)
+                .join(", ")}` +
+                `${header ? ` and it is \`${header[0]}\`` : ""}` +
+                `. A second sticky element at another z-index is how two headers end up fighting.`,
+            applies: [],
+            kind: "implementation",
+            evidence: sticky
+                .map(([key, n]) => `${key} in ${n} of ${pages.length} pages`)
+                .join("; "),
+        });
+    }
+    return laws;
+}
+/** O nome mais composto, que é o candidato a "onde o conteúdo vai". */
+function topOf(composed) {
+    return [...composed.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "";
+}

package/dist/doctor/style-ledger.js

@@ -0,0 +1,119 @@
+/**
+ * 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",
+];
+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.`,
+    ];
+    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.131",
+  "version": "0.16.133",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {