synthesisui 0.16.418 → 0.16.419

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/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-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.418",
+  "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": {