synthesisui 0.16.133 → 0.16.135

package/dist/commands/gaps.js

@@ -0,0 +1,47 @@
+/**
+ * `synthesisui gaps` - o que esta esteira NÃO leu do projeto, triado.
+ *
+ * O `import` já imprime o ledger no fim de uma execução, e é ali que a pessoa o vê uma vez. Depois
+ * disso o número fica em `_synthesisui/census.json` e não existe pergunta que se possa fazer a ele:
+ * "quanto disso é trabalho de vocês?" não tinha resposta em lugar nenhum, e sem ela o ciclo de
+ * conserto continua dependendo de alguém reportar (dono, 05/08).
+ *
+ * Não mede nada: lê o censo em disco. Medir aqui seria uma segunda leitura dos arquivos deles, com
+ * uma segunda chance de discordar do que a receita diz.
+ *
+ * E o texto que ele imprime é o que a pessoa manda para quem vai escrever o leitor - por isso ele
+ * nomeia o módulo e nunca sugere código.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describeTriage, triageLedger } from "../doctor/gap-triage.js";
+import { body, section } from "../output.js";
+export async function gaps(opts) {
+    const root = opts.dir ?? process.cwd();
+    const path = opts.census ?? join(root, "_synthesisui", "census.json");
+    const raw = await readFile(path, "utf8").catch(() => null);
+    console.log(section("What this pipeline did not read"));
+    if (!raw) {
+        console.log(body(`No census at ${path}. Run \`synthesisui import --dry\` first - that is what measures your files, and it writes the census there.`));
+        return;
+    }
+    let ledger;
+    try {
+        ledger = JSON.parse(raw).ledger;
+    }
+    catch {
+        console.log(body(`${path} is not readable JSON.`));
+        return;
+    }
+    /**
+     * UM CENSO SEM LEDGER NÃO É UM PROJETO SEM LACUNA. Ele foi medido por uma versão que não
+     * contabilizava, e dizer "0 gaps" aqui seria a mentira mais barata que este comando poderia
+     * contar.
+     */
+    if (!ledger) {
+        console.log(body(`This census was written by a CLI that did not count style fragments yet, so the numbers do not exist rather than being zero. Run \`synthesisui import --dry\` again with ${opts.cli} to measure.`));
+        return;
+    }
+    for (const line of describeTriage(triageLedger(ledger, opts.cli)))
+        console.log(body(line));
+}

package/dist/commands/import.js

@@ -1509,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

package/dist/doctor/gap-triage.js

