synthesisui 0.4.4 → 0.4.5

package/dist/commands/upgrade.js

@@ -2,6 +2,7 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
+import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
 import { body, section, snippet } from "../output.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { add } from "./add.js";
@@ -85,11 +86,29 @@ export async function upgrade(slug, opts) {
             }
         }
     }
-    // 3. deterministic changelog → UPGRADE.md (the agent's migration brief)
-    const log = await fetchChangelog(base, slug, installed, latest.version);
+    // 3. deterministic changelog → UPGRADE.md (the agent's migration brief).
+    //    Diffed against the LOCALLY installed snapshot: personal systems mutate
+    //    their working draft in place under a version number, so the server's
+    //    vN may have moved since this app installed it ("draft drift") - a
+    //    server-side history diff can be empty while this app's files differ.
+    //    Fallback to the server changelog if the local snapshot is unreadable.
+    let markdown;
+    let breaking;
+    try {
+        const beforeDoc = JSON.parse(await readFile(join(slugDir, `v${installed}`, "design-system.json"), "utf8"));
+        const afterDoc = JSON.parse(await readFile(join(slugDir, `v${latest.version}`, "design-system.json"), "utf8"));
+        const local = diffLocalDocuments(beforeDoc, afterDoc);
+        markdown = localChangelogMarkdown(slug, installed, latest.version, local);
+        breaking = local.breaking;
+    }
+    catch {
+        const log = await fetchChangelog(base, slug, installed, latest.version);
+        markdown = log.markdown;
+        breaking = log.changelog.breaking;
+    }
     const upgradePath = join(slugDir, "UPGRADE.md");
     const brief = [
-        log.markdown,
+        markdown,
         "",
         "---",
         "",
@@ -110,10 +129,10 @@ export async function upgrade(slug, opts) {
     await writeFile(upgradePath, brief, "utf8");
     // ── report ──
     console.log(section(`Upgraded ${slug}: v${installed} → v${latest.version}`));
-    if (log.changelog.breaking.length > 0) {
-        console.log(body(`Breaking changes (${log.changelog.breaking.length}):`));
+    if (breaking.length > 0) {
+        console.log(body(`Breaking changes (${breaking.length}):`));
         console.log("");
-        console.log(snippet(log.changelog.breaking.map((item) => `- ${item}`)));
+        console.log(snippet(breaking.map((item) => `- ${item}`)));
     }
     else {
         console.log(body("No breaking changes detected."));

package/dist/document-diff.js

@@ -0,0 +1,174 @@
+/**
+ * LOCAL document diff for `upgrade` - computed against the design-system.json
+ * snapshots on disk, not against the server's version history.
+ *
+ * Why local: personal design systems mutate their WORKING DRAFT in place under
+ * a fixed version number; only publishing freezes it. So the server's "v3" may
+ * have moved since this app installed it ("draft drift"), and a server-side
+ * v3→v4 changelog can be legitimately empty while the app's files differ. The
+ * app's truth is what it has installed - so that's what we diff.
+ */
+/** Flatten a token subtree into `prefix.path → value` leaves. */
+function flattenTokens(prefix, value, out) {
+    if (value == null)
+        return;
+    if (typeof value === "string" || typeof value === "number") {
+        out.set(prefix, String(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => flattenTokens(`${prefix}.${i}`, v, out));
+        return;
+    }
+    if (typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            flattenTokens(prefix ? `${prefix}.${k}` : k, v, out);
+        }
+    }
+}
+/** Key-order-insensitive equality (JSON docs round-trip with unstable order). */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (a && b && typeof a === "object") {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        if (ka.length !== kb.length)
+            return false;
+        return ka.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/** Variant options that existed and disappeared (breaking for the consumer). */
+function removedVariantOptions(before, after) {
+    const out = [];
+    const prevVariants = (before.variants ?? {});
+    const nextVariants = (after.variants ?? {});
+    for (const [axis, options] of Object.entries(prevVariants)) {
+        const nextAxis = nextVariants[axis];
+        if (!nextAxis) {
+            out.push(axis);
+            continue;
+        }
+        for (const option of Object.keys(options)) {
+            if (!(option in nextAxis))
+                out.push(`${axis}="${option}"`);
+        }
+    }
+    return out;
+}
+function diffRecipeMaps(before, after, label, breaking) {
+    const out = [];
+    const names = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const name of [...names].sort()) {
+        const prev = before[name];
+        const next = after[name];
+        if (!prev) {
+            out.push({ name, kind: "added" });
+            continue;
+        }
+        if (!next) {
+            out.push({ name, kind: "removed" });
+            breaking.push(`${label} "${name}" was removed`);
+            continue;
+        }
+        if (deepEqual(prev, next))
+            continue;
+        out.push({ name, kind: "changed" });
+        for (const gone of removedVariantOptions(prev, next)) {
+            breaking.push(`${label} "${name}" no longer supports ${gone}`);
+        }
+    }
+    return out;
+}
+/** Diff two installed design-system.json documents (token + recipe level). */
+export function diffLocalDocuments(before, after) {
+    const breaking = [];
+    const prevTokens = new Map();
+    const nextTokens = new Map();
+    flattenTokens("", before.foundations, prevTokens);
+    flattenTokens("motion", before.motion, prevTokens);
+    flattenTokens("", after.foundations, nextTokens);
+    flattenTokens("motion", after.motion, nextTokens);
+    const tokens = [];
+    const paths = new Set([...prevTokens.keys(), ...nextTokens.keys()]);
+    for (const path of [...paths].sort()) {
+        const prev = prevTokens.get(path);
+        const next = nextTokens.get(path);
+        if (prev === next)
+            continue;
+        if (prev === undefined)
+            tokens.push({ path, after: next, kind: "added" });
+        else if (next === undefined) {
+            tokens.push({ path, before: prev, kind: "removed" });
+            breaking.push(`token "${path}" was removed`);
+        }
+        else
+            tokens.push({ path, before: prev, after: next, kind: "changed" });
+    }
+    const components = diffRecipeMaps((before.components ?? {}), (after.components ?? {}), "component", breaking);
+    const blocks = diffRecipeMaps((before.blocks ?? {}), (after.blocks ?? {}), "block", breaking);
+    return {
+        tokens,
+        components,
+        blocks,
+        breaking,
+        isEmpty: tokens.length === 0 && components.length === 0 && blocks.length === 0,
+    };
+}
+const CAP_TOKENS = 40;
+/** The migration brief body, mirroring the server changelog's format. */
+export function localChangelogMarkdown(slug, from, to, log) {
+    const lines = [
+        `# ${slug} - v${from} → v${to}`,
+        "",
+        `_Diffed against this app's installed v${from} snapshot (the app's truth) -`,
+        "personal systems can evolve in place under a version, so a server-side",
+        "history diff may miss what changed HERE._",
+        "",
+    ];
+    if (log.isEmpty) {
+        lines.push("No visual-contract changes for this app.", "");
+        return lines.join("\n");
+    }
+    if (log.breaking.length > 0) {
+        lines.push("## Breaking", "");
+        for (const item of log.breaking)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    if (log.tokens.length > 0) {
+        lines.push(`## Tokens (${log.tokens.length} change(s))`, "");
+        for (const t of log.tokens.slice(0, CAP_TOKENS)) {
+            const val = t.kind === "removed"
+                ? `removed (was \`${t.before}\`)`
+                : t.kind === "added"
+                    ? `added: \`${t.after}\``
+                    : `\`${t.before}\` → \`${t.after}\``;
+            lines.push(`- ${t.path}: ${val}`);
+        }
+        if (log.tokens.length > CAP_TOKENS) {
+            lines.push(`- …and ${log.tokens.length - CAP_TOKENS} more`);
+        }
+        lines.push("");
+    }
+    for (const [title, entries] of [
+        ["Components", log.components],
+        ["Blocks", log.blocks],
+    ]) {
+        if (entries.length === 0)
+            continue;
+        lines.push(`## ${title}`, "");
+        for (const entry of entries)
+            lines.push(`- \`ds-${entry.name}\` - ${entry.kind}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
   "type": "module",
   "bin": {