synthesisui 0.16.153 → 0.16.155

package/dist/absorb-plan.js

@@ -0,0 +1,154 @@
+import { deltaE, JND } from "./doctor/color-distance.js";
+import { nearestToken } from "./doctor/tokens.js";
+/** Onde cada tipo de valor mora na fundação. `color` é o único com dois segmentos. */
+const HOME = {
+    color: "color",
+    radius: "radius",
+    spacing: "spacing",
+    font: "typography",
+    motion: "motion.durations",
+};
+/** Uma palavra de categoria no começo do nome deles não é família - é a categoria repetida. */
+const CATEGORY = /^(color|colour|radius|rounded|spacing|space|gap|font|type|duration|motion|ease|easing)-/;
+const clean = (name) => name.replace(/^--/, "").toLowerCase();
+/**
+ * O CAMINHO A PARTIR DO NOME DELES, e nada além dele.
+ *
+ * Cor precisa de família E step, e a forma que o mundo real produz é `<família>-<número>` - a mesma que
+ * o censo lê para montar as rampas deles. Sem o número não há step, e inventar um (`.500`) seria
+ * escolher uma posição na escala por eles: aí o valor volta sem caminho e a pessoa decide.
+ *
+ * O namespace é PRESERVADO de propósito: um repo com `--color-lightgray-300` e
+ * `--dashboard-lightgray-300` tem duas famílias, e `dashboard-lightgray` é o nome honesto da segunda.
+ */
+export function pathFor(kind, theirName) {
+    if (!theirName)
+        return "";
+    const bare = clean(theirName).replace(CATEGORY, "");
+    if (!bare)
+        return "";
+    if (kind === "color") {
+        const m = /^(.*[a-z0-9])-(\d{2,4})$/.exec(bare);
+        return m ? `color.${m[1]}.${m[2]}` : "";
+    }
+    return `${HOME[kind]}.${bare}`;
+}
+/**
+ * O TOKEN DELES MAIS PRÓXIMO DESTE VALOR, quando existe um perto o bastante para valer a frase.
+ *
+ * Cor por ΔE76 (2.3 é a diferença que um olho começa a notar; abaixo disso são a mesma cor discutindo).
+ * Comprimento pelo mesmo `nearestToken` que o doctor já usa para dizer "snap to". Motion e tipografia
+ * ficam de fora: 0.2s e 0.25s não são "quase iguais", são durações diferentes de propósito.
+ */
+function nearestOwn(theirs, literal, kind) {
+    if (kind === "color") {
+        let best = null;
+        for (const [name, value] of theirs.byName) {
+            const d = deltaE(literal, value);
+            if (d === null || d === 0)
+                continue;
+            if (best === null || d < best.away)
+                best = { name, value, away: d };
+        }
+        /** Três ΔE: perto o bastante para alguém querer olhar, longe o bastante para não ser óbvio. */
+        if (!best || best.away > JND * 1.3)
+            return undefined;
+        return {
+            name: clean(best.name),
+            value: best.value,
+            away: `${best.away.toFixed(1)} ΔE`,
+        };
+    }
+    if (kind === "radius" || kind === "spacing") {
+        const hit = nearestToken(theirs, literal);
+        return hit
+            ? {
+                name: clean(hit.name),
+                value: hit.value,
+                away: `${hit.delta}${/rem$/.test(literal) ? "rem" : "px"} apart`,
+            }
+            : undefined;
+    }
+    return undefined;
+}
+/**
+ * A PROPOSTA: os valores mais repetidos que o sistema não nomeia, com o caminho quando ele é derivável.
+ *
+ * `theirs` é a tabela do vocabulário DELES (`buildTable({ source: "yours" })`), lida da raiz mesmo
+ * quando a medição é escopada - é o mesmo princípio que já vale no doctor: o vocabulário vem da raiz, só
+ * a leitura é escopada.
+ *
+ * `have` são os caminhos que a fundação já tem, para a proposta nunca sugerir sobrescrever um token
+ * existente com outro valor - isso não é absorver, é repintar.
+ */
+export function absorbPlan(d, theirs, have, cap = 40) {
+    const unnamed = d.repeats.filter((r) => !r.token);
+    const entries = [];
+    for (const r of unnamed) {
+        if (entries.length >= cap)
+            break;
+        const theirNames = theirs.byValue.get(r.literal.toLowerCase()) ?? [];
+        const theirName = theirNames[0];
+        const path = pathFor(r.kind, theirName);
+        const near = nearestOwn(theirs, r.literal, r.kind);
+        /** Já existe na fundação com OUTRO valor: absorver aqui seria repintar o token deles. */
+        if (path && have.has(path))
+            continue;
+        entries.push({
+            value: r.literal,
+            kind: r.kind,
+            files: r.files,
+            count: r.count,
+            path,
+            ...(theirName ? { theirName: clean(theirName) } : {}),
+            ...(near ? { near } : {}),
+        });
+    }
+    return { entries, more: Math.max(0, unnamed.length - entries.length) };
+}
+/** Quantas linhas da proposta ainda precisam de um nome humano. */
+export const needingName = (plan) => plan.entries.filter((e) => !e.path);
+/**
+ * A proposta em texto - e ela lidera pelo que está PRONTO para enviar.
+ *
+ * Uma lista que abre pelas pendências faz parecer que nada pode ser feito hoje; a maioria das linhas de
+ * um repo em migração já tem nome no vocabulário do próprio cliente, e essas viajam sem ninguém digitar
+ * nada.
+ */
+export function describeAbsorb(plan) {
+    const ready = plan.entries.filter((e) => e.path);
+    const pending = needingName(plan);
+    const lines = [];
+    if (plan.entries.length === 0)
+        return [
+            "Nothing to absorb: every repeated value your code writes by hand already has a name in the system.",
+        ];
+    lines.push(`${ready.length} of ${plan.entries.length} values already have a name in YOUR vocabulary - those travel as they are:`);
+    for (const e of ready.slice(0, 8))
+        lines.push(`  ${e.value.padEnd(24)} ${e.path.padEnd(28)} ${e.files} file${e.files === 1 ? "" : "s"}${e.theirName ? ` · your ${e.theirName}` : ""}`);
+    if (ready.length > 8)
+        lines.push(`  (${ready.length - 8} more)`);
+    if (pending.length > 0) {
+        const close = pending.filter((e) => e.near);
+        lines.push("");
+        lines.push(`${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`);
+        for (const e of pending.slice(0, 8))
+            lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near ? `≈ your ${e.near.name} (${e.near.away})` : 'path: ""'}`);
+        if (pending.length > 8)
+            lines.push(`  (${pending.length - 8} more)`);
+        /**
+         * E A LEITURA QUE MUDA O TRABALHO: quando a maioria dos sem-nome está perto de um token que eles já
+         * têm, isto não é uma fila de batismos - é uma fila de NORMALIZAÇÃO, e sai muito mais barato.
+         */
+        if (close.length > 0) {
+            lines.push("");
+            lines.push(`${close.length} of those ${close.length === 1 ? "is" : "are"} within a hair of a token you already have (marked ≈). Those are probably not new names - they are the same decision written twice, and pointing the code at what you have is cheaper than naming them.`);
+        }
+    }
+    /** O teto NUNCA é silencioso: um corte que não se diz lê como "é tudo o que existe". */
+    if (plan.more > 0) {
+        lines.push("");
+        lines.push(`${plan.more} more unnamed values are below the cut - the file holds the ${plan.entries.length} most repeated. Absorb these, re-run, and the next batch appears.`);
+    }
+    return lines;
+}

package/dist/commands/absorb.js

@@ -0,0 +1,211 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { absorbPlan, describeAbsorb, needingName, } from "../absorb-plan.js";
+import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
+import { diagnose, scanSource } from "../doctor/scan.js";
+import { buildTable } from "../doctor/tokens.js";
+import { measuredScope, scopePaths } from "../measured-scope.js";
+import { body, paint, section, snippet } from "../output.js";
+import { loadSystem, walkAll } from "./doctor.js";
+/**
+ * `synthesisui absorb` - O SISTEMA APRENDE O DESIGN QUE O CÓDIGO JÁ TEM.
+ *
+ * O outro sentido da esteira, e o que faltava para o ciclo de migração fechar (dono, 06/08, movendo
+ * design de três apps para `packages/ui`):
+ *
+ *     doctor --migrate   4223 valores que o sistema não nomeia, por frequência
+ *     absorb             ESTE: eles viram tokens do sistema
+ *     upgrade            o repo pega a versão nova
+ *     doctor --fix       agora eles têm nome, e a troca é automática
+ *
+ * DUAS FASES, e a do meio é humana de propósito. A primeira escreve uma PROPOSTA em
+ * `_synthesisui/absorb.json`: cada valor com o caminho derivado do nome que eles já usam, e vazio
+ * quando ninguém nomeia. A pessoa preenche os vazios num arquivo, de uma vez - vinte perguntas no
+ * terminal é como uma migração vira uma tarde perdida. Aí `--send` manda o lote.
+ *
+ * O arquivo é o contrato entre as duas fases, e é revisável por outra pessoa antes de ir: um lote de
+ * tokens novos num sistema compartilhado é exatamente o tipo de mudança que um time quer ver num diff.
+ */
+const FILE = "_synthesisui/absorb.json";
+export async function absorb(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const path = join(root, FILE);
+    if (opts.send)
+        return sendProposal(root, path, opts.registry);
+    const installed = await loadSystem(root);
+    if (!installed.table.slug) {
+        console.log(section("Absorb"));
+        console.log(body("No system installed here, so there is nothing to absorb INTO. `synthesisui list` shows what you can add."));
+        return;
+    }
+    const measured = await measuredScope(root);
+    const rel = scopePaths(measured);
+    const roots = rel.length > 0 ? rel.map((s) => resolve(root, s)) : [root];
+    /**
+     * DUAS TABELAS, e é a diferença entre elas que define o trabalho.
+     *
+     * A nossa diz o que o sistema JÁ nomeia - o que ela nomeia é assunto do `--fix`. A DELES diz como
+     * eles chamam o valor, e é de lá que o nome sai. Lida da RAIZ mesmo quando a medição é escopada: o
+     * vocabulário é do projeto, e um app que pega um token emprestado do `packages/ui` deles não o
+     * redeclara.
+     */
+    let css = "";
+    for await (const file of walkAll([root]))
+        if (/\.(css|scss|sass|less)$/i.test(file))
+            css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+    const theirs = buildTable({ css, source: "yours" });
+    const reports = [];
+    for await (const file of walkAll(roots)) {
+        const source = await readFile(file, "utf8").catch(() => null);
+        if (source === null)
+            continue;
+        reports.push(scanSource(file.slice(root.length + 1), source, installed.table));
+    }
+    const plan = absorbPlan(diagnose(reports), theirs, pathsInSystem(installed.documents), opts.cap ?? 40);
+    console.log(section("What the system could absorb"));
+    console.log(body(paint.dim(`read from ${rel.length > 0 ? rel.join(", ") : "this project"} · your own vocabulary read from the root`)));
+    console.log("");
+    for (const line of describeAbsorb(plan))
+        console.log(body(line));
+    if (plan.entries.length === 0)
+        return;
+    const proposal = {
+        slug: installed.table.slug,
+        at: new Date().toISOString(),
+        scope: rel,
+        entries: plan.entries,
+        more: plan.more,
+    };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(proposal, null, 2)}\n`, "utf8");
+    console.log("");
+    console.log(body(`Written to ${FILE} - nothing was sent.`));
+    const pending = needingName(plan).length;
+    if (pending > 0)
+        console.log(body(`Fill the ${pending} empty \`path\` field${pending === 1 ? "" : "s"} with the name you want (\`color.<family>.<step>\`, \`spacing.<key>\`), delete the lines you do not want, then:`));
+    else
+        console.log(body("Delete the lines you do not want and send the rest with:"));
+    console.log(paint.blue(snippet(["npx synthesisui@latest absorb --send"])));
+}
+/**
+ * OS CAMINHOS QUE A FUNDAÇÃO JÁ TEM, lidos do documento que o `add` deixou ao lado dos tokens.
+ *
+ * Serve para a proposta nunca sugerir escrever num token existente: isso não seria absorver o design
+ * deles, seria repintar uma decisão que eles já tomaram. A plataforma recusa de novo do outro lado - ela
+ * é a autoridade -, e recusar aqui evita a pessoa preencher um nome que vai ser rejeitado.
+ */
+function pathsInSystem(documents) {
+    const out = new Set();
+    const walk = (node, path) => {
+        if (node && typeof node === "object" && !Array.isArray(node))
+            for (const [k, v] of Object.entries(node))
+                walk(v, [...path, k]);
+        else if (typeof node === "string" && path.length > 0)
+            out.add(path.join("."));
+    };
+    for (const doc of documents) {
+        const d = (doc ?? {});
+        const foundations = d.foundations ?? {};
+        const color = (foundations.color ?? {});
+        walk(color.primitives, ["color"]);
+        for (const [key, value] of Object.entries(foundations))
+            if (key !== "color")
+                walk(value, [key]);
+        walk(d.motion?.durations, ["motion", "durations"]);
+        walk(d.motion?.easings, ["motion", "easings"]);
+    }
+    return out;
+}
+/** Manda o lote gravado. Só o que tem caminho viaja - o resto ainda espera um nome. */
+async function sendProposal(root, path, registry) {
+    const raw = await readFile(path, "utf8").catch(() => null);
+    if (!raw) {
+        console.log(section("Absorb"));
+        console.log(body(`No proposal at ${FILE}. Run \`npx synthesisui@latest absorb\` first - it writes one and sends nothing.`));
+        return;
+    }
+    let proposal;
+    try {
+        proposal = JSON.parse(raw);
+    }
+    catch {
+        console.log(section("Absorb"));
+        console.log(body(`${FILE} is not readable JSON anymore. Fix the file, or delete it and run \`absorb\` again.`));
+        return;
+    }
+    const ready = (proposal.entries ?? []).filter((e) => typeof e.path === "string" && e.path.trim().length > 0);
+    const waiting = (proposal.entries ?? []).length - ready.length;
+    if (ready.length === 0) {
+        console.log(section("Absorb"));
+        console.log(body(`Every line in ${FILE} still has an empty \`path\`. A name is the one thing this cannot decide for you.`));
+        return;
+    }
+    /**
+     * O ALVO DECIDE SE ISSO SAI DA MÁQUINA - ver `ProjectConfig.absorb`.
+     *
+     * `code`: o vocabulário canônico é o CSS deles, então a nossa parte é devolver o bloco e a deles é
+     * colar. Nunca escrevemos no arquivo do cliente - e o import seguinte lê os tokens de volta, o que faz
+     * o caminho fechar sem nós tocarmos em nada.
+     */
+    const target = (await readProjectConfig(root)).absorb ?? "system";
+    if (target === "code") {
+        console.log(section("Paste this into your own vocabulary"));
+        console.log(body(paint.dim("Your config says absorbed values belong in your CSS, so nothing was sent.")));
+        console.log("");
+        console.log("  :root {");
+        for (const e of ready)
+            console.log(`    --${e.path.replace(/\./g, "-")}: ${e.value};`);
+        console.log("  }");
+        console.log("");
+        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor cobra them by your own names."));
+        return;
+    }
+    const token = await readToken();
+    if (!token) {
+        console.log(section("Absorb"));
+        console.log(body("Sending needs a login - the tokens land in YOUR system:"));
+        console.log(paint.blue(snippet(["npx synthesisui@latest login"])));
+        return;
+    }
+    const base = resolveRegistry(registry);
+    const res = await fetch(`${base}/api/registry/ds/${proposal.slug}/absorb`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({
+            tokens: ready.map((e) => ({
+                path: e.path.trim(),
+                value: e.value,
+                ...(e.theirName ? { was: e.theirName } : {}),
+            })),
+        }),
+    }).catch(() => null);
+    console.log(section("Absorb"));
+    if (!res?.ok) {
+        console.log(body(res
+            ? `The registry answered ${res.status}. Nothing was absorbed, and ${FILE} is untouched - fix and send again.`
+            : "Could not reach the registry. Nothing was absorbed."));
+        return;
+    }
+    const answer = (await res.json());
+    console.log(body(`${answer.added ?? 0} token${answer.added === 1 ? "" : "s"} are now part of your system${answer.draft ? `, in the v${answer.draft} draft` : ""}.`));
+    for (const s of (answer.skipped ?? []).slice(0, 8))
+        console.log(body(paint.dim(`  skipped ${s.path} - ${s.why}`)));
+    if (waiting > 0)
+        console.log(body(paint.dim(`${waiting} line${waiting === 1 ? "" : "s"} stayed behind with no name. They are still in ${FILE}.`)));
+    /**
+     * E O CICLO SE FECHA AQUI, dito em voz alta.
+     *
+     * Absorver não muda o código: os literais continuam escritos à mão até alguém trocá-los, e agora
+     * existe por quem trocar. Ninguém adivinharia essa ordem - foi ela que faltou na primeira conversa
+     * sobre migração (dono, 06/08).
+     */
+    console.log("");
+    console.log(body("Two commands and the code catches up:"));
+    console.log(paint.blue(snippet([
+        `npx synthesisui@latest upgrade ${proposal.slug}`,
+        "npx synthesisui@latest doctor --fix",
+    ])));
+}

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
+import { describeIntent, intentOf, readProjectConfig } from "../config.js";
 import { describeFix, planFix, readerFor, writeFix, } from "../doctor/apply-fix.js";
 import { baselineOf, compareToBaseline, describeVerdict, githubAnnotations, sarifOf, } from "../doctor/ci-format.js";
 import { findDivergences } from "../doctor/coherence.js";