@@ -0,0 +1,186 @@
+/**
+ * O QUE FAZER COM O QUE NÃO FOI LIDO - triado, e nem tudo é trabalho.
+ *
+ * O ledger diz quanto e onde. Essa é metade da resposta, e sozinha ela ENGANA: no dashboard do
+ * dono, 6 610 dos 8 523 fragmentos não interpretados (78%) não são lacuna de leitura nenhuma - são
+ * o portão recusando um componente e classe montada em tempo de execução. Uma pessoa olhando "56%
+ * interpretado" conclui que falta ler 44% do app e vai escrever o leitor errado (medido, 04/08).
+ *
+ * ENTÃO A TRIAGEM É ESTA, e a ordem dela é a ordem em que alguém decide:
+ *
+ *     older-cli    medido por uma versão antiga. Re-medir ANTES de qualquer conclusão -
+ *                  a lacuna pode já estar fechada e o trabalho já estar feito.
+ *     no-reader    nenhum leitor entende esta forma. É trabalho, e o módulo é nomeado.
+ *     value-gap    a forma é lida e o VALOR não. O trabalho é nas tabelas de escala,
+ *                  não num leitor novo - confundir os dois custa um módulo inteiro.
+ *     by-design    o portão recusou, ou o valor não existe na fonte. NÃO É LACUNA, e a
+ *                  triagem para aqui em vez de mandar alguém consertar o que não quebrou.
+ *
+ * O QUE ELA NUNCA FAZ: sugerir código. Ela nomeia o módulo onde o leitor mora ou moraria, e a
+ * decisão de escrever é de quem lê - a esteira opinando sobre o nosso backlog no terminal do
+ * cliente é ela falando de um assunto que não é dela (dono, 05/08).
+ */
+/**
+ * QUEM É DONO DE CADA FORMA, hoje.
+ *
+ * Nomear o módulo é a diferença entre "isto não é lido" e "isto é trabalho aqui". A forma que não
+ * tem dono ganha `null`, e um leitor novo é um módulo novo - dizer que ele "vai em transcribe"
+ * quando não vai é pior que não dizer nada.
+ */
+const OWNER = {
+    class: "src/doctor/transcribe.ts",
+    template: "src/doctor/sketch.ts (the literal halves) + src/doctor/variant-read.ts",
+    inline: "src/doctor/transcribe.ts (readInlineStyle)",
+    css: "src/doctor/css-modules.ts",
+    sx: null,
+    styled: null,
+    runtime: null,
+};
+/**
+ * O motivo decide o veredito, nunca a forma.
+ *
+ * `css` aparece nos dois lados: uma declaração de module de componente admitido é LIDA, a mesma
+ * declaração num `.css` global não tem leitor, e a de um componente que o portão não admite está
+ * lida e sem receita que a reivindique. Três destinos, uma forma - por isso o veredito lê o motivo.
+ */
+function verdictOf(reason) {
+    switch (reason) {
+        case "shape-not-read":
+            return "no-reader";
+        case "value-not-read":
+            return "value-gap";
+        default:
+            // `computed` e `component-not-admitted`: nenhum leitor muda o resultado.
+            return "by-design";
+    }
+}
+/** Onde o trabalho mora, para cada veredito - ou por que não existe trabalho. */
+function whereOf(shape, reason) {
+    switch (verdictOf(reason)) {
+        case "no-reader": {
+            /**
+             * A REGRA DE CLASSE NUM CSS GLOBAL é a lacuna de leitura mais barata que existe hoje no
+             * repo do dono - 1 520 declarações em 135 arquivos - e ela não tem dono: `css-modules.ts` lê
+             * o module (escopo garantido pelo bundler), e um global vale para toda a página.
+             */
+            const owner = shape === "css" ? null : OWNER[shape];
+            return owner
+                ? {
+                    module: owner,
+                    work: `a reader exists and does not cover this shape: ${owner}`,
+                }
+                : {
+                    module: null,
+                    work: "no module owns this shape - a reader here is a new module, and it needs an app in the corpus before it exists",
+                };
+        }
+        case "value-gap":
+            return {
+                module: "src/doctor/transcribe.ts",
+                work: "the shape is already read; what is missing is a SCALE that recognises this value - a table, not a new reader",
+            };
+        default:
+            return {
+                module: null,
+                work: reason === "component-not-admitted"
+                    ? "the gate refused the component: these styles exist and no recipe claims them. Changing that means moving the GATE - a decision about the vitrine, not a reader to write"
+                    : "the value is assembled at render time and is not in the source at any level - there is nothing to read",
+            };
+    }
+}
+/**
+ * A triagem de um ledger, contra a versão que está triando.
+ *
+ * Pura: ninguém abre arquivo aqui. O ledger já carrega tudo - inclusive a versão que o mediu, que
+ * é o campo sem o qual esta função não teria como responder a primeira pergunta.
+ */
+export function triageLedger(ledger, triagedBy) {
+    const sum = (counts) => Object.values(counts).reduce((n, k) => n + k, 0);
+    const counted = sum(ledger.counted);
+    const interpreted = sum(ledger.interpreted);
+    const unread = counted - interpreted;
+    const totals = { "no-reader": 0, "value-gap": 0, "by-design": 0 };
+    const rank = {
+        "no-reader": 0,
+        "value-gap": 1,
+        "by-design": 2,
+    };
+    const gaps = ledger.unread.map((group) => {
+        const verdict = verdictOf(group.reason);
+        totals[verdict] += group.uses;
+        const { module, work } = whereOf(group.shape, group.reason);
+        return {
+            shape: group.shape,
+            reason: group.reason,
+            verdict,
+            uses: group.uses,
+            files: group.files,
+            share: unread > 0 ? Math.round((group.uses / unread) * 100) : 0,
+            module,
+            work,
+            because: group.because,
+            examples: group.examples,
+        };
+    });
+    gaps.sort((a, b) => rank[a.verdict] - rank[b.verdict] || b.uses - a.uses);
+    return {
+        measuredBy: ledger.cli,
+        triagedBy,
+        stale: isOlder(ledger.cli, triagedBy),
+        counted,
+        interpreted,
+        percent: counted > 0 ? Math.round((interpreted / counted) * 100) : 0,
+        totals,
+        gaps,
+    };
+}
+/** `0.16.133` é mais velha que `0.16.134`. Compara número por número, e o que não é número não
+ *  desempata nada - uma pré-release não é motivo para dizer que a medição está velha. */
+function isOlder(measured, current) {
+    const parts = (v) => v.split(".").map((p) => Number.parseInt(p, 10));
+    const a = parts(measured);
+    const b = parts(current);
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const left = a[i];
+        const right = b[i];
+        if (!Number.isFinite(left) || !Number.isFinite(right))
+            return false;
+        if (left !== right)
+            return left < right;
+    }
+    return false;
+}
+/**
+ * A triagem em texto, na ordem em que uma pessoa decide.
+ *
+ * Lidera pelo que NÃO é trabalho quando ele domina, porque é o número que muda a conclusão: 78%
+ * do não interpretado ser o portão funcionando é a informação mais importante da tela, e ela vem
+ * antes de qualquer lista de tarefa.
+ */
+export function describeTriage(t) {
+    const unread = t.counted - t.interpreted;
+    const lines = [
+        `${t.counted} style fragments accounted for, ${t.interpreted} interpreted (${t.percent}%). The ${unread} below are sorted by what to do about them.`,
+    ];
+    if (t.stale) {
+        lines.push("", `MEASURED BY CLI ${t.measuredBy}, TRIAGED BY ${t.triagedBy}. Re-run \`import\` before concluding anything from the numbers below - a gap here may already be closed, and the work already done.`);
+    }
+    const label = {
+        "no-reader": "NO READER FOR THIS SHAPE - this is work",
+        "value-gap": "THE SHAPE IS READ, THE VALUE IS NOT - a scale, not a reader",
+        "by-design": "NOT A READING GAP - nothing a reader would change, and no work here",
+    };
+    for (const verdict of ["no-reader", "value-gap", "by-design"]) {
+        const group = t.gaps.filter((g) => g.verdict === verdict);
+        if (group.length === 0)
+            continue;
+        const total = t.totals[verdict];
+        lines.push("", `${label[verdict]} - ${total} fragment${total === 1 ? "" : "s"}, ${unread > 0 ? Math.round((total / unread) * 100) : 0}% of what was not interpreted`);
+        for (const gap of group) {
+            lines.push(`  ${gap.uses} ${gap.shape} in ${gap.files} file${gap.files === 1 ? "" : "s"} (${gap.share}%) - ${gap.work}`);
+            for (const example of gap.examples.slice(0, 2))
+                lines.push(`      ${example.file}:${example.line}  ${example.text.slice(0, 76)}`);
+        }
+    }
+    return lines;
+}

