synthesisui 0.16.147 → 0.16.148

package/dist/commands/doctor.js

@@ -1271,12 +1271,18 @@ export async function doctor(opts) {
     if (opts.fix) {
         const read = await readerFor(root, d.findings.filter((f) => f.token).map((f) => f.file));
         const { result, next } = planFix(d, read);
-        if (!opts.dry)
+        const writing = opts.write === true;
+        if (writing)
             await writeFix(root, next);
-        console.log(section(opts.dry ? "What --fix would do" : "Fixed what had an answer"));
-        for (const line of describeFix(result, opts.dry === true))
+        console.log(section(writing ? "Fixed what had an answer" : "What --fix would do"));
+        for (const line of describeFix(result, !writing))
             console.log(body(line));
-        if (!opts.dry && result.applied.length > 0) {
+        if (!writing && result.applied.length > 0) {
+            console.log("");
+            console.log(body("Nothing was written. When the list above is what you want:"));
+            console.log(paint.blue(snippet(["npx synthesisui@latest doctor --fix --write"])));
+        }
+        if (writing && result.applied.length > 0) {
             console.log("");
             console.log(body(paint.dim("Read the diff before committing - it is your code, and this replaced literals with the tokens your own system declares.")));
         }

package/dist/doctor/apply-fix.js

@@ -65,6 +65,23 @@ export function planFix(d, read) {
             });
             continue;
         }
+        /**
+         * COINCIDÊNCIA NÃO SE APLICA - ver `crossFamily` em `scan.ts`.
+         *
+         * Um `2rem` que só existe como token de tipografia é uma resposta para um `font-size` e um erro
+         * de categoria para um `border-radius`. O `--fix` trocou `rounded-[2rem]` por
+         * `var(--ds-typography-scale-h1-font-size)` no repo do dono (05/08) - um canto que se move no dia
+         * em que alguém edita a escala de tipo. Medido lá: 14 de 129, e 0 de 76 na biblioteca dele.
+         */
+        if (f.crossFamily) {
+            skipped.push({
+                file: f.file,
+                line: f.line,
+                literal: f.literal,
+                because: "cross-family",
+            });
+            continue;
+        }
         if (!lines.has(f.file)) {
             const raw = read(f.file);
             if (raw === null) {
@@ -134,6 +151,7 @@ export async function readerFor(root, files) {
 export function describeFix(result, dry) {
     const { applied, skipped } = result;
     const moved = skipped.filter((s) => s.because === "moved").length;
+    const coincidence = skipped.filter((s) => s.because === "cross-family").length;
     const unread = skipped.filter((s) => s.because === "unreadable").length;
     const decisions = skipped.filter((s) => s.because === "no-token").length;
     const lines = [];
@@ -153,6 +171,8 @@ export function describeFix(result, dry) {
         lines.push(`  var(${token}) · ${n} time${n === 1 ? "" : "s"}`);
     if (moved > 0)
         lines.push(`${moved} line${moved === 1 ? "" : "s"} changed since the scan and ${moved === 1 ? "was" : "were"} left alone - run it again.`);
+    if (coincidence > 0)
+        lines.push(`${coincidence} left alone because the only token with that value belongs to another family - a length that happens to equal a font size is a coincidence, not an answer.`);
     if (unread > 0)
         lines.push(`${unread} file${unread === 1 ? "" : "s"} could not be read.`);
     if (decisions > 0)

package/dist/doctor/scan.js

@@ -9,7 +9,7 @@
  * Text in, findings out. No filesystem, no AST, no network - a diagnosis that
  * takes eight seconds and needs a build step is a diagnosis nobody runs.
  */
-import { tokenFor } from "./tokens.js";
+import { tokenMatch } from "./tokens.js";
 /**
  * `next/og` renders JSX to a PNG on the server. There is no document, so there
  * is no `var(--ds-*)` to read: every colour in such a file MUST be a literal.
@@ -335,13 +335,22 @@ function scanCore(file, source, table) {
             if (seen.has(key))
                 return;
             seen.add(key);
+            // The kind is already known here, and without passing it the lookup
+            // answers a `gap` with a radius token.
+            const match = tokenMatch(table, literal, kind);
             findings.push({
                 kind,
                 line: at,
                 literal,
-                // The kind is already known here, and without passing it the lookup
-                // answers a `gap` with a radius token.
-                token: tokenFor(table, literal, kind),
+                token: match?.token ?? null,
+                /**
+                 * A COINCIDÊNCIA VIAJA COM O ACHADO - ver `tokenMatch`.
+                 *
+                 * Sem esta marca, quem só tem `token: string` não consegue distinguir "o seu sistema nomeia
+                 * este raio" de "existe um token de TIPOGRAFIA com o mesmo 2rem". A primeira é uma troca de
+                 * uma linha; a segunda é um erro de categoria, e o `--fix` fez essa troca no repo do dono.
+                 */
+                ...(match && !match.family ? { crossFamily: true } : {}),
                 excerpt: clip(line),
             });
         };

package/dist/doctor/tokens.js

@@ -445,17 +445,36 @@ const FAMILY = {
     font: "--ds-typography-",
     motion: "--ds-motion-",
 };
-export function tokenFor(table, literal, kind) {
+/**
+ * O token que carrega este valor, e SE ELE É DA MESMA FAMÍLIA.
+ *
+ * A queda para o conjunto inteiro sempre existiu aqui, com um comentário admitindo que "deixa de ser
+ * recomendação". Como INFORMAÇÃO num relatório isso é honesto: um `2rem` que só existe como
+ * `--ds-typography-scale-h1-font-size` é um fato sobre o sistema deles.
+ *
+ * Como AÇÃO é um erro de categoria, e ele aconteceu: o `--fix` trocou `rounded-[2rem]` por
+ * `var(--ds-typography-scale-h1-font-size)` e `margin: 2rem` pela mesma coisa, no repo do dono
+ * (05/08). Um canto que se move no dia em que alguém edita a escala de tipo.
+ *
+ * Medido no `apps/web-dashboard` dele: 14 de 129 achados com token (11%) são coincidência entre
+ * famílias, e no `packages/ui` são 0 de 76 - então não é raro nem universal, é o tipo de coisa que
+ * só aparece num app grande.
+ *
+ * Então a função passa a dizer QUAL DOS DOIS é: quem informa usa os dois, quem escreve usa só
+ * `family`.
+ */
+export function tokenMatch(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal));
     if (!hit || hit.length === 0)
         return null;
-    // Narrow to the family first, and only fall back to the whole set when the
-    // system has no token of that kind holding this value - a fallback is still
-    // better than silence, it just stops being a recommendation.
     const prefix = kind ? FAMILY[kind] : undefined;
     const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
     const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.
     const semantic = pool.find((n) => n.includes("-semantic-"));
-    return semantic ?? pool[0];
+    return { token: semantic ?? pool[0], family: family.length > 0 };
+}
+/** O nome só, para quem já tratava um `string | null` - a forma antiga, preservada. */
+export function tokenFor(table, literal, kind) {
+    return tokenMatch(table, literal, kind)?.token ?? null;
 }

package/dist/index.js

@@ -60,8 +60,8 @@ Usage - governance (deterministic, FREE):
                                            reusing the reading you already authored, plus the local
                                            record - checks, fixes, open requests (--record-only skips
                                            the measurement, --yes skips the overwrite question)
-  synthesisui doctor --fix [--dry]          replace every hand-written value your system already
-                                           names with the token, in place
+  synthesisui doctor --fix [--write]        show every hand-written value your system already names,
+                                           and the token for it. --write applies them in place
   synthesisui status                       where this project stands: installed version, last check,
                                            the ratchet, open requests - local first, no login needed
   synthesisui ci [--write]                 the two steps that put drift in your PR - annotations on
@@ -273,7 +273,11 @@ async function main() {
                     : {}),
                 ...(flags.baseline === true ? { compareBaseline: true } : {}),
                 ...(flags.fix === true ? { fix: true } : {}),
-                ...(flags.dry === true ? { dry: true } : {}),
+                /**
+                 * `--fix` MOSTRA; `--fix --write` escreve. `--dry` continua aceito e é um no-op, porque um
+                 * script escrito hoje não pode virar uma escrita amanhã por causa de uma flag que sumiu.
+                 */
+                ...(flags.write === true ? { write: true } : {}),
                 ...(flags["write-baseline"] === true ? { writeBaseline: true } : {}),
                 cli: CLI_VERSION,
             });