@@ -13,6 +14,7 @@ import { checkableName, readRequests, verifyAndCloseRequests, } from "../doctor/
 import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
+import { describeScope, measuredScope, scopePaths } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { resolveDeps } from "../stack.js";
 /**
@@ -412,7 +414,32 @@ async function readWiring(root, slug) {
 const DEFAULT_BASELINE = "_synthesisui/drift-baseline.json";
 export async function doctor(opts) {
     const root = resolve(opts.dir ?? process.cwd());
-    const scopes = (opts.scopes ?? []).map((s) => resolve(root, s));
+    /**
+     * O ESCOPO QUE O IMPORT JÁ GRAVOU - ver `measured-scope.ts`.
+     *
+     * Um caminho passado à mão manda, sempre: quem digitou sabe o que quer. Sem ele, a resposta já está
+     * no disco (`census.json`: `scope` + `usage`), e varrer a raiz ignorando isso foi o que produziu uma
+     * lista de prioridades tirada de um app consumidor num repo de 2787 arquivos (dono, 06/08).
+     */
+    const measured = (opts.scopes ?? []).length > 0
+        ? { system: null, usage: [], from: "none" }
+        : await measuredScope(root);
+    const relScopes = (opts.scopes ?? []).length > 0
+        ? opts.scopes
+        : scopePaths(measured);
+    const scopes = relScopes.map((s) => resolve(root, s));
+    /**
+     * CORRIDA COMPLETA É "NINGUÉM DIGITOU UM CAMINHO", e não "varreu tudo".
+     *
+     * O ledger só guarda retrato de corrida completa, porque a cobertura de um canto na linha do tempo do
+     * projeto lê como o projeto tendo melhorado quando alguém só apontou a ferramenta para outra pasta.
+     * Com o escopo agora vindo do censo, `scopes.length === 0` deixaria de acontecer - e o histórico
+     * pararia de existir em todo repo que tem censo. O que caracteriza a corrida completa é a INTENÇÃO de
+     * medir o projeto, e ela é: nenhum caminho na linha de comando.
+     */
+    const fullRun = (opts.scopes ?? []).length === 0;
+    /** A intenção ordena o relatório, e a precedência é flag > config > default. */
+    const intent = intentOf(await readProjectConfig(root), opts.intent);
     const installed = await loadSystem(root);
     const { recipes, documents } = installed;
     let table = installed.table;
@@ -533,9 +560,24 @@ export async function doctor(opts) {
             : table.source === "yours"
                 ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
                 : `No system installed - ${plural(d.scanned, "file")} read`));
+    /**
+     * ONDE ELE LEU, SEMPRE - e de onde essa decisão veio.
+     *
+     * "2787 files read" sem dizer o universo é um número que a pessoa preenche com o que imagina, e ela
+     * imagina o sistema dela. Quando o escopo veio do censo, a frase nomeia os dois papéis: a pasta que
+     * É o sistema, e os apps que o CONSOMEM.
+     */
     if (scopes.length > 0) {
-        console.log(body(`scope: ${opts.scopes?.join(", ")}`));
+        const said = measured.from === "census" ? describeScope(measured) : null;
+        console.log(body(said ?? `scope: ${relScopes.join(", ")}`));
     }
+    /**
+     * E A INTENÇÃO, em toda rodada, com a data e o jeito de inverter.
+     *
+     * É o que impede uma fase declarada em agosto de ordenar o relatório em dezembro sem ninguém saber
+     * por quê - a mesma regra que fez `not observed since` existir em vez de um `fixed` inferido.
+     */
+    console.log(body(paint.dim(describeIntent(intent))));
     // What a token could never have held, said out loud. A report that quietly
     // drops things is only trustworthy until someone notices, and then it is
     // worth less than one that says too much.