package/dist/doctor/style-ledger.js

@@ -35,6 +35,20 @@ const SHAPES = [
     "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",
@@ -107,6 +121,19 @@ export function describeLedger(l) {
     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)

package/dist/index.js

@@ -7,6 +7,7 @@ import { clean } from "./commands/clean.js";
 import { component } from "./commands/component.js";
 import { connect } from "./commands/connect.js";
 import { doctor } from "./commands/doctor.js";
+import { gaps } from "./commands/gaps.js";
 import { generate } from "./commands/generate.js";
 import { hook } from "./commands/hook.js";
 import { runImport } from "./commands/import.js";
@@ -48,6 +49,9 @@ Usage - governance (deterministic, FREE):
   synthesisui doctor [paths…] [--verbose]  audit for DRIFT: every design value written by hand, the
                                            token your system already has for it, coherence, and the
                                            record over time
+  synthesisui gaps [--census <p>]           what this pipeline did NOT read of your project, triaged:
+                                           a reader that is missing, a value outside your scales, or
+                                           something no reader would change
   synthesisui request [component|token]    the queue of what your agent needed and the system
                                            refused to invent (--done <id> closes one)
   synthesisui sync                         send the local record - checks, fixes, open requests -
@@ -247,6 +251,21 @@ async function main() {
                 laws: flags.laws === true,
             });
             break;
+        case "gaps":
+            /**
+             * O LEDGER JÁ ESTÁ NO CENSO - isto não mede nada, tria.
+             *
+             * Existe para que a triagem seja alcançável por uma pessoa, e não só pelo spec: quem rodou
+             * `import` uma vez tem o número em disco e nenhuma forma de perguntar "e o que eu faço com
+             * isso". O texto que sai daqui é exatamente o que ele me manda quando quer que eu escreva o
+             * leitor (dono, 05/08).
+             */
+            await gaps({
+                dir,
+                census: typeof flags.census === "string" ? flags.census : undefined,
+                cli: CLI_VERSION,
+            });
+            break;
         case "list":
             await list({ registry });
             break;

package/package.json

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