synthesisui 0.16.165 → 0.16.167

package/dist/commands/import.js

@@ -21,6 +21,7 @@ import { describeConvention, describeRemainder, detectConventions, } from "../do
 import { pageLaws } from "../doctor/page-laws.js";
 import { callSiteNode, placeLayers, } from "../doctor/place-layers.js";
 import { publicApi, requiredProps } from "../doctor/public-api.js";
+import { aliasesOf, describeReachability, edgesIn, reachabilityOf, } from "../doctor/reachability.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
@@ -973,12 +974,23 @@ export async function takeCensus(root, opts) {
         .then((raw) => JSON.parse(raw).name ?? null)
         .catch(() => null);
     const shared = scopePkg ? [...internal, scopePkg] : internal;
+    /**
+     * O GRAFO DE IMPORTS DA EVIDÊNCIA, montado no laço que já abre cada arquivo.
+     *
+     * O `--usage` doa CONTAGEM e LEI, então código que nenhuma rota atinge vota nas leis do cliente -
+     * 180 de 966 arquivos no repo do dono (07/08). Refazer a varredura para montar o grafo seria
+     * percorrer o repo inteiro de novo por um dado que este laço já tem na mão. Ver `reachability.ts`.
+     */
+    const edges = new Map();
+    const aliases = [];
     for (const u of opts?.usage ?? []) {
         const uInternal = await internalSpecifiers(u.path);
+        aliases.push(...(await aliasesOf(u.path)));
         for await (const file of walk(u.path)) {
             const src = await readFile(file, "utf8").catch(() => "");
             if (!src)
                 continue;
+            edges.set(file, edgesIn(src));
             const rel = join(u.label, relative(u.path, file));
             if (/(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/.test(rel)) {
                 continue;
@@ -1215,6 +1227,11 @@ export async function takeCensus(root, opts) {
      *
      * `componentFiles` segue existindo para as formas de estilo, que SÃO por arquivo.
      */
+    /**
+     * O GRAFO SÓ FECHA DEPOIS QUE TODOS OS ARQUIVOS FORAM VISTOS: um especificador só resolve para um
+     * arquivo que já esteja na lista, então isto não pode rodar dentro do laço que a preenche.
+     */
+    const reachability = edges.size > 0 ? await reachabilityOf({ edges, aliases }) : null;
     const coverage = summarizeCoverage(shapes, defined.length || componentFiles, Object.keys(looks).length, Object.values(looks).reduce((n, look) => n +
         Object.keys(look.base).length +
         Object.keys(look.dark ?? {}).length +
@@ -1350,6 +1367,25 @@ export async function takeCensus(root, opts) {
         for (const line of coverageLines)
             console.log(body(line));
     }
+    /**
+     * O QUE VOTA NAS LEIS DELE SEM ESTAR VIVO - dito, e nada excluído.
+     *
+     * Lei 7 do `CLAUDE.md`: o que a esteira não sabe tratar se DECLARA, com o número do repo dele, no
+     * momento do censo. Silêncio sobre uma lacuna é o que faz um produto correto parecer quebrado - e
+     * aqui o silêncio custava mais que aparência, porque as leis saíam distorcidas sem ninguém saber.
+     */
+    const reachLines = reachability ? describeReachability(reachability) : [];
+    if (reachLines.length > 0) {
+        console.log("");
+        console.log(section("What no route reaches"));
+        for (const line of reachLines)
+            console.log(body(line));
+        if (reachability && reachability.unreached.length > 0)
+            console.log(body(paint.faint(`${reachability.unreached
+                .slice(0, 4)
+                .map((f) => relative(root, f))
+                .join(", ")}${reachability.unreached.length > 4 ? `, and ${reachability.unreached.length - 4} more` : ""} - the full list travels in the census, and nothing was left out because of it`)));
+    }
     /**
      * WHAT THE GATE TURNED AWAY - said out loud, grouped, with the reason.
      *
@@ -1622,6 +1658,17 @@ export async function takeCensus(root, opts) {
          * ninguém ter que reportar (dono, 04/08).
          */
         ledger,
+        /**
+         * O QUE NENHUMA ROTA ATINGE, entre os arquivos que doam evidência.
+         *
+         * O `--usage` não doa token nem componente - doa CONTAGEM e LEI, que é o que transforma uma
+         * escolha assentada numa lei que governa. Então código morto ali VOTA nas leis do cliente, e
+         * até 07/08 nada contava: 180 de 966 arquivos no repo do dono.
+         *
+         * Viaja com o censo e NÃO exclui nada. Ver `reachability.ts` para o motivo de ser um grafo e não
+         * uma regra de nome - `_legacy` tinha 178 arquivos e 106 deles estavam vivos.
+         */
+        ...(reachability ? { reachability } : {}),
         /**
          * A ESCALA QUE O `sx` DELES USA, só quando eles declaram uma diferente do default do MUI.
          * Medida no censo e consumida pela derivação - ver `readSxProps`.

package/dist/doctor/reachability.js

@@ -0,0 +1,293 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+/**
+ * OS NOMES QUE O ROTEADOR MONTA SOZINHO.
+ *
+ * Um arquivo com um destes nomes é uma porta de entrada mesmo que ninguém o importe - é o framework
+ * que o monta. Sem esta lista, um app inteiro sairia como inalcançável a partir do nada.
+ */
+const ENTRY = /\/(page|layout|route|template|default|loading|error|not-found|global-error|middleware|instrumentation)\.[jt]sx?$/;
+const EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+/**
+ * Os especificadores que um arquivo importa - estáticos, re-exports e dinâmicos.
+ *
+ * Re-export conta: um barril (`export { X } from "./x"`) é o caminho pelo qual metade dos projetos
+ * chega nos próprios componentes, e ignorá-lo transformaria uma pasta inteira em morta.
+ */
+export function edgesIn(source) {
+    const out = [];
+    for (const re of [
+        /\bfrom\s+["']([^"']+)["']/g,
+        /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g,
+        /\brequire\s*\(\s*["']([^"']+)["']\s*\)/g,
+        /\bimport\s+["']([^"']+)["']/g,
+    ])
+        for (const m of source.matchAll(re))
+            out.push(m[1]);
+    return out;
+}
+/**
+ * Os apelidos que o projeto declara - `paths` do tsconfig, que é onde `@/` mora.
+ *
+ * Sem eles, um projeto que importa tudo por `@/components/...` lê como um grafo sem aresta nenhuma,
+ * e a medição diria que o app inteiro está morto. Ler o `tsconfig` é a diferença entre uma medição e
+ * um alarme.
+ */
+/**
+ * Tira comentários de um tsconfig SEM ATRAVESSAR STRING - e essa ressalva é o ponto inteiro.
+ *
+ * A primeira versão era um `replace` de duas regex, e ela comia o próprio alias que veio buscar:
+ * `"@/*"` - o apelido padrão de qualquer projeto Next - começa com `/*`, que lê como abertura de
+ * bloco. O parser engolia dali até o primeiro `*` `/` adiante, o JSON quebrava, e a função devolvia
+ * zero alias. Consequência: todo `@/…` deixava de resolver e o app inteiro saía como código morto
+ * (07/08, 1573 arestas perdidas no app do dono).
+ *
+ * Um erro de leitura NOSSO virando uma acusação sobre o código de alguém é o pior modo de falha que
+ * esta esteira tem, e é por isso que o scanner sabe onde uma string começa e acaba.
+ */
+function withoutComments(raw) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < raw.length; i += 1) {
+        const c = raw[i];
+        const next = raw[i + 1];
+        if (inString) {
+            out += c;
+            if (c === "\\") {
+                out += next ?? "";
+                i += 1;
+            }
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            continue;
+        }
+        if (c === "/" && next === "/") {
+            while (i < raw.length && raw[i] !== "\n")
+                i += 1;
+            out += "\n";
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            i += 2;
+            while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i += 1;
+            i += 1;
+            continue;
+        }
+        out += c;
+    }
+    return out;
+}
+export async function aliasesOf(root) {
+    return readAliases(join(root, "tsconfig.json"), 0);
+}
+/**
+ * Lê um tsconfig POR CAMINHO DE ARQUIVO, e é isso que faz o `extends` funcionar.
+ *
+ * A primeira versão pegava o diretório do arquivo apontado e voltava a procurar `tsconfig.json` nele
+ * - então um `extends: "../../tsconfig.base.json"` lia o `tsconfig.json` da raiz, que não existe, e
+ * devolvia zero alias. No app do dono isso fazia todo `@/…` deixar de resolver: 1053 arestas
+ * perdidas, e o app inteiro lendo como morto (07/08).
+ */
+async function readAliases(path, 
+/** Guarda contra `extends` circular, e contra uma cadeia que ninguém pretendia seguir. */
+depth) {
+    if (depth > 4)
+        return [];
+    const raw = await readFile(path, "utf8").catch(() => "");
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(withoutComments(raw));
+    }
+    catch {
+        return [];
+    }
+    const here = dirname(path);
+    const inherited = parsed.extends?.startsWith(".")
+        ? await readAliases(resolve(here, parsed.extends), depth + 1)
+        : [];
+    /**
+     * `paths` é relativo ao `baseUrl` DO ARQUIVO QUE O DECLARA - um base config na raiz aponta para as
+     * pastas a partir da raiz, e resolvê-lo a partir do app daria um caminho que não existe.
+     */
+    const base = resolve(here, parsed.compilerOptions?.baseUrl ?? ".");
+    const own = Object.entries(parsed.compilerOptions?.paths ?? {}).map(([from, to]) => ({
+        prefix: from.replace(/\*$/, ""),
+        to: to.map((t) => resolve(base, t.replace(/\*$/, ""))),
+    }));
+    /** O do próprio projeto vence o herdado, que é a regra do TypeScript. */
+    return [...own, ...inherited];
+}
+/**
+ * Parece um caminho DESTE repo, e não um pacote?
+ *
+ * `@/x`, `~/x` e `#x` são as três formas de apelido local que aparecem na prática, e nenhuma é um
+ * pacote npm válido - um escopo real é `@escopo/nome`. Existe para o contador de `unresolved` pegar
+ * o caso em que a configuração de alias falhou: sem isto, um `@/` sem alias casado era descartado em
+ * silêncio, e o número de mortos subia sem a ressalva que devia acompanhá-lo.
+ */
+export function looksLocal(spec) {
+    return /^(\.|~\/|#)/.test(spec) || /^@\//.test(spec);
+}
+/**
+ * Um import de ASSET não é uma aresta de código.
+ *
+ * `import "./globals.css"` e `import logo from "./logo.png"` são reais e não fazem componente nenhum
+ * ficar vivo. Contá-los como aresta perdida inflava a ressalva que qualifica todo o resto - e uma
+ * ressalva inflada é tão inútil quanto uma ausente.
+ */
+const ASSET = /\.(css|scss|sass|less|styl|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|otf|mp4|webm|json|md|txt|ya?ml|graphql|wasm)$/i;
+/**
+ * Existe como arquivo? Com memória, porque a mesma resposta é pedida centenas de vezes.
+ *
+ * Cada especificador tenta até treze candidatos (o base, seis extensões, seis `index`), e um barril
+ * importado por cem arquivos repete os mesmos treves `stat` cem vezes. Sem isto, medir um app de 1446
+ * arquivos passava de três segundos - e um leitor que roda dentro de todo import não pode pagar isso
+ * por um dado que não muda durante a rodada.
+ */
+function fileChecker() {
+    const known = new Map();
+    return (path) => {
+        const seen = known.get(path);
+        if (seen)
+            return seen;
+        const asked = stat(path).then((s) => s.isFile(), () => false);
+        known.set(path, asked);
+        return asked;
+    };
+}
+/** Um especificador vira um arquivo real, ou nada. `null` é contado, nunca engolido. */
+async function toFile(known, from, spec, aliases, isFile) {
+    const bases = [];
+    if (spec.startsWith("."))
+        bases.push(resolve(dirname(from), spec));
+    else
+        for (const a of aliases)
+            if (spec.startsWith(a.prefix))
+                for (const t of a.to)
+                    bases.push(join(t, spec.slice(a.prefix.length)));
+    if (bases.length === 0)
+        return null;
+    for (const base of bases)
+        for (const candidate of [
+            base,
+            ...EXTS.map((e) => base + e),
+            ...EXTS.map((e) => join(base, `index${e}`)),
+        ]) {
+            if (known.has(candidate))
+                return candidate;
+            /**
+             * Fora da lista varrida ainda pode existir: um alias que aponta para outro pacote do monorepo,
+             * ou um `.js` que o walk deste escopo não coletou. O próprio `base` entra no teste - um alias
+             * que aponta DIRETO para um arquivo (`"@x/core": ["packages/core/src/index.ts"]`) não tem
+             * sufixo nenhum, e pular o base fazia esse caso nunca resolver.
+             */
+            if (await isFile(candidate))
+                return candidate;
+        }
+    return null;
+}
+/**
+ * Quem o roteador alcança, e quem não.
+ *
+ * `edges` chega já coletado pelo laço que já abriu cada arquivo - refazer a leitura para montar o
+ * grafo seria uma segunda varredura do repo inteiro por um dado que a primeira já tinha na mão.
+ */
+export async function reachabilityOf(input) {
+    /**
+     * O UNIVERSO É CÓDIGO-FONTE, e não tudo que tem extensão.
+     *
+     * `.d.ts` são declarações de tipo e `next.config.js`/`tailwind.config.ts` são configuração: nenhum
+     * é montado por uma rota e nenhum doa evidência sobre como o produto usa o sistema. Contá-los
+     * inflava o denominador com arquivos que são inalcançáveis por definição - 2090 no lugar de 966 no
+     * app do dono (07/08), e um número inflado no denominador é uma acusação inflada no numerador.
+     */
+    const isFile = fileChecker();
+    const known = new Set([...input.edges.keys()].filter((f) => /\.[jt]sx?$/.test(f) &&
+        !/\.d\.ts$/.test(f) &&
+        !/\/[a-z.-]+\.config\.[jt]sx?$/.test(f)));
+    const graph = new Map();
+    let unresolved = 0;
+    for (const [file, specs] of input.edges) {
+        if (!known.has(file))
+            continue;
+        const out = [];
+        for (const spec of specs) {
+            const mine = spec.startsWith(".") ||
+                input.aliases.some((a) => spec.startsWith(a.prefix));
+            /**
+             * Pacote de terceiro não é aresta deste repo. Mas um apelido LOCAL que nenhum alias casa é uma
+             * aresta PERDIDA - e era descartado aqui em silêncio, o que subia o número de mortos sem a
+             * ressalva que devia vir junto (07/08).
+             */
+            if (!mine) {
+                if (looksLocal(spec) && !ASSET.test(spec))
+                    unresolved += 1;
+                continue;
+            }
+            const hit = await toFile(known, file, spec, input.aliases, isFile);
+            if (hit)
+                out.push(hit);
+            /**
+             * Asset que não resolve não é aresta perdida - ver `ASSET`. A tentativa acontece assim mesmo,
+             * porque um `./styles.css` que EXISTE é um nó legítimo do grafo, e recusá-lo antes de tentar
+             * derrubou 300 arquivos alcançados na primeira versão desta linha (07/08).
+             */ else if (!ASSET.test(spec))
+                unresolved += 1;
+        }
+        graph.set(file, out);
+    }
+    const entries = [...known].filter((f) => ENTRY.test(f));
+    const seen = new Set();
+    const queue = [...entries];
+    while (queue.length > 0) {
+        const file = queue.pop();
+        if (!file || seen.has(file))
+            continue;
+        seen.add(file);
+        for (const next of graph.get(file) ?? [])
+            if (!seen.has(next))
+                queue.push(next);
+    }
+    return {
+        entries: entries.length,
+        files: known.size,
+        reached: seen.size,
+        unreached: [...known].filter((f) => !seen.has(f)).sort(),
+        unresolved,
+    };
+}
+/**
+ * A frase, e ela QUALIFICA o número antes de o dar.
+ *
+ * Um "19% do que vota nas suas leis é código morto" sem a ressalva do `unresolved` é uma afirmação
+ * que quem lê não tem como checar - e a primeira coisa que alguém faz com um número desses é apagar
+ * arquivo. A ordem aqui é deliberada: o que foi contado, depois o que a contagem não soube ver.
+ */
+export function describeReachability(r) {
+    if (r.files === 0 || r.entries === 0)
+        return [];
+    const dead = r.unreached.length;
+    if (dead === 0)
+        return [
+            `Every one of the ${r.files} files behind your evidence is reached from one of its ${r.entries} entry points - nothing dead is voting on your laws.`,
+        ];
+    const pct = Math.round((dead / r.files) * 100);
+    const out = [
+        `${dead} of ${r.files} files (${pct}%) are not reached from any of the ${r.entries} entry points this app declares - they are counted as evidence, which means dead code is voting on which of your choices became laws.`,
+    ];
+    /**
+     * A RESSALVA VIAJA COM O NÚMERO, sempre - e o corte é 5% dos especificadores. Acima disso o grafo
+     * perdeu arestas demais para a palavra "morto" significar alguma coisa.
+     */
+    if (r.unresolved > 0)
+        out.push(`${r.unresolved} import${r.unresolved === 1 ? "" : "s"} could not be resolved to a file, so that count is a CEILING and not a measurement: an import this reader cannot follow turns living code into "dead". Nothing was excluded on account of it.`);
+    return out;
+}

package/package.json

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