@@ -574,6 +616,15 @@ export async function doctor(opts) {
     // Fonts only count as missing when `init` actually wrote the file - a
     // non-Next project has no fonts.ts and must not be nagged about one.
     const fontsPending = wiring.fontsWritten && !wiring.fontsMapped;
+    /**
+     * A FIAÇÃO É PORTÃO, e não um aviso ao lado de um número.
+     *
+     * Sem o `@import` ou sem o `data-ds`, os tokens não chegam ao navegador. Até 06/08 a tela dizia isso
+     * e, três linhas abaixo, imprimia uma barra de 0% e uma lista de cinco prioridades - se contradizendo
+     * na mesma tela (dono: "fiquei perdido"). Ou o número não significa nada, ou existe uma lista de
+     * prioridades; as duas não cabem juntas.
+     */
+    const blocked = hasSystem && (!wiring.imported || !wiring.scoped);
     const unwired = table.source === "installed" &&
         (!wiring.imported || !wiring.scoped || fontsPending);
     if (unwired) {
@@ -598,10 +649,13 @@ export async function doctor(opts) {
         // working and the faces are not - saying "nothing reaches the browser"
         // there would be false, and a report that overstates is one nobody trusts
         // the next time.
-        const blocked = !wiring.imported || !wiring.scoped;
         if (blocked) {
-            console.log(body(`Until the first two are true, none of the ${table.byName.size} tokens reach the`));
-            console.log(body("browser and the number below cannot mean anything."));
+            /**
+             * A FRASE SEGUE O QUE VEM DEPOIS DELA. Ela dizia "o número abaixo não pode significar nada"
+             * enquanto imprimia o número abaixo; agora não há número abaixo, e prometer um seria a mesma
+             * incoerência ao contrário.
+             */
+            console.log(body(`Until both are true, none of the ${table.byName.size} tokens reach the browser.`));
         }
         else {
             console.log(body("Colour and spacing are working. Type is not: the system's faces"));
@@ -610,6 +664,41 @@ export async function doctor(opts) {
         }
         console.log(body("The exact snippets are in the output of `init`."));
     }
+    /**
+     * E AQUI O RELATÓRIO PARA, quando a fiação está vermelha: uma instrução, e nada mais.
+     *
+     * O que fica de fora é justamente o que não pode ser verdade ainda - a barra de cobertura, a lista de
+     * prioridades e a oferta do `--fix`. O `--fix` é o mais grave: no repo do dono ele teria trocado 217
+     * literais por `var(--ds-…)` que não resolvem em lugar nenhum, e o navegador descarta a declaração -
+     * ou seja, o comando que promete adotar o sistema quebraria a aparência do app.
+     *
+     * O ledger é gravado ANTES de sair: a corrida aconteceu, e o histórico não pode depender de o
+     * projeto estar bem configurado.
+     */
+    if (blocked) {
+        if (fullRun)
+            await appendEvent(root, {
+                kind: "doctor",
+                at: new Date().toISOString(),
+                coverage: d.coverage,
+                named: d.named,
+                ...(d.findings.some((f) => f.crossFamily)
+                    ? { crossFamily: d.findings.filter((f) => f.crossFamily).length }
+                    : {}),
+            }).catch(() => { });
+        console.log("");
+        if (opts.fix) {
+            console.log(body(`--fix is refused while those two are false. ${d.named} of your hand-written values`));
+            console.log(body("do have a name in the system, and swapping them now would point them at"));
+            console.log(body("variables the browser cannot resolve - the declarations would be dropped"));
+            console.log(body("and the page would change. Wire the two lines first."));
+        }
+        else {
+            console.log(body(`${d.named} of the ${d.findings.length} hand-written values found already have a name in`));
+            console.log(body("your system, and that number becomes actionable the moment both are true."));
+        }
+        return;
+    }
     /**
      * SHADCN IS THE MOST LIKELY THING ALREADY IN THE PROJECT, AND THE BRIDGE WAS
      * INVISIBLE.
@@ -671,7 +760,7 @@ export async function doctor(opts) {
      * question a design-system lead asks before paying for anything, and until
      * today the honest answer was that nobody knew.
      */
-    if (hasSystem && measurable && scopes.length === 0) {
+    if (hasSystem && measurable && fullRun) {
         /**
          * E A CONTAGEM DE COINCIDÊNCIAS VAI JUNTO - ver `crossFamily` em `scan.ts`.
          *
@@ -688,7 +777,7 @@ export async function doctor(opts) {
             ...(crossFamily > 0 ? { crossFamily } : {}),
         });
     }
-    if (hasSystem && scopes.length === 0) {
+    if (hasSystem && fullRun) {
         const record = summarize(await readEvents(root));
         if (record.checks >= 2) {
             console.log("");
@@ -716,7 +805,7 @@ export async function doctor(opts) {
      * the considered-and-rejected entries arrive already argued, by the party
      * that actually hit the gap.
      */
-    if (hasSystem && scopes.length === 0) {
+    if (hasSystem && fullRun) {
         // Verification first: whether an ask is still missing is a FACT about
         // the installed css, so the queue re-checks before it reports. A request
         // the build now delivers closes itself and says so - nobody marks done
@@ -1143,18 +1232,31 @@ export async function doctor(opts) {
             cheap: false,
         });
     }
-    for (const r of d.repeats.filter((x) => x.token).slice(0, 3)) {
+    /**
+     * AS DUAS INTENÇÕES ORDENAM ESTA LISTA AO CONTRÁRIO UMA DA OUTRA.
+     *
+     * `adopt`: o que o sistema JÁ nomeia vem primeiro - é troca de uma linha e o `--fix` faz.
+     * `migrate`: o que ele NÃO nomeia vem primeiro - é a decisão de design que a biblioteca tem que
+     * absorver, e é o trabalho de quem está movendo design de um app para um pacote compartilhado.
+     *
+     * As duas listas continuam presentes nos dois modos (dono, 06/08): esconder metade faria a tela
+     * mentir por omissão. Muda a ordem e muda quantos de cada aparecem no teto de cinco.
+     */
+    const migrating = intent.intent === "migrate";
+    const named = d.repeats.filter((x) => x.token);
+    const unnamed = d.repeats.filter((x) => !x.token);
+    for (const r of named.slice(0, migrating ? 2 : 3)) {
         plan.push({
-            rank: 3,
+            rank: migrating ? 4 : 3,
             what: `${r.literal} → ${r.token}`,
             size: `${r.files} file${r.files === 1 ? "" : "s"}`,
             cheap: true,
         });
     }
-    for (const r of d.repeats.filter((x) => !x.token).slice(0, 2)) {
+    for (const r of unnamed.slice(0, migrating ? 3 : 2)) {
         const near = nearestToken(table, r.literal);
         plan.push({
-            rank: 4,
+            rank: migrating ? 3 : 4,
             what: near
                 ? `${r.literal} - name it, or snap to ${near.name}`
                 : `${r.literal} - the system has no name for it`,
@@ -1318,7 +1420,8 @@ export async function doctor(opts) {
         await writeFile(path, `${JSON.stringify(baselineOf(d, {
             at: new Date().toISOString(),
             ...(opts.cli ? { cli: opts.cli } : {}),
-            ...(opts.scopes?.length ? { scope: opts.scopes.join(",") } : {}),
+            /** O escopo EFETIVO, e não a flag: comparar dois universos diferentes inventa regressão. */
+            ...(relScopes.length ? { scope: relScopes.join(",") } : {}),
         }), null, 1)}\n`, "utf8");
         console.log(section("Baseline written"));
         console.log(body(`${d.findings.length} findings and ${d.phantomUses} phantom uses are now the line to hold. A run that goes above it fails; everything at or below it passes.`));
@@ -1337,7 +1440,7 @@ export async function doctor(opts) {
             return;
         }
         const verdict = compareToBaseline(d, base, {
-            ...(opts.scopes?.length ? { scope: opts.scopes.join(",") } : {}),
+            ...(relScopes.length ? { scope: relScopes.join(",") } : {}),
         });
         console.log(section(verdict.worse ? "Drift went up" : "Ratchet"));
         for (const line of describeVerdict(verdict))

package/dist/commands/import.js

@@ -857,6 +857,16 @@ export async function takeCensus(root, opts) {
                         ...(v.unslotted.length > 0
                             ? { unplaced: [...new Set(v.unslotted)] }
                             : {}),
+                        /**
+                         * AS NOTAS SÃO OUTRA LISTA - ver `notes` em `variant-read.ts`.
+                         *
+                         * Um layer que FICOU e precisa de um `data-*` não é um look sem lugar: ele está na receita.
+                         * As duas viajavam em `unplaced`, e a tela de causas cobrava conserto de 16 linhas que
+                         * diziam, no próprio texto, que nada tinha sido perdido (dono, 06/08).
+                         */
+                        ...(v.notes.length > 0
+                            ? { renderNotes: [...new Set(v.notes)] }
+                            : {}),
                         ...(Object.keys(v.axes).length > 0 ? { declaredAxes: v.axes } : {}),
                         ...(Object.keys(defaults).length > 0 ? { defaults } : {}),
                     };
@@ -1253,6 +1263,30 @@ export async function takeCensus(root, opts) {
             console.log(body(paint.faint(`  and ${unplacedByComponent.length - 8} more components`)));
         }
     }
+    /**
+     * E AS NOTAS DE RENDERIZAÇÃO, que são o oposto de uma perda.
+     *
+     * O layer ESTÁ na receita: o que falta é um atributo no elemento para ele aplicar. Até 06/08 estas
+     * linhas viajavam junto com as de "não achei onde pôr" - 16 de 33 num repo real -, e a tela de causas
+     * cobrava conserto de quem não tinha o que consertar. Separadas, elas viram o que sempre foram: uma
+     * instrução para quem for renderizar.
+     */
+    const notesByComponent = Object.entries(looks)
+        .filter(([, look]) => (look.renderNotes ?? []).length > 0)
+        .map(([component, look]) => ({
+        component,
+        lines: look.renderNotes ?? [],
+    }));
+    if (notesByComponent.length > 0) {
+        const total = notesByComponent.reduce((n, u) => n + u.lines.length, 0);
+        console.log("");
+        console.log(section("Looks that are in the recipe and need an attribute"));
+        console.log(body(`${total} decision${total === 1 ? "" : "s"} across ${notesByComponent.length} component${notesByComponent.length === 1 ? "" : "s"} were read and KEPT - they apply once the element carries the attribute the line names:`));
+        for (const u of notesByComponent.slice(0, 6))
+            console.log(body(paint.faint(`  ${u.component}: ${u.lines[0]}`)));
+        if (notesByComponent.length > 6)
+            console.log(body(paint.faint(`  and ${notesByComponent.length - 6} more components`)));
+    }
     /**
      * THE DROPS, SAID OUT LOUD. `p-spacing-sm` on a real menu popup read as nothing and
      * the popup shipped with no padding, invisibly - "if the compiler drops them, the drop

package/dist/commands/init.js

@@ -15,6 +15,16 @@ export async function init(opts) {
         pagesDir: opts.pagesDir ?? (target === "next" ? "app" : DEFAULT_CONFIG.pagesDir),
         componentsDir: opts.componentsDir ?? DEFAULT_CONFIG.componentsDir,
         styles: opts.styles === "tailwind" ? "tailwind" : "css",
+        /**
+         * Gravada COM A DATA, e só quando alguém respondeu. Migração é uma fase que termina, e uma fase sem
+         * data é a etiqueta que envelhece em silêncio - o doctor imprime as duas em toda rodada.
+         */
+        ...(opts.intent === "migrate" || opts.intent === "adopt"
+            ? { intent: opts.intent, intentAt: new Date().toISOString() }
+            : {}),
+        ...(opts.absorb === "code" || opts.absorb === "system"
+            ? { absorb: opts.absorb }
+            : {}),
     };
     await writeProjectConfig(root, config);
     console.log("✓ wrote _synthesisui/config.json");
@@ -22,6 +32,10 @@ export async function init(opts) {
     console.log(`  pagesDir:      ${config.pagesDir}`);
     console.log(`  componentsDir: ${config.componentsDir}`);
     console.log(`  styles:        ${config.styles}`);
+    if (config.absorb)
+        console.log(`  absorb:        ${config.absorb}${config.absorb === "code" ? "  (we hand you the CSS block; your file stays yours)" : "  (absorbed values become tokens of the system)"}`);
+    if (config.intent)
+        console.log(`  intent:        ${config.intent}${config.intent === "migrate" ? "  (the doctor leads with what your system does not name yet)" : "  (the doctor leads with what your system already names)"}`);
     // --ds bootstraps the project with a system in one step (tokens + philosophy
     // + rules + CLAUDE.md all arrive via `add`).
     if (opts.ds) {