synthesisui 0.16.204 → 0.16.207

package/dist/commands/align.js

@@ -2,23 +2,30 @@ import { readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { pinnedHookVersion } from "../agent-wiring.js";
+import { isOlderCli } from "../cli-version.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { unsentEvents } from "../doctor/ledger.js";
+import { CHECKER_SINCE, MATERIALISER_SINCE, READER_SINCE, } from "../install-marks.js";
 import { measuredScope } from "../measured-scope.js";
-import { READER } from "../reader-version.js";
 /**
- * Qual leitor mediu o censo em disco, quando ele o registra.
+ * QUAL CLI MEDIU O CENSO EM DISCO - e era o `reader`, um inteiro, até 11/08.
  *
- * `null` para censo anterior a esta marca: um censo que não diz quem o leu não prova nada, e supor
- * que ele é velho faria toda pessoa que ainda não re-mediu ver o aviso para sempre.
+ * O carimbo `ledger.reader` existe e continua sendo gravado, mas ele não serve para responder esta
+ * pergunta: ficou parado em 1 enquanto os leitores mudavam, então censos de julho e de ontem levam
+ * o mesmo número e nada os separa. A versão que mediu separa - ver `READER_SINCE`.
+ *
+ * `null` para censo que não diz quem o mediu: um censo assim não prova nada, e supor que ele é
+ * velho faria toda pessoa que ainda não re-mediu ver o aviso para sempre.
  */
-async function censusReader(root) {
+async function censusMeasuredBy(root) {
     const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => null);
     if (!raw)
         return null;
     try {
         const c = JSON.parse(raw);
-        return typeof c.ledger?.reader === "number" ? c.ledger.reader : null;
+        return typeof c.ledger?.cli === "string" && c.ledger.cli
+            ? c.ledger.cli
+            : null;
     }
     catch {
         return null;
@@ -59,6 +66,28 @@ async function credentials(home) {
  *
  * Separada de propósito: ela é a que sempre roda, e é testável sem servidor nenhum.
  */
+/**
+ * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
+ *
+ * `installed` é a versão que escreveu a coisa (a pasta, ou o pin do hook); `running` é o CLI de hoje;
+ * `since` é a última versão em que aquilo mudou de verdade - ver `install-marks.ts`.
+ *
+ * As duas condições, e nenhuma delas basta sozinha:
+ *
+ *     o que está instalado é ANTERIOR à última mudança    senão `upgrade` reescreve bytes idênticos
+ *     o CLI de hoje já ALCANÇOU essa mudança              senão `upgrade` escreve a mesma coisa velha
+ *
+ * A segunda é a que quase escapou: quem roda um CLI antigo com uma pasta da mesma época não ganha
+ * nada com `upgrade` - o comando usa o CLI que ela tem. Mandar rodar ali é gastar a atenção dela num
+ * comando que não pode mudar nada, e o caminho de verdade é outro (`connect`).
+ */
+function behind(installed, running, since) {
+    if (!installed || !running)
+        return null;
+    if (!isOlderCli(installed, since))
+        return null;
+    return isOlderCli(running, since) ? null : installed;
+}
 export async function localMisalignments(root, 
 /**
  * `home` é injetável porque a SESSÃO mora nele e não no repo - e uma verificação que lê o home da
@@ -97,11 +126,13 @@ opts = {}) {
      * leitura de antes e NENHUMA re-interpretação nossa alcança isso. Só uma medição nova alcança, e
      * ela é um comando que ninguém tinha motivo para rodar.
      *
-     * Compara `READER`, não a string do CLI: em 07/08 o CLI subiu quatro vezes e nenhuma delas mudou um
-     * leitor - pedir re-medição em cada bump faria a pessoa parar de ler estas linhas.
+     * Compara contra `READER_SINCE`, e não contra a string do CLI: em 07/08 o CLI subiu quatro vezes e
+     * nenhuma delas mudou um leitor - pedir re-medição em cada bump faria a pessoa parar de ler estas
+     * linhas. E não contra o carimbo `reader`, que ficou parado em 1 enquanto os leitores andavam:
+     * medido em 11/08, 12 de 36 componentes têm árvore diferente entre o leitor de 07/08 e o de hoje.
      */
-    const reader = await censusReader(root);
-    if (reader != null && reader !== READER)
+    const measuredBy = await censusMeasuredBy(root);
+    if (behind(measuredBy, cli, READER_SINCE))
         out.push({
             says: `the measurement stored in this repo was read by an older reader, so what the platform knows about your components is what that reader could see. A re-measure is the only thing that reaches it - the fix lives on this machine, not on the server.`,
             run: "npx synthesisui sync",
@@ -147,8 +178,12 @@ opts = {}) {
      * O `upgrade` conserta, e esta linha existe para quem ainda não rodou: a verificação de abertura é
      * o único lugar que fala sem ser perguntado. Apontava `connect` até 07/08, quando o dono nomeou a
      * incoerência - a palavra que significa atualizar era a única que não atualizava.
+     *
+     * COMPARA `MATERIALISER_SINCE`, E NÃO A STRING DO CLI - a mesma correção que o `READER` recebeu do
+     * lado da medição, e que este lado não tinha. Medido: de 79 bumps, 10 mudaram o que vai para esta
+     * pasta. Os outros 69 mandavam rodar `upgrade` para reescrever bytes idênticos.
      */
-    const folderBehind = cli && lock.cli && lock.cli !== cli ? lock.cli : null;
+    const folderBehind = behind(lock.cli, cli, MATERIALISER_SINCE);
     /**
      * O HOOK, MEDIDO NELE MESMO - e não pelo `.lock`, que é um proxy que se move sozinho.
      *
@@ -159,9 +194,13 @@ opts = {}) {
      *
      * `pinnedHookVersion` devolve `null` numa instalação local, onde o hook segue o `node_modules` e
      * nunca está atrás por si.
+     *
+     * E COMPARA `CHECKER_SINCE` pelo mesmo motivo da linha acima: o hook estar pinado numa versão
+     * anterior só importa quando o checador de hoje veria algo que o pinado não vê. De 79 bumps, 34
+     * mudaram o checador - nos outros 45 esta linha acusava um pin que se comporta igual.
      */
     const pinned = await pinnedHookVersion(root).catch(() => null);
-    const hookBehind = cli && pinned && pinned !== cli ? pinned : null;
+    const hookBehind = behind(pinned, cli, CHECKER_SINCE);
     /**
      * UMA CAUSA, UMA LINHA - e as duas metades nomeadas dentro dela.
      *

package/dist/doctor/fragments.js

@@ -58,6 +58,36 @@ const MODULE_REF = /\$\{\s*[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*\s*\}/g;
  * que nenhum leitor cobre (`sx`, `styled`, `runtime`) já saem com o motivo, porque nesses casos o
  * motivo é a própria forma e não depende de leitura.
  */
+/**
+ * O QUE ESTÁ DENTRO DE UM `cn(...)` E NÃO É CLASSE - e por que isto vira número na tela dele.
+ *
+ * O corpo da chamada é varrido por literal, e todo literal virava um fragmento de estilo. Dois deles
+ * nunca foram estilo, e a esteira estava dizendo ao cliente que não conseguia ler o que ele nem
+ * escreveu:
+ *
+ *     status === "success" ? "bg-success-500" : ...     "success" é OPERANDO da comparação
+ *     // ... to prevent the "short width" issue        "short width" está num COMENTÁRIO
+ *
+ * MEDIDO EM 11/08 no repo real, sobre as 26 declarações que o censo listava como `value-not-read`:
+ *
+ *      8 (31%)  operando de ===   Card, RadioCard x4, SelectionCard x2
+ *      2  (8%)  comentário        Input, Tag
+ *     16 (61%)  classe de verdade  sr-only, flex flex-col, data-[side=top]:top-full, ...
+ *
+ * Ou seja: 10 das 26 eram acusação NOSSA. E a lei 8 é explícita - lacuna declarada é confiança,
+ * mas lacuna FALSA custa o mesmo que a escondida: ela manda a pessoa procurar um problema que não
+ * existe no código dela, e gasta a credibilidade do número que está certo.
+ */
+/** Apaga comentários preservando o COMPRIMENTO, senão todo índice depois deles aponta para a linha errada. */
+function blankComments(body) {
+    return body
+        .replace(/\/\*[\s\S]*?\*\//g, (m) => " ".repeat(m.length))
+        .replace(/\/\/[^\n]*/g, (m) => " ".repeat(m.length));
+}
+/** `size === "md"`: o literal é o que está sendo COMPARADO, e comparar não é vestir. */
+function isComparedTo(body, index) {
+    return /(?:===|!==|==|!=)\s*$/.test(body.slice(0, index));
+}
 export function fragmentsOfSource(file, source) {
     const out = [];
     const at = (index) => source.slice(0, index).split("\n").length;
@@ -93,12 +123,14 @@ export function fragmentsOfSource(file, source) {
      * classe escrita à mão - a forma mais comum do repo dele (113 arquivos).
      */
     for (const call of source.matchAll(CALL_LITERAL)) {
-        const body = call[1] ?? "";
+        const body = blankComments(call[1] ?? "");
         const base = (call.index ?? 0) + (call[0].length - body.length - 1);
         for (const s of body.matchAll(STRING_IN_CALL)) {
             const text = s[1] ?? s[2] ?? "";
             if (!LOOKS_LIKE_CLASS.test(text))
                 continue;
+            if (isComparedTo(body, s.index ?? 0))
+                continue;
             push("class", base + (s.index ?? 0), text);
         }
     }

package/dist/install-marks.js

@@ -0,0 +1,92 @@
+/**
+ * QUANDO O QUE ESTÁ INSTALADO NESTA MÁQUINA FICOU PARA TRÁS DE VERDADE.
+ *
+ * Duas coisas do CLI vivem no repositório de quem usa e NÃO se atualizam sozinhas: os arquivos que o
+ * `add` escreve em `_synthesisui/ds/<slug>`, e o hook que roda depois de cada escrita do agente - que
+ * fica pinado de propósito, porque comportamento que muda sob você é indebugável.
+ *
+ * O `align` avisava sobre as duas comparando a STRING DA VERSÃO do CLI. É a mesma armadilha que o
+ * `READER` já tinha resolvido do lado da medição, e que ninguém tinha aplicado aqui. Medido em 11/08
+ * sobre os 79 últimos bumps deste repositório:
+ *
+ *     mudaram o que o `upgrade` ESCREVE     20 (25%)
+ *     mudaram o que o HOOK roda             34 (43%)
+ *     não mudaram NENHUM dos dois           27 (34%)
+ *
+ * Um terço dos bumps mandava a pessoa rodar `upgrade` por absolutamente nada, com as DUAS linhas na
+ * tela. E o custo não é o incômodo: um alarme que toca quando está tudo certo é o alarme que ela
+ * aprende a pular no dia em que ele estiver dizendo a verdade.
+ *
+ * O dono nomeou isso em 11/08 pela pergunta certa - *"por que foi necessário atualizar o CLI dessa
+ * vez?"* - sobre um bump que mexeu no `clean` e numa frase, e não tocou a pasta de ninguém.
+ *
+ * ESTAS MARCAS SÃO VERSÕES, e não números de série, por um motivo prático: elas comparam contra o que
+ * já está gravado no `.lock` e no hook dos installs QUE JÁ EXISTEM. Um contador novo precisaria ser
+ * escrito primeiro, e o primeiro contato com ele acusaria todo mundo uma vez - exatamente o alarme à
+ * toa que isto remove.
+ *
+ * A família inteira, e o que cada uma alcança:
+ *
+ *     READER              a medição na máquina dela         ->  npx synthesisui sync
+ *     COMPILER            o CSS de uma versão já instalada  ->  npx synthesisui connect
+ *     INTERPRETATION      a nossa metade, no servidor       ->  sem comando
+ *     MATERIALISER_SINCE  os arquivos da pasta dele         ->  npx synthesisui upgrade
+ *     CHECKER_SINCE       o hook que lê o que o agente faz  ->  npx synthesisui upgrade
+ *
+ * COMO SE MEXE NELAS: não se lembra, o spec cobra. `install-marks.spec.ts` guarda o fingerprint dos
+ * arquivos que decidem cada marca e fica vermelho quando eles mudam sem a marca acompanhar. O
+ * `READER` nasceu sem esse portão em 07/08 e a disciplina falhou na primeira oportunidade que teve:
+ * `d90260cb` acrescentou 47 linhas a `anatomy-from-sketch.ts` - uma mudança que muda o censo dos
+ * mesmos arquivos - e o `READER` continua em 1 até hoje. Uma marca mantida à mão sem portão é uma
+ * marca errada esperando a hora.
+ */
+/**
+ * A ÚLTIMA VERSÃO EM QUE O QUE O `upgrade` ESCREVE NO REPO DELE MUDOU.
+ *
+ * Um install escrito por um CLI ANTERIOR a esta está velho de verdade; escrito por qualquer versão a
+ * partir daqui, tem exatamente os mesmos bytes que o `upgrade` de hoje escreveria.
+ *
+ * CONJUNTO COMPLETO, e a primeira tentativa errou por incompleta: `add.ts` chama `claude-md.ts`,
+ * `fonts.ts`, `rule-filter.ts` e `stack.ts`, e o `upgrade.ts` escreve o `UPGRADE.md` por conta
+ * própria. Deixar qualquer um de fora produz FALSO NEGATIVO - a marca fica parada enquanto o
+ * conteúdo anda, e o alarme cala no dia em que ele é verdade. Foi exatamente o que quase aconteceu:
+ * o `claude-md.ts` mudou em 0.16.204 e o conjunto de quatro arquivos não via.
+ *
+ * O resto da pasta vem do servidor e já é coberto pela versão do DS.
+ */
+export const MATERIALISER_SINCE = "0.16.204";
+/**
+ * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
+ *
+ * O hook fica pinado, então ele só anda quando alguém roda `upgrade`. Isso é de propósito - mas só
+ * vale a pena dizer quando o checador de hoje veria algo que o pinado não vê.
+ *
+ * Os arquivos que decidem: `doctor/` inteiro e `commands/hook.ts`.
+ */
+export const CHECKER_SINCE = "0.16.202";
+/**
+ * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
+ *
+ * A terceira do mesmo bolo, e a que tinha o desenho MAIS antigo e mais errado. O `READER` era um
+ * inteiro carimbado no censo na hora da medição, e a comparação era `carimbo !== READER`. O defeito
+ * disso não é ruído, é PERDA DE INFORMAÇÃO: com o número parado em 1 desde 07/08, um censo medido
+ * ontem e um medido em julho carregam o mesmo `1` e nada os separa. Subir o número para 2 chamaria
+ * os dois para re-medir - inclusive quem já está em dia.
+ *
+ * Uma versão não perde nada, porque o censo já grava QUEM mediu (`StyleLedger.cli`).
+ *
+ * MEDIDO EM 11/08, rodando o leitor de 07/08 e o de hoje sobre os mesmos 35 componentes do repo
+ * real, e comparando o censo canônico:
+ *
+ *     12 de 36  componentes com ÁRVORE diferente - 10 lendo mais (LineChart +556 bytes)
+ *      8 de 36  com FRONTEIRA diferente - Tooltip, Menu, Modal, Select, ColorPicker, ...
+ *      2        custom properties que eram descartadas: --loader-color, --color-track
+ *
+ * Ou seja, o `READER` estava errado e ninguém tinha sido avisado. A marca nasceu em `0.16.202`,
+ * bisseccionada: o censo de 0.16.201 difere do de então, o de 0.16.202 é byte a byte igual.
+ *
+ * ANDOU PARA `0.16.207` no mesmo dia, e desta vez o portão é que mandou. `fragmentsOfSource` parou
+ * de tomar operando de `===` e texto de comentário por classe - 11 das 26 declarações que o censo
+ * dele listava como ilegíveis eram acusação NOSSA. Um censo medido antes disto carrega as onze.
+ */
+export const READER_SINCE = "0.16.207";

package/dist/reader-version.js

@@ -20,5 +20,21 @@
  *     READER          a medição na máquina dela   ->  npx synthesisui sync
  *     COMPILER        o CSS de uma versão já instalada  ->  npx synthesisui connect
  *     INTERPRETATION  a nossa metade, sobre censos já guardados  ->  roda no servidor, sem comando
+ *
+ * A DECISÃO SAIU DAQUI EM 11/08, e este número virou só um carimbo.
+ *
+ * O desenho acima está certo na intenção e errado no formato: um inteiro gravado no censo NO
+ * MOMENTO DA MEDIÇÃO só separa duas medições se ele tiver subido entre elas. Ele não subiu - ficou
+ * em 1 desde 07/08 - enquanto os leitores andavam. Medido rodando o leitor daquele dia e o de hoje
+ * sobre os mesmos 35 componentes do repo real: 12 de 36 componentes com ÁRVORE diferente, 8 com
+ * FRONTEIRA diferente, e 2 custom properties que eram descartadas. Todos esses censos carregam `1`,
+ * e a informação para separá-los não existe mais.
+ *
+ * Subir para 2 agora chamaria para re-medir também quem já está em dia. Então quem responde
+ * *"este censo está velho?"* passou a ser `READER_SINCE`, em `install-marks.ts`, comparado contra a
+ * VERSÃO que mediu (`StyleLedger.cli`) - que o censo sempre gravou e nunca se perde.
+ *
+ * O carimbo continua sendo escrito porque ele é barato e é registro; ele só não decide mais nada.
+ * Sobe para 2 aqui por honestidade com o que foi medido.
  */
-export const READER = 1;
+export const READER = 2;

package/package.json

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