package/dist/skill-init.js

@@ -84,26 +84,39 @@ Then wire it, once, with the command that is already idempotent:
 npx synthesisui@latest connect
 \`\`\`
 
-## 2. AUTHORISATION - ONE QUESTION, THREE BOXES
+## 2. AUTHORISATION - ONE QUESTION, AND IT IS A SINGLE CHOICE
 
 Ask it HERE, before the import, because it is the only way the end can be four lines instead of a
 negotiation.
 
-\`\`\`
-After I import, may I apply the deterministic fixes? Nothing here is AI - it is arithmetic,
-and your untouched version stays frozen either way.
+**ASK IT AS A SINGLE CHOICE, NEVER A MULTI-SELECT.** The first real run of this skill made the reason
+obvious (dono, 05/08): a multi-select renders as three checkboxes plus a fourth, \`[ ] Type something\`,
+that the question tool always appends - and free text next to three closed deterministic transforms
+has nothing to act on. Whatever somebody types there matches no transform that exists, so the option
+is either ignored or it lies. Three named options and the escape stays meaningful.
 
-  [x] tokens & contrast   values that repeat become one named token; text that fails
-                          contrast gets its INK changed, never its background
-  [x] spacing             lengths off your own scale converge onto the step you named
-  [x] typography          sizes and weights land on your own scale
+\`\`\`
+May I apply the deterministic fixes after importing? Nothing here is AI - it is arithmetic,
+and the version you have now stays frozen either way.
+
+  All three (recommended)
+      tokens & contrast - values that repeat become one named token, and text that fails
+      contrast gets its INK changed, never its background
+      spacing - lengths off your own scale converge onto the step you named
+      typography - sizes and weights land on your own scale
+  Let me pick
+      then, and only then, ask which ones - there the multi-select is the right shape,
+      because picking IS the question
+  None
+      the system arrives exactly as your code has it, and the fixes wait on a button
 \`\`\`
 
-All three checked by default. Two things must be said in the same breath, because a default that
-edits is only defensible with both:
+Two things must be said in the same breath with the recommendation, because a default that edits is
+only defensible with both:
 
-- **v1 is frozen before anything is applied.** It is a published version, it never moves, and
-  restoring it is one click.
+- **The version they have now is frozen before anything is applied.** It becomes a published version,
+  it never moves, and restoring it is one click. Say the NUMBER the route answers with, never "v1":
+  a system publishes its baseline at birth, so an import writes into v2 and the freeze produces v3.
 - **Value, never form.** Your axes, options, parts and layers are declarations - we do not touch
   them. \`archetypeFidelity\` is excluded from this run on purpose: its fix once deleted the \`variant\`
   and \`size\` a real \`Input\` declared (dono, 02/08).

package/package.json

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