synthesisui 0.16.417 → 0.16.419

package/dist/commands/add.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
+import { parseRules } from "../doctrine.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
 import { detectAppDirs, globalSheetOf, prefixFrom } from "../global-sheet.js";
 import { lockReference } from "../group-role.js";
@@ -375,9 +376,17 @@ export async function add(slug, opts) {
      * registry working unchanged.
      */
     const stack = await detectStack(projectRoot);
+    /**
+     * AS DUAS ENTRADAS VIRAM A MESMA FORMA ANTES DE TOCAR O DISCO.
+     *
+     * `ruleSet` vem estruturado e `rules` vem como frase - e enquanto a segunda caía direto no
+     * arquivo, o disco dele podia receber uma lista mista sem nada reclamar. `parseRules` normaliza
+     * as duas para `{ text, applies }`, e desfaz o prefixo `ds-a + ds-b:` da forma antiga no
+     * caminho, então um registry que ainda manda frase não perde o alcance da regra.
+     */
     const rules = payload.ruleSet && payload.ruleSet.length > 0
         ? rulesForProject(payload.ruleSet, stack)
-        : (payload.rules ?? []);
+        : parseRules(payload.rules ?? []);
     const leftOut = payload.ruleSet
         ? describeFiltered(payload.ruleSet, stack)
         : null;

package/dist/commands/doctor.js

@@ -16,6 +16,7 @@ import { diagnose, nameToWrite, scanSource, siblingTokens, } from "../doctor/sca
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { withTheirNames } from "../doctor/their-names.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
+import { parseRules } from "../doctrine.js";
 /**
  * `detectAppDirs` SAIU DESTE IMPORT em 09/09: quem pergunta "quais pastas são app?" agora é
  * `readWiringPerApp`, que responde a fiação de cada uma. O comando não escolhe mais um app.
@@ -320,13 +321,23 @@ measured) {
         if (doctrineRaw) {
             try {
                 const parsed = JSON.parse(doctrineRaw);
-                if (Array.isArray(parsed.rules))
+                /**
+                 * AS DUAS FORMAS DO DISCO, lidas pela mesma porta (`parseRules`).
+                 *
+                 * Este filtro era `typeof r === "string"`, e com a regra passando a viajar como dado ele
+                 * DESCARTARIA calado toda regra de uma instalação nova - o pior resultado possível para
+                 * uma doutrina, que é sumir sem ninguém saber. E a leitura pela porta única também
+                 * devolve o alcance às instalações ANTIGAS: o prefixo `ds-a + ds-b:` é desfeito ali, sem
+                 * reimportar nada.
+                 */
+                const parsedRules = parseRules(parsed.rules);
+                if (parsedRules.length > 0)
                     doctrines.push({
                         ...(typeof parsed.version === "number"
                             ? { version: parsed.version }
                             : {}),
                         ...(typeof parsed.name === "string" ? { name: parsed.name } : {}),
-                        rules: parsed.rules.filter((r) => typeof r === "string"),
+                        rules: parsedRules,
                     });
             }
             catch {

package/dist/commands/hook.js

@@ -2,6 +2,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { appendEvent } from "../doctor/ledger.js";
 import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
+import { namesRemoved, previousText, rulesTouchedBy } from "../rule-touched.js";
 import { loadSystem } from "./doctor.js";
 const pass = () => ({ continue: true });
 const speak = (context) => ({
@@ -47,14 +48,80 @@ async function greet(root, rel) {
         "here it only speaks when something needs a name.",
     ].join("\n");
 }
+/**
+ * A REGRA QUE ESTA EDIÇÃO APAGOU - e o que a plataforma diz em vez de calar.
+ *
+ * ═══ O CASO, medido em 12/09 ═══
+ *
+ * O agente dele apagou a serif itálica de seis lugares da landing do `codelevel` e nada avisou. A
+ * regra estava instalada, em disco, a dois diretórios da edição - a décima de vinte e cinco - e era
+ * literalmente sobre isso. Palavras dele ao abrir a etapa: *"o sistema fala antes do dano"*.
+ *
+ * ═══ POR QUE ISTO É UM BLOCO SEPARADO, E VEM PRIMEIRO ═══
+ *
+ * Acrescentar valor solto é DERIVA, e a resposta é o token. Apagar o que uma regra escrita exige é
+ * uma EMENDA AO SISTEMA, e a resposta é outra: ou a regra muda, ou o caso é uma exceção registrada.
+ * As duas saídas são decisão de uma PESSOA, e nenhuma delas é "escreva isto de volta".
+ *
+ * Se as duas informações saíssem na mesma lista, um agente que acabou de aprender *"lista →
+ * proponha o token"* leria a emenda com o mesmo reflexo - e é o mesmo defeito que a revisão de DX
+ * já tinha encontrado na lista dos valores sem nome.
+ *
+ * ═══ E NADA AQUI BLOQUEIA NEM BATIZA ═══
+ *
+ * O retorno continua sendo contexto: `continue: true` em todo caminho. E nenhum nome é proposto -
+ * a frase diz qual regra, qual nome declarado amarra a regra ao que saiu, e devolve a decisão.
+ */
+async function amendment(root, rel, after, rules, declared) {
+    if (rules.length === 0)
+        return [];
+    const before = await previousText(root, rel);
+    if (before == null)
+        return [];
+    const touched = rulesTouchedBy(namesRemoved(before, after, declared), rules);
+    if (touched.length === 0)
+        return [];
+    return [
+        /**
+         * A FRASE FALA DO ARQUIVO, NUNCA DESTA EDIÇÃO - achado da revisão de QA no fecho.
+         *
+         * Ela dizia *"this edit removes…"*, e o "antes" é o último COMMIT: da segunda escrita em
+         * diante aquela edição não removeu nada, e a frase virava mentira enquanto se repetia. Dita
+         * sobre o ARQUIVO ela é verdadeira todas as vezes - e a repetição em si continua sendo dívida
+         * declarada em `steps/20-fora-do-escopo.md`.
+         */
+        `${rel} - this file no longer has what a rule of this system asks for.`,
+        "",
+        ...touched.flatMap(({ rule, through }) => [
+            `  ${through} is gone from this file, and the system says:`,
+            `    "${rule.text}"`,
+        ]),
+        "",
+        /**
+         * "DRIFT" É PALAVRA NOSSA, e o portão de vocabulário (`INV-VOC-05`) a barrou nesta linha -
+         * com razão: ela é o nome interno para um valor fora do sistema, e quem lê esta saída é o
+         * repositório DELE. A frase diz a mesma coisa com o que o produto já escreve duas linhas
+         * abaixo, "written by hand".
+         */
+        "That is an amendment to the system, not a value written by hand - so there is no token to put back.",
+        "Tell the person which it is: the rule changes, or this case is an exception worth recording.",
+    ];
+}
 async function report(root, filePath) {
-    const { table } = await loadSystem(root);
+    const { table, doctrines } = await loadSystem(root);
     if (table.byName.size === 0)
         return null;
-    const src = await readFile(filePath, "utf8").catch(() => "");
-    if (!src)
+    /**
+     * VAZIO NÃO É ILEGÍVEL - achado da revisão de QA no fecho, e a remoção mais destrutiva possível
+     * produzia a menor saída possível. `catch` devolve `null` quando o arquivo não pode ser lido;
+     * um arquivo TRUNCADO devolve `""`, e apagar todo o conteúdo de um arquivo governado apaga todas
+     * as regras dele de uma vez - que é exatamente quando falar importa mais.
+     */
+    const src = await readFile(filePath, "utf8").catch(() => null);
+    if (src == null)
         return null;
     const rel = relative(root, filePath);
+    const broke = await amendment(root, rel, src, doctrines.flatMap((doc) => doc.rules), table.declared).catch(() => []);
     const d = diagnose([scanSource(rel, src, table)]);
     const named = d.findings.filter((f) => nameToWrite(f));
     /**
@@ -84,7 +151,10 @@ async function report(root, filePath) {
         named: named.length,
         phantoms: phantoms.length,
     });
-    if (named.length === 0 && phantoms.length === 0 && unnamed.length === 0)
+    if (broke.length === 0 &&
+        named.length === 0 &&
+        phantoms.length === 0 &&
+        unnamed.length === 0)
         return greet(root, rel);
     // A report IS the evidence the greeting exists to provide, so it counts as the
     // introduction. Otherwise a project whose first file had drift would get the
@@ -109,16 +179,31 @@ async function report(root, filePath) {
      * é "deixe como está" volta a ser dito na próxima escrita naquele arquivo, porque não existe
      * memória por linha e criar uma é comportamento novo. Está medido em `steps/11-fora-do-escopo.md`.
      */
+    /**
+     * A EMENDA VEM ANTES DO VALOR, e sozinha quando é a única coisa a dizer.
+     *
+     * Ela é a mais cara de ignorar: um valor solto se conserta depois, e uma regra apagada vira o
+     * próximo agente restaurando a serif citando a doutrina, com o dono achando que ele alucinou.
+     */
+    if (broke.length > 0 && named.length === 0 && phantoms.length === 0)
+        return broke.join("\n");
     const sample = unnamed
         .slice(0, 3)
         .map((f) => `line ${f.line} ${f.literal}`)
         .join(", ");
-    if (named.length === 0 && phantoms.length === 0)
+    if (broke.length === 0 && named.length === 0 && phantoms.length === 0)
         return [
             `${rel} - ${unnamed.length} value${unnamed.length === 1 ? "" : "s"} here ${unnamed.length === 1 ? "has" : "have"} no name in this system, and nothing to replace ${unnamed.length === 1 ? "it" : "them"} with: ${sample}${unnamed.length > 3 ? `, +${unnamed.length - 3} more` : ""}.`,
             "Do not invent a name - leave them, or ask the person what they would call it.",
         ].join("\n");
-    const lines = [`${rel} - checked against ${table.name ?? table.slug}.`];
+    /**
+     * E QUANDO HÁ AS DUAS COISAS, a emenda lidera o relatório - mesma razão: ela é a que ninguém
+     * conserta depois, e a lista de valores abaixo dela ensina a diferença entre deriva e emenda.
+     */
+    const lines = [
+        ...(broke.length > 0 ? [...broke, ""] : []),
+        `${rel} - checked against ${table.name ?? table.slug}.`,
+    ];
     if (named.length > 0) {
         lines.push("", "Values written by hand that this system already has a name for:", ...named
             .slice(0, 20)
@@ -169,8 +254,18 @@ export async function hook(opts) {
     const abs = resolve(root, file);
     // Our own installed artifacts are the answer, not the problem - and a file
     // outside the project is none of our business.
-    const inside = !relative(root, abs).startsWith("..");
-    if (!UI_FILE.test(abs) || !inside || abs.includes("_synthesisui")) {
+    /**
+     * O CAMINHO TESTADO É O RELATIVO - achado da revisão de QA no fecho.
+     *
+     * `abs.includes("_synthesisui")` olhava o caminho ABSOLUTO, então quem clonasse o projeto para
+     * qualquer diretório com esse nome no meio (`~/_synthesisui-demo/app`) tinha TODOS os arquivos
+     * pulados e um hook permanentemente mudo. O relativo já estava calculado uma linha acima.
+     */
+    const rel = relative(root, abs);
+    const inside = !rel.startsWith("..");
+    if (!UI_FILE.test(abs) ||
+        !inside ||
+        rel.split("/").includes("_synthesisui")) {
         process.stdout.write(`${JSON.stringify(pass())}\n`);
         return;
     }

package/dist/commands/mcp.js

@@ -12,6 +12,7 @@ import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
 import { nearestToken, normalizeValue, tokenFor } from "../doctor/tokens.js";
+import { ruleLine } from "../doctrine.js";
 import { fromCensus } from "../memory/observation.js";
 import { handleRecall, handleRemember, MEMORY_TOOLS } from "../memory/tools.js";
 import { readInstalledConvention } from "../project-facts.js";
@@ -523,7 +524,13 @@ async function systemDoctrine(root) {
         rules.length > 0
             ? `# Rules - maximum authority, ${rules.length} of them${pinned ? `, as of v${pinned}` : ""}`
             : "",
-        ...rules.map((r) => `- ${r}`),
+        /**
+         * `ruleLine` É O QUE MANTÉM ESTA SAÍDA IDÊNTICA. A regra passou a viajar como dado
+         * (`{ text, applies }`), e interpolar o objeto aqui imprimiria `[object Object]` sem o `tsc`
+         * reclamar - um template literal aceita qualquer coisa. O alcance volta a ser prefixo na hora
+         * de MOSTRAR, que é onde ele sempre esteve para quem lê.
+         */
+        ...rules.map((r) => `- ${ruleLine(r)}`),
     ].filter(Boolean);
     const pulse = await sessionPulse(root, pinned);
     return [
@@ -1706,7 +1713,7 @@ cli) {
             const plan = composePlan({
                 documents,
                 table,
-                rules: doctrines.flatMap((d) => d.rules),
+                rules: doctrines.flatMap((d) => d.rules).map(ruleLine),
                 /**
                  * A regra tem a FRASE e o PACOTE em campos separados (`text`,
                  * `requires`) - mandar a frase sozinha esconderia o que instalar, e

package/dist/doctrine.js

@@ -0,0 +1,96 @@
+/**
+ * A REGRA DO SISTEMA DELE, COMO DADO - e não como frase.
+ *
+ * ═══ O QUE ABRIU ESTE ARQUIVO, medido em 12/09 ═══
+ *
+ * O agente dele apagou a serif itálica de seis lugares da landing do `codelevel`, e nada avisou.
+ * A regra existia, instalada, em disco, no `doctrine.json` daquele projeto - a décima de vinte e
+ * cinco, verbatim:
+ *
+ *     "A display headline breaks onto a line set in the serif, italic - that line carries the
+ *      emphasis of the sentence, never the whole headline."
+ *
+ * O conhecimento estava a dois diretórios de distância da edição e ninguém o entregou. Palavras
+ * dele: *"o sistema fala antes do dano"*.
+ *
+ * ═══ A CAUSA, e ela é de uma linha ═══
+ *
+ * Do NOSSO lado a regra é estruturada: `applies` diz quais componentes ela governa, e
+ * `rules-for-component.ts` casa por esse campo há semanas. No caminho até o disco dele,
+ * `rulesForProject` achatava a estrutura num PREFIXO DE PROSA - `ds-button + ds-icon-button: <o
+ * texto>` - e a partir dali nada mais podia perguntar *"esta regra vale para o arquivo que está
+ * sendo escrito?"*. A resposta existia e era jogada fora na exportação.
+ *
+ * ═══ POR QUE UM MÓDULO, e não um `JSON.parse` em cada leitor ═══
+ *
+ * O `doctrine.json` é lido em três lugares - o doctor, o `system_doctrine` do MCP e o compositor
+ * de plano -, e a partir de agora existem DUAS formas no disco do mundo: a nova, estruturada, e a
+ * antiga, em string, que está instalada em todo projeto que rodou `connect` antes de hoje. Três
+ * leitores decidindo sozinhos o que fazer com duas formas são três chances de discordar sobre a
+ * mesma regra.
+ *
+ * ═══ E A FORMA ANTIGA NÃO PERDE O ALCANCE ═══
+ *
+ * O prefixo era um achatamento REVERSÍVEL: `ds-card + ds-noise-overlay: <texto>` carrega os dois
+ * nomes, só que em prosa. `parseRule` desfaz isso na leitura, então uma instalação antiga ganha o
+ * alcance de volta sem reimportar nada - que é a diferença entre uma correção que alcança quem já
+ * é cliente e uma que só alcança quem instalar amanhã.
+ */
+/**
+ * O PREFIXO QUE A FORMA ANTIGA USA: `ds-card + ds-noise-overlay: `.
+ *
+ * Ancorado no começo e exigindo o `ds-` em cada nome, porque uma frase pode conter dois pontos -
+ * *"Dark is a class, never the OS preference: @custom-variant dark"* é a segunda regra real do
+ * sistema dele, e sem a âncora ela viraria um componente chamado `Dark is a class, never the OS
+ * preference`.
+ */
+const LEGACY_SCOPE = /^((?:ds-[a-z0-9-]+)(?:\s*\+\s*ds-[a-z0-9-]+)*)\s*:\s*/;
+/** Uma regra vinda do disco, em qualquer das duas formas - ou `null` quando não há frase. */
+export function parseRule(raw) {
+    if (typeof raw === "string") {
+        const text = raw.trim();
+        if (!text)
+            return null;
+        const m = LEGACY_SCOPE.exec(text);
+        if (!m)
+            return { text, applies: [] };
+        return {
+            text: text.slice(m[0].length).trim(),
+            applies: m[1].split("+").map((n) => n.trim().replace(/^ds-/, "")),
+        };
+    }
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const text = typeof r.text === "string" ? r.text.trim() : "";
+    if (!text)
+        return null;
+    const applies = Array.isArray(r.applies)
+        ? r.applies.filter((a) => typeof a === "string" && !!a.trim())
+        : [];
+    return { text, applies: applies.map((a) => a.trim().replace(/^ds-/, "")) };
+}
+/** Todas as regras de um `doctrine.json`, nas duas formas, sem as ilegíveis. */
+export function parseRules(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const rule = parseRule(entry);
+        if (rule)
+            out.push(rule);
+    }
+    return out;
+}
+/**
+ * A REGRA COMO ALGUÉM A LÊ - a mesma frase que o disco carregava antes.
+ *
+ * O alcance volta a ser prefixo AQUI, na hora de mostrar, e não no dado. Quem imprime continua
+ * imprimindo o que sempre imprimiu; quem PERGUNTA passa a ter o campo.
+ */
+export function ruleLine(rule) {
+    const scope = rule.applies.length > 0
+        ? `${rule.applies.map((a) => `ds-${a}`).join(" + ")}: `
+        : "";
+    return `${scope}${rule.text}`;
+}

package/dist/install-marks.js

@@ -344,7 +344,7 @@ export const COUNTED_DIFFERENTLY = "this run counts every length in a shorthand
  * e nós engolimos". Agora sai `line 12  #ff00aa`, sem uma única proposta de nome nosso. Um hook
  * pinado antes desta versão aconselha MENOS, que é a régua desta marca.
  */
-export const CHECKER_SINCE = "0.16.413";
+export const CHECKER_SINCE = "0.16.419";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/rule-filter.js

@@ -1,18 +1,3 @@
-/**
- * WHICH RULES BELONG IN *THIS* PROJECT.
- *
- * A rule travels with the design system, and the system gets installed places it
- * was never written for. "The state arrives through this hook" is true about Next
- * and actively wrong about Vue - so a rule carries the environments it holds in,
- * and the filtering happens HERE, because the consumer's stack is the one thing
- * the platform cannot know (dono, 01/08).
- *
- * THE DEFAULT WHEN WE CANNOT TELL IS TO KEEP IT. A rule whose condition does not
- * match is removed, because obeying it would be a mistake. A rule we cannot
- * evaluate - the stack came back empty, or it names something we do not detect -
- * stays, because a rule nobody can judge is safer present than silently gone.
- * Those are two different situations and they get two different answers.
- */
 const norm = (v) => v.trim().toLowerCase();
 /**
  * True when this rule holds in a project built with `stack`.
@@ -45,10 +30,18 @@ export function rulesForProject(rules, stack) {
         const text = rule.text?.trim();
         if (!text)
             continue;
-        const scope = rule.applies?.length > 0
-            ? `${rule.applies.map((a) => `ds-${a}`).join(" + ")}: `
-            : "";
-        out.push(`${scope}${text}`);
+        /**
+         * O ALCANCE SAI DAQUI COMO CAMPO, e não mais como prefixo de prosa.
+         *
+         * Esta função achatava `applies` em `ds-a + ds-b: <texto>` e era o último ponto onde a
+         * estrutura existia: do disco em diante, nada mais podia perguntar se a regra vale para o
+         * arquivo que está sendo escrito. Foi assim que a regra da serif do `codelevel` - a décima
+         * de vinte e cinco, instalada, correta - não disse nada quando um agente a apagou de seis
+         * lugares (12/09).
+         *
+         * A frase não mudou: `ruleLine` volta a montar o prefixo na hora de MOSTRAR.
+         */
+        out.push({ text, applies: (rule.applies ?? []).map((a) => a.trim()) });
     }
     return out;
 }

package/dist/rule-touched.js

@@ -0,0 +1,175 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/**
+ * O QUE ESTA EDIÇÃO APAGOU, E QUAL REGRA DELE ISSO TOCA.
+ *
+ * ═══ O CASO, medido em 12/09 ═══
+ *
+ * O agente dele apagou a serif itálica de seis lugares da landing do `codelevel`. A regra existia,
+ * instalada: *"A display headline breaks onto a line set in the serif, italic - that line carries
+ * the emphasis of the sentence, never the whole headline."* Nada avisou.
+ *
+ * Duas razões, e este arquivo é as duas. A checagem lia o ARQUIVO depois da escrita - e uma
+ * remoção é, por construção, aquilo que não está mais lá. E ela media VALOR SOLTO contra token,
+ * nunca regra.
+ *
+ * ═══ O ANTES VEM DO GIT, e não do payload do cliente ═══
+ *
+ * O hook recebe `tool_input.file_path` e o cliente PODE mandar o texto anterior - mas o formato é
+ * de cada cliente, muda entre versões, e um produto que se apoia nele funciona num editor e cala
+ * no seguinte. O git é o mesmo em todo lugar e responde a pergunta certa: *o que esta árvore
+ * removeu em relação ao último commit?* - que é exatamente o que ele vai empurrar.
+ *
+ * SEM GIT, SEM ARQUIVO NO HEAD, OU ARQUIVO NOVO: não há "antes", então não há remoção. Silêncio é
+ * a resposta correta, e não uma falha - um arquivo novo não apagou nada de ninguém.
+ *
+ * ═══ E O CASAMENTO É POR VOCABULÁRIO DECLARADO, nunca por palavra em inglês ═══
+ *
+ * A tentação é procurar as palavras da regra no diff. Isso casaria *"never"* com qualquer coisa e
+ * transformaria a checagem numa fonte de falso positivo - e um falso positivo custa mais que
+ * silêncio aqui, porque ele treina a pessoa a ignorar a saída e depois a desinstalar o hook.
+ *
+ * Então os dois lados são amarrados pelo que o SISTEMA DELE DECLARA. Uma regra "toca" o que foi
+ * apagado quando um nome declarado aparece nos dois: no texto da regra e no que saiu do arquivo.
+ * No caso real: o sistema declara `--font-serif`, a regra fala em `serif`, e a edição removeu
+ * `font-serif` seis vezes.
+ */
+/** Como o texto anterior era, ou `null` quando não há "antes" que se possa provar. */
+export async function previousText(root, rel) {
+    try {
+        /**
+         * O `./` NÃO É ENFEITE, e a população do incidente escondia isto.
+         *
+         * `git show HEAD:<caminho>` resolve a partir do TOPO da árvore, nunca do `cwd`. No `codelevel`
+         * a raiz do git e a raiz do projeto coincidem, então os dois davam no mesmo. Num monorepo com
+         * o `_synthesisui` em `apps/landing/`, `HEAD:app/x.tsx` devolve o arquivo da RAIZ - outro
+         * arquivo -, e a checagem ou cala ou acusa uma remoção que ninguém fez.
+         *
+         * `HEAD:./<caminho>` resolve a partir do `cwd`, que é a raiz do projeto. Reproduzido em 12/09
+         * num repositório de teste com os dois arquivos no mesmo caminho relativo.
+         */
+        const { stdout } = await run("git", ["show", `HEAD:./${rel}`], {
+            cwd: root,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * OS NOMES DECLARADOS QUE ESTE ARQUIVO DEIXOU DE REFERENCIAR.
+ *
+ * ═══ POR QUE NÃO É UM DIFF DE LINHAS ═══
+ *
+ * A primeira versão desta função comparava as LINHAS que sumiram, e o spec do A6 a derrubou na
+ * primeira execução: trocar uma palavra dentro de uma linha faz a linha inteira "sumir", então
+ * editar o texto de um heading acusava a remoção da família que continua ali, na mesma linha.
+ * Falso positivo é o defeito que esta checagem menos pode ter - ele treina a pessoa a ignorar a
+ * saída, e depois a desinstalar o hook.
+ *
+ * A pergunta certa é sobre PRESENÇA, não sobre texto: este arquivo referenciava `--font-serif` e
+ * não referencia mais? Ela é imune a reformatação, a mover código de lugar e a reescrever a frase
+ * em volta - e é exatamente o que uma regra do sistema fala sobre.
+ *
+ * O PREÇO, dito em voz alta: remover cinco de seis usos não é remoção - o nome continua no
+ * arquivo. É a troca certa. A regra fala sobre o sistema ter aquela decisão presente, e um uso que
+ * fica mantém a decisão presente; acusar por contagem transformaria toda refatoração num alarme.
+ */
+export function namesRemoved(before, after, declared) {
+    const had = declaredNamesIn(before, declared);
+    if (had.length === 0)
+        return [];
+    const kept = new Set(declaredNamesIn(after, declared));
+    return had.filter((name) => !kept.has(name));
+}
+/**
+ * A FOLHA DE UM NOME DECLARADO - `--font-serif` → `serif`, `--ds-color-brand` → `brand`.
+ *
+ * É por ela que uma regra escrita em prosa encontra um nome: ninguém escreve *"a headline quebra
+ * numa linha em `--ds-typography-families-serif`"*, escreve *"in the serif"*.
+ */
+const leafOf = (name) => name.replace(/^--/, "").split("-").pop() ?? "";
+/**
+ * ═══ QUANDO UMA FOLHA IDENTIFICA - e a resposta sai do CORPUS DELE, não de uma lista nossa ═══
+ *
+ * A primeira versão disto era uma lista fechada de vinte e sete palavras em inglês (`body`,
+ * `size`, `color`…) mais um corte por tamanho. A revisão de contrato derrubou as duas coisas, e
+ * pelo motivo certo: um cliente que escreve o sistema dele em português (`--fonte-corpo` → `corpo`)
+ * não recebia filtragem nenhuma e pagava em falso positivo - o defeito exato que este módulo diz
+ * não poder ter. E o `>= 4` descartava folha curta e real: `--ds-color-ink` tem folha `ink`.
+ *
+ * A FORMA GERAL É SELETIVIDADE, e ela é derivada do que ELE declarou: **uma folha identifica quando
+ * seleciona exatamente UMA regra do corpus dele.** Nenhuma palavra de idioma nenhum participa.
+ *
+ * MEDIDO nas 25 regras reais de uma população viva:
+ *
+ *     rejeitadas por selecionarem mais de uma regra   `size` (5)  `body` (3)  `default` (2)
+ *     mantidas por selecionarem exatamente uma        `serif`  `violet`  `grain`  `aurora`
+ *
+ * Mesmo resultado da lista curada, sem uma palavra nossa no núcleo.
+ *
+ * E O NOME ESCRITO POR INTEIRO NÃO PASSA POR ESSE TESTE: quem escreve `--font-serif` dentro da
+ * regra não deixou ambiguidade nenhuma para resolver, e duas regras podem falar do mesmo token de
+ * propósito.
+ */
+/** Um nome, como uma PALAVRA inteira - `serif` não casa dentro de `serifed`. */
+const mentions = (text, word) => new RegExp(`(^|[^a-z0-9-])${word}([^a-z0-9-]|$)`, "i").test(text);
+/**
+ * OS NOMES DECLARADOS QUE ESTE TRECHO REFERENCIA.
+ *
+ * Três formas, porque um projeto escreve o mesmo token de três jeitos: `var(--font-serif)` no CSS,
+ * `--font-serif` cru numa declaração, e `font-serif` como utility - que é o idioma medido em 72%
+ * dos `.tsx` dele. Sem a terceira, um repositório Tailwind inteiro não referenciaria nada.
+ */
+export function declaredNamesIn(text, declared) {
+    const found = new Set();
+    for (const name of declared) {
+        const bare = name.replace(/^--/, "");
+        if (text.includes(name) || mentions(text, bare))
+            found.add(name);
+    }
+    return [...found];
+}
+/** A regra escreve este nome - por inteiro, ou pela folha dele. */
+const writesName = (text, name) => {
+    if (text.includes(name) || mentions(text, name.replace(/^--/, "")))
+        return "full";
+    const leaf = leafOf(name);
+    return leaf && mentions(text, leaf) ? "leaf" : null;
+};
+/**
+ * AS REGRAS QUE O QUE FOI APAGADO TOCA - e o nome que faz a ligação.
+ *
+ * O nome sai junto porque a frase que o hook escreve precisa dele: *"você removeu `font-serif`, e
+ * esta regra é sobre isso"* é verificável; *"você quebrou uma regra"* é uma acusação sem prova.
+ */
+export function rulesTouchedBy(names, rules) {
+    if (names.length === 0)
+        return [];
+    const out = [];
+    const taken = new Set();
+    for (const name of names) {
+        const hits = rules
+            .map((rule) => ({ rule, how: writesName(rule.text, name) }))
+            .filter((h) => h.how !== null);
+        if (hits.length === 0)
+            continue;
+        /**
+         * A FOLHA SÓ VALE QUANDO ELA SELECIONA UMA REGRA SÓ. Uma folha que casa com três regras não
+         * está identificando um assunto - ela está aparecendo em prosa, e falar seria ruído.
+         * O nome escrito por inteiro não passa por este teste: ali não há ambiguidade a resolver.
+         */
+        const full = hits.filter((h) => h.how === "full");
+        const chosen = full.length > 0 ? full : hits.length === 1 ? hits : [];
+        for (const { rule } of chosen) {
+            if (taken.has(rule))
+                continue;
+            taken.add(rule);
+            out.push({ rule, through: name });
+        }
+    }
+    return out;
+}

package/package.json

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