synthesisui 0.16.153 → 0.16.155

package/dist/commands/summary.js

@@ -0,0 +1,79 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { measuredScope } from "../measured-scope.js";
+import { body, paint, section, snippet } from "../output.js";
+/**
+ * `synthesisui summary <slug>` - AS QUATRO LINHAS DO PRIMEIRO MINUTO, impressas por um programa.
+ *
+ * A skill `sui-init` já mandava terminar em quatro linhas, e listava o que nunca deveria aparecer
+ * nelas: quantos arquivos foram varridos, quanto tempo levou, quais leitores rodaram, o que o ledger
+ * diz. O fechamento que o dono recebeu em 06/08 tinha ~400 palavras e violava as duas regras - com
+ * três dos quatro parágrafos falando do AGENTE e não do sistema dele:
+ *
+ *     "my notes from 2026-08-05 carry two confirmed defects"          a memoria do agente
+ *     "the generator had been deleted, so I rebuilt it"               o retrabalho do agente
+ *     "a census regression I stripped by hand"                        o conserto do agente
+ *
+ * E duas daquelas advertências estavam DESATUALIZADAS: os dois defeitos do `--fix` foram consertados
+ * na 0.16.153, então a skill assustou o usuário com um bug que não existe mais.
+ *
+ * Mais prosa proibindo não conserta isso. O que o agente tem em mãos no fim é justamente o próprio
+ * trabalho dele, e a atração de reportá-lo vence uma linha de proibição a sessenta linhas de distância.
+ * Então o fechamento sai das mãos dele: este comando sabe as contagens (o censo está no disco), sabe a
+ * versão instalada (o `.lock`), e recebe o resto por flag. Um agente que executa isto não tem o que
+ * compor - e uma anotação velha dele não tem por onde entrar.
+ *
+ * LOCAL, E NUNCA FALHA. Sem censo ele ainda diz o essencial; sem rede ele não perde nada, porque nada
+ * aqui é remoto.
+ */
+export async function summary(slug, opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const census = await readFile(join(root, "_synthesisui", "census.json"), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    const lock = await readFile(join(root, "_synthesisui", "ds", slug, ".lock"), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    const measured = await measuredScope(root);
+    const name = lock?.name ?? slug;
+    /**
+     * `looks`, NUNCA `components`.
+     *
+     * `components` é a lista de candidatos que o portão avaliou - 128 no repo do dono, contra os 36 que
+     * o sistema realmente tem. Dizer 128 no primeiro minuto é prometer quatro vezes o que foi entregue,
+     * e o número certo já estava no mesmo arquivo.
+     */
+    const components = census?.looks ? Object.keys(census.looks).length : null;
+    const tokens = census?.declared ? Object.keys(census.declared).length : null;
+    console.log(section(`${name} is yours`));
+    /**
+     * LINHA 1 - O QUE ELE TEM, nas contagens dele. Nunca "36 de 128 candidatos", nunca "2787 arquivos":
+     * o que importa no primeiro minuto é o tamanho do que ele ganhou e de onde saiu.
+     */
+    const from = measured.system ? `, read out of ${measured.system}` : "";
+    console.log(body(components != null && tokens != null
+        ? `${components} components and ${tokens} of your own tokens${from}.`
+        : `Installed${lock?.version ? ` at v${lock.version}` : ""}${from}.`));
+    /**
+     * LINHA 2 - AS DUAS VERSÕES E O CAMINHO DE VOLTA, com os números que a PLATAFORMA deu.
+     *
+     * Escrever "v1" e "v2" aqui por conta própria já esteve errado uma vez: enquanto o nascimento
+     * publicava uma baseline, o import caía na v2 e o congelamento produzia a v3. Então os números
+     * chegam por flag, e sem eles esta linha simplesmente não é dita.
+     */
+    if (opts.base != null && opts.draft != null) {
+        console.log(body(`v${opts.base} is your code as it is today${opts.fixes ? ` · v${opts.draft} adds ${opts.fixes} deterministic ${opts.fixes === 1 ? "fix" : "fixes"}` : ` · v${opts.draft} is the draft`}.`));
+        console.log(body(paint.dim(`Back to v${opts.base} is one click: /dashboard/mine/${slug}/publish`)));
+    }
+    /**
+     * LINHA 3 - O QUE FAZER AGORA, e é uma coisa só.
+     *
+     * As duas linhas de fiação são o portão de tudo o mais: sem elas nenhum token chega ao navegador e
+     * todo número seguinte é vazio. O `doctor` diz isso melhor e com o estado real, então o próximo passo
+     * é ele - não uma explicação nossa aqui.
+     */
+    console.log("");
+    console.log(body("Two lines wire it up, and `init` printed both:"));
+    console.log(body(paint.dim(`  @import "./_synthesisui/ds/${slug}/tokens.css";   and   data-ds="${slug}" on <html>`)));
+    console.log(paint.blue(snippet(["npx synthesisui@latest doctor"])));
+}

package/dist/config.js

@@ -98,12 +98,66 @@ export async function readProjectConfig(root) {
                 ? parsed.componentsDir
                 : DEFAULT_CONFIG.componentsDir,
             styles: parsed.styles === "tailwind" ? "tailwind" : "css",
+            /**
+             * A INTENÇÃO NÃO TEM DEFAULT AQUI, de propósito.
+             *
+             * Um default silencioso é uma decisão nossa vestida de decisão deles: quem não respondeu não
+             * escolheu, e o doctor tem que poder dizer "ninguém declarou" em vez de ordenar por um palpite.
+             * Quem consome isto é `intentOf`, que separa os três casos.
+             */
+            ...(parsed.intent === "migrate" || parsed.intent === "adopt"
+                ? { intent: parsed.intent }
+                : {}),
+            ...(typeof parsed.intentAt === "string" && parsed.intentAt
+                ? { intentAt: parsed.intentAt }
+                : {}),
+            /** Sem valor gravado o comando usa `system`, que é o default do produto e não uma suposição. */
+            ...(parsed.absorb === "code" || parsed.absorb === "system"
+                ? { absorb: parsed.absorb }
+                : {}),
         };
     }
     catch {
         return DEFAULT_CONFIG;
     }
 }
+/**
+ * A PRECEDÊNCIA, num lugar só: flag > config > default.
+ *
+ * E ela é IMPRESSA por quem chama, sempre. Estado persistido que não se anuncia é a etiqueta que
+ * envelhece em silêncio - o mesmo defeito que a tela de causas acabou de perder (dono, 06/08). Uma
+ * linha dizendo "migrate, definido em 06/08, --adopt inverte" transforma estado velho em fato.
+ *
+ * O default é `adopt` porque é o que uma pessoa com um sistema instalado quer na maioria dos dias, e
+ * porque é o único dos dois cuja lista tem conserto automático (`--fix`). Migrar é uma fase, e uma
+ * fase se declara.
+ */
+export function intentOf(config, flag) {
+    if (flag === "migrate" || flag === "adopt")
+        return { intent: flag, from: "flag" };
+    if (config.intent)
+        return {
+            intent: config.intent,
+            from: "config",
+            ...(config.intentAt ? { at: config.intentAt } : {}),
+        };
+    return { intent: "adopt", from: "default" };
+}
+/** A frase que acompanha o relatório - ver `intentOf` para por que ela é obrigatória. */
+export function describeIntent(source) {
+    const what = source.intent === "migrate"
+        ? "reading as a MIGRATION - values your system does not name yet come first"
+        : "reading as ADOPTION - values your system already names come first";
+    const where = source.from === "flag"
+        ? "this run only"
+        : source.from === "config"
+            ? `set in _synthesisui/config.json${source.at ? ` on ${source.at.slice(0, 10)}` : ""}`
+            : "nobody declared one, so this is the default";
+    const flip = source.intent === "migrate"
+        ? "`doctor --adopt` flips it"
+        : "`doctor --migrate` flips it";
+    return `${what} · ${where} · ${flip}`;
+}
 /** Writes the project config (committable, plain JSON). */
 export async function writeProjectConfig(root, config) {
     const path = projectConfigPath(root);

package/dist/doctor/frozen.js

@@ -19,7 +19,19 @@
  * actually differs between the two schemes; a role that is the same in both
  * costs nothing to spell either way, and this stays quiet about it.
  */
-const PRIMITIVE = /^\{color\.([a-z0-9]+)\.([a-z0-9]+)\}$/i;
+/**
+ * A GRAMÁTICA DE UMA REF DE PRIMITIVA, e ela recusava hífen nos DOIS segmentos.
+ *
+ * Contada em 06/08: a mesma pergunta era feita por quatro regexes e as quatro discordavam - duas
+ * aceitavam hífen só na família, uma aceitava nos dois, e esta em nenhum. Consequência medida no repo do
+ * dono, que tem as famílias `royal-blue`, `vivid-pink` e `electric-indigo`: toda ref para elas parseava
+ * como nada aqui, e esta checagem passava calada por cima delas - um achado que não existe é
+ * indistinguível de um achado que não há.
+ *
+ * Gêmea de `PRIMITIVE_REF_PATTERN` em `libs/ds-contracts/src/token-ref.ts`, copiada e não importada
+ * porque o CLI é publicado standalone. O spec ao lado assere a fonte da regex nos dois lados.
+ */
+const PRIMITIVE = /^\{color\.([a-z0-9-]+)\.([a-z0-9-]+)\}$/i;
 const BACKGROUND = /^background(-color)?$/;
 const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
 function* colorBindings(node, where) {

package/dist/doctor/variant-read.js

@@ -79,9 +79,16 @@ export function conditionOf(modifiers) {
     const out = {};
     for (const raw of modifiers) {
         if (raw === "dark") {
-            // The dark half has its own home in the transcription and no slot inside a
-            // layer. Saying so beats writing the light value into a dark rule.
-            out.lost = true;
+            /**
+             * O ESQUEMA É UMA CONDIÇÃO, e o layer tem slot para ele.
+             *
+             * O comentário anterior dizia "the dark half has its own home in the transcription and no slot
+             * inside a layer" - verdade quando foi escrito, e falso desde que o layer passou a carregar
+             * `scheme`. A "casa na transcrição" só existe para a classe INCONDICIONAL: uma `dark:` dentro de
+             * um record por variante passava por aqui e morria, e é assim que 9 utilities do Button e do
+             * Toggle sumiram com uma linha de aviso e outras 66 sem nenhuma (dono, 06/08).
+             */
+            out.scheme = "dark";
             continue;
         }
         const relational = RELATIONAL.exec(raw);
@@ -121,7 +128,8 @@ function keyOf(c, variant) {
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([k, o]) => `${k}=${o}`)
         .join("&");
-    return `${v}|${c.state ?? ""}|${c.within ?? ""}|${c.at ?? ""}`;
+    /** O ESQUEMA ENTRA NA CHAVE: sem ele, `bg-white` e `dark:bg-black` caem no mesmo layer e um vence. */
+    return `${v}|${c.state ?? ""}|${c.within ?? ""}|${c.at ?? ""}|${c.scheme ?? ""}`;
 }
 /**
  * Split a class list into the base and the conditional layers it contains.
@@ -157,12 +165,13 @@ export function splitByCondition(classes, variant) {
         const key = keyOf(cond, variant);
         const layer = layers.get(key) ??
             {
-                ...(variant || cond.state || cond.within
+                ...(variant || cond.state || cond.within || cond.scheme
                     ? {
                         when: {
                             ...(variant ? { variant } : {}),
                             ...(cond.state ? { state: cond.state } : {}),
                             ...(cond.within ? { within: cond.within } : {}),
+                            ...(cond.scheme ? { scheme: cond.scheme } : {}),
                         },
                     }
                     : {}),
@@ -623,6 +632,31 @@ function objectFields(value) {
         return [];
     return topLevelEntries(trimmed.slice(1, end - 1));
 }
+/**
+ * TEM A FORMA DE UMA LISTA DE CLASSES?
+ *
+ * Usada só no resíduo: quando nenhuma prop de classe consome o campo, esta é a última pergunta antes de
+ * afirmar que ele é estilo. Ela é deliberadamente TÍMIDA - dois tokens no mínimo, tudo minúsculo, nada
+ * começando com `#`:
+ *
+ *     "px-2 py-2 gap-0.5"   3 tokens, minusculo        -> lista de classes
+ *     "overline"            1 token                    -> silencio (e o `variant` de um <Text>)
+ *     "body-md"             1 token                    -> silencio, e indistinguivel de `text-xs`
+ *     "#1394DC"             comeca com #               -> silencio (cor de grafico)
+ *     "Waiting"             maiuscula                  -> silencio (conteudo)
+ *
+ * Ela erra CALANDO sobre uma classe única e não-consumida, e esse é o lado certo de errar: uma linha
+ * inventada num relatório custa a confiança na linha seguinte, que estava certa.
+ */
+function looksLikeClassList(value) {
+    const text = value.trim().replace(/^[`'"]|[`'"]$/g, "");
+    if (!text || text.startsWith("#"))
+        return false;
+    const tokens = text.split(/\s+/).filter(Boolean);
+    if (tokens.length < 2)
+        return false;
+    return tokens.every((t) => /^[a-z0-9[\]()/:._!-]+$/.test(t));
+}
 /**
  * THE STATIC CLASSES OF THE `className` CALL THAT CONSUMES A LOOKUP.
  *
@@ -636,12 +670,34 @@ function objectFields(value) {
  * local first (`const config = statusConfig[status]`); a record whose value is a plain
  * string has no field, and there the indexing expression is what is written at the call
  * site (`variantColors[variant]`), so the SYMBOL is the reliable half.
+ *
+ * E DUAS COISAS QUE FALTAVAM, medidas em 8 de 8 casos de um repo real (dono, 06/08) - nenhum deles
+ * escrevia `simbolo.campo` no ponto de consumo:
+ *
+ *   1. A PROP NÃO É SÓ `className`. O MetricCard deles passa o campo em
+ *      `contentClassName={cn("p-0 flex flex-col", currentSize.container)}` - é o Card deles que recebe
+ *      a classe por outro nome, e exigir `className` literal descartava a linha inteira.
+ *   2. O CAMPO PODE VIR DESESTRUTURADO. O CircularProgress escreve
+ *      `const { diameter, strokeWidth, fontSize } = sizeConfig[size]` e depois usa `fontSize` NU dentro
+ *      do `cn()` - sem ponto nenhum, então a forma `<algo>.campo` não casa.
+ *
+ * As duas juntas são a diferença entre colocar o look no elemento certo e reportá-lo como "não há
+ * elemento onde pôr".
  */
 function callSiteClasses(source, symbol, field) {
+    /** Desestruturado da própria tabela: `const { fontSize } = sizeConfig[size]`. */
+    const destructured = field != null &&
+        new RegExp(`\\{[^}]*\\b${field}\\b[^}]*\\}\\s*=\\s*${symbol}\\s*\\[`).test(source);
     const use = field
-        ? new RegExp(`\\b[A-Za-z_$][\\w$]*(?:\\[[^\\]]*\\])?\\.${field}\\b`)
+        ? new RegExp(destructured
+            ? `\\b${field}\\b`
+            : `\\b[A-Za-z_$][\\w$]*(?:\\[[^\\]]*\\])?\\.${field}\\b`)
         : new RegExp(`\\b${symbol}\\s*\\[`);
-    for (const m of source.matchAll(/className=\{\s*(?:[A-Za-z_$][\w$]*\.)?(?:cn|clsx|classNames|cx|twMerge|twJoin|classcat)\(/g)) {
+    /**
+     * `className` E QUALQUER `*ClassName`, que é como um componente deles recebe a classe de um filho.
+     * A borda `(?:^|[^A-Za-z])` existe para não casar no meio de um identificador maior.
+     */
+    for (const m of source.matchAll(/(?:^|[^A-Za-z])[A-Za-z]*[Cc]lassName=\{\s*(?:[A-Za-z_$][\w$]*\.)?(?:cn|clsx|classNames|cx|twMerge|twJoin|classcat)\(/g)) {
         const open = (m.index ?? 0) + m[0].length - 1;
         const end = endOf(source, open);
         if (end === -1)
@@ -787,11 +843,23 @@ unattributed) {
                 const on = callSiteClasses(clean, symbol, field.key);
                 if (!on) {
                     /**
-                     * NOWHERE TO PUT IT IS NOT THE ROOT. A field no `className` claims is a
-                     * decision we cannot place, and placing it on the component would paint
-                     * the wrong element - which is the whole bug this reads around.
+                     * NOWHERE TO PUT IT IS NOT THE ROOT. A field no class prop claims is a decision we cannot
+                     * place, and placing it on the component would paint the wrong element - which is the whole
+                     * bug this reads around.
+                     *
+                     * MAS SÓ SE FOR UMA LISTA DE CLASSES. Medido em 8 de 8 casos de um repo real (dono, 06/08),
+                     * SEIS dos campos não eram estilo nenhum: `labelVariant: "overline"` e `valueVariant:
+                     * "body-md"` são o `variant` de um `<Text>`, `text: "Waiting"` é conteúdo, e
+                     * `start: "#1394DC"` é a cor de um gráfico. Chamá-los de "look que não pôde ser colocado" é
+                     * inventar um problema, e foi o que fez uma causa de 33 ocorrências ter 6 falsos positivos.
+                     *
+                     * A regra é o que sobra depois do consumo: se NENHUMA prop de classe consome o campo E o
+                     * valor não tem a forma de uma lista de classes, a gente não sabe que é estilo - e o que não
+                     * se sabe não se afirma. Um valor de um token só fica em silêncio de propósito: `overline` e
+                     * `text-xs` são indistinguíveis pela forma, e o consumo era a única prova.
                      */
-                    unattributed?.push(`\`${symbol}.${field.key}\` is a field of a per-element table that no \`className\` call consumes, so there is no element to put it on`);
+                    if (looksLikeClassList(field.value))
+                        unattributed?.push(`\`${symbol}.${field.key}\` is a field of a per-element table that no class prop consumes, so there is no element to put it on`);
                     continue;
                 }
                 const per = splitByCondition(classes, { [axis]: option.key });
@@ -856,6 +924,7 @@ export function transcribeVariants(source, declared) {
     const reads = readVariants(source);
     const fromRecords = {};
     const unslotted = [];
+    const notes = [];
     const inline = [
         ...readInlineConditions(source),
         // The two shapes the enumeration found to be five times more common than `cva`.
@@ -925,7 +994,11 @@ export function transcribeVariants(source, declared) {
             continue;
         }
         const attr = axis.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-        unslotted.push(named.length === 0
+        /**
+         * NOTA, NÃO PERDA. O layer está na receita; o que falta é um atributo no elemento para ele aplicar.
+         * Enquanto isto viajava em `unslotted`, a tela contava 16 destes como pendência de conserto.
+         */
+        notes.push(named.length === 0
             ? `\`${axis}\` gates a look and is a boolean rather than an axis - the layer is kept, and \`data-${attr}\` has to be set for it to apply`
             : `\`${axis}\` gates a look on one option (\`${named[0]}\`) - one option is not an axis, so the layer is kept and \`data-${attr}="${named[0]}"\` has to be set for it to apply`);
     }
@@ -957,5 +1030,6 @@ export function transcribeVariants(source, declared) {
         layers,
         base: transcribe(baseClasses, declared),
         unslotted,
+        notes,
     };
 }

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { absorb } from "./commands/absorb.js";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
 import { advise } from "./commands/advise.js";
@@ -19,6 +20,7 @@ import { mcp } from "./commands/mcp.js";
 import { refit } from "./commands/refit.js";
 import { request } from "./commands/request.js";
 import { status } from "./commands/status.js";
+import { summary } from "./commands/summary.js";
 import { sync } from "./commands/sync.js";
 import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
@@ -99,6 +101,10 @@ Options:
   --strict           doctor: exit 1 when drift is found in THIS repo (for CI)
   --strict-system    doctor: also exit 1 when the system itself is inconsistent
   --verbose          doctor: every finding, file by file (default is a summary)
+  --send             absorb: send the batch you reviewed (default writes the file)
+  --migrate          doctor: lead with what your system does NOT name yet - the
+                     order for moving design INTO a shared package
+  --adopt            doctor: lead with what your system already names (default)
   --laws             doctor: show every usage law, not just the busiest components
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
@@ -279,9 +285,57 @@ async function main() {
                  */
                 ...(flags.write === true ? { write: true } : {}),
                 ...(flags["write-baseline"] === true ? { writeBaseline: true } : {}),
+                /**
+                 * A INTENÇÃO DESTA RODADA - atalho para `config.json`, ver `intentOf`.
+                 *
+                 * Duas flags e não um valor (`--intent=migrate`), porque o que se digita no meio de uma tarefa
+                 * é uma palavra: `--migrate` ou `--adopt`.
+                 */
+                ...(flags.migrate === true
+                    ? { intent: "migrate" }
+                    : flags.adopt === true
+                        ? { intent: "adopt" }
+                        : {}),
                 cli: CLI_VERSION,
             });
             break;
+        case "absorb":
+            /**
+             * O OUTRO SENTIDO: o sistema aprende o design que o código já tem - ver `commands/absorb.ts`.
+             *
+             * Sem flag ESCREVE uma proposta e não fala com a rede; `--send` manda o lote. A fase do meio é
+             * humana de propósito: nomear uma cor é decisão de design.
+             */
+            await absorb({
+                dir,
+                registry,
+                ...(flags.send === true ? { send: true } : {}),
+            });
+            break;
+        case "summary": {
+            /**
+             * AS QUATRO LINHAS DO PRIMEIRO MINUTO - ver `commands/summary.ts`.
+             *
+             * Existe para tirar o fechamento do `sui-init` das mãos do agente: ele terminou com ~400 palavras
+             * sobre o próprio trabalho, incluindo duas advertências já desatualizadas (dono, 06/08).
+             */
+            /** `args` já exclui o comando - o slug é o primeiro posicional, como em `template <slug>`. */
+            const target = args[0];
+            if (!target) {
+                console.log("usage: synthesisui summary <slug> [--base N --draft N --fixes N]");
+                break;
+            }
+            const num = (v) => typeof v === "string" && /^\d+$/.test(v)
+                ? Number.parseInt(v, 10)
+                : undefined;
+            await summary(target, {
+                dir,
+                ...(num(flags.base) != null ? { base: num(flags.base) } : {}),
+                ...(num(flags.draft) != null ? { draft: num(flags.draft) } : {}),
+                ...(num(flags.fixes) != null ? { fixes: num(flags.fixes) } : {}),
+            });
+            break;
+        }
         case "status":
             /** A resposta do dia a dia no terminal - ver `commands/status.ts`. Local primeiro. */
             await status({ dir, registry, cli: CLI_VERSION });
@@ -338,11 +392,28 @@ async function main() {
                 : undefined;
             const ds = typeof flags.ds === "string" ? flags.ds : undefined;
             const styles = typeof flags.styles === "string" ? flags.styles : undefined;
+            /**
+             * A INTENÇÃO, gravada com a data - ver `ProjectConfig.intent`.
+             *
+             * Aceita as duas formas porque as duas são naturais: `--intent migrate` quando um agente monta o
+             * comando, `--migrate` quando uma pessoa digita.
+             */
+            const intent = typeof flags.intent === "string"
+                ? flags.intent
+                : flags.migrate === true
+                    ? "migrate"
+                    : flags.adopt === true
+                        ? "adopt"
+                        : undefined;
             await init({
                 dir,
                 registry,
                 target,
                 pagesDir,
+                ...(flags.absorb === "code" || flags.absorb === "system"
+                    ? { absorb: flags.absorb }
+                    : {}),
+                ...(intent ? { intent } : {}),
                 componentsDir,
                 styles,
                 ds,

package/dist/measured-scope.js

@@ -0,0 +1,63 @@
+import { readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const EMPTY = { system: null, usage: [], from: "none" };
+/** Existe como diretório? Um escopo gravado e depois renomeado não pode derrubar o comando. */
+async function present(root, rel) {
+    return stat(resolve(root, rel)).then((s) => s.isDirectory(), () => false);
+}
+/**
+ * Lê `_synthesisui/census.json` e devolve o que ele diz sobre ONDE.
+ *
+ * Só caminhos que ainda existem: o censo é uma foto de quando o import rodou, e uma pasta renomeada
+ * desde então não pode fazer o doctor estourar - ela simplesmente sai da lista, e a lista vazia cai no
+ * comportamento antigo (a raiz).
+ */
+export async function measuredScope(root) {
+    const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => null);
+    if (!raw)
+        return EMPTY;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return EMPTY;
+    }
+    const scope = typeof parsed.scope === "string" && parsed.scope.trim()
+        ? parsed.scope.trim()
+        : null;
+    const usage = Array.isArray(parsed.usage)
+        ? parsed.usage.filter((u) => typeof u === "string" && !!u.trim())
+        : [];
+    const system = scope && (await present(root, scope)) ? scope : null;
+    const kept = [];
+    for (const u of usage)
+        if (await present(root, u))
+            kept.push(u);
+    if (!system && kept.length === 0)
+        return EMPTY;
+    return { system, usage: kept, from: "census" };
+}
+/**
+ * As pastas a LER, na ordem em que importam - o sistema primeiro.
+ *
+ * A ordem não é cosmética: ela decide qual arquivo entra primeiro no relatório e, com teto de
+ * anotações no CI, decide o que chega ao PR.
+ */
+export function scopePaths(m) {
+    return [...(m.system ? [m.system] : []), ...m.usage];
+}
+/** Como dizer o que foi lido. Uma leitura que não declara o universo é um número sem denominador. */
+export function describeScope(m) {
+    if (m.from === "none")
+        return null;
+    const parts = [
+        ...(m.system ? [`${m.system} (the system)`] : []),
+        ...(m.usage.length > 0
+            ? [
+                `${m.usage.join(", ")} (${m.usage.length === 1 ? "consumer" : "consumers"})`,
+            ]
+            : []),
+    ];
+    return `read from your census: ${parts.join(" · ")}`;
+}