tokvista 1.7.1 → 1.8.0

package/README.md

@@ -119,6 +119,18 @@ npx tokvista validate tokens.json
 npm run validate-tokens
 ```
 
+### Compare Tokens
+
+```bash
+# Compare two token files
+npx tokvista diff tokens-v1.json tokens-v2.json
+
+# Perfect for:
+# - Version control reviews
+# - Release changelogs  
+# - Migration tracking
+```
+
 ### Interactive Setup
 
 ```bash
@@ -149,6 +161,7 @@ Then run `npx tokvista` to use your config.
 | `tokvista init` | Interactive config setup |
 | `tokvista export <file> --format <type>` | Export tokens (css, scss, json, tailwind) |
 | `tokvista validate <file>` | Validate token structure and values |
+| `tokvista diff <old> <new>` | Compare two token files |
 | `--config`, `-c` | Config file path |
 | `--port`, `-p` | Server port (default: `3000`) |
 | `--format` | Export format (export only) |

package/dist/bin/tokvista.js

@@ -935,6 +935,66 @@ function validateTokens(tokens) {
   };
 }
 
+// src/bin/differ.ts
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTokenLike3(obj) {
+  return isRecord5(obj) && "value" in obj;
+}
+function flattenTokens(tokens) {
+  const flat = /* @__PURE__ */ new Map();
+  function walk(node, path2 = []) {
+    if (!isRecord5(node)) return;
+    if (path2.length === 0 && Object.keys(node).some((k) => k.includes("/"))) {
+      Object.values(node).forEach((val) => walk(val, []));
+      return;
+    }
+    if (isTokenLike3(node)) {
+      flat.set(path2.join("."), String(node.value));
+      return;
+    }
+    Object.entries(node).forEach(([key, val]) => {
+      walk(val, [...path2, key]);
+    });
+  }
+  walk(tokens);
+  return flat;
+}
+function diffTokens(oldTokens, newTokens) {
+  const oldDetection = detectTokenFormat(oldTokens);
+  const newDetection = detectTokenFormat(newTokens);
+  let normalizedOld = oldTokens;
+  let normalizedNew = newTokens;
+  if (oldDetection.format !== "token-studio" && oldDetection.format !== "unknown") {
+    normalizedOld = normalizeTokenFormat(oldTokens, oldDetection.format);
+  }
+  if (newDetection.format !== "token-studio" && newDetection.format !== "unknown") {
+    normalizedNew = normalizeTokenFormat(newTokens, newDetection.format);
+  }
+  const oldFlat = flattenTokens(normalizedOld);
+  const newFlat = flattenTokens(normalizedNew);
+  const added = [];
+  const removed = [];
+  const modified = [];
+  let unchanged = 0;
+  newFlat.forEach((newValue, path2) => {
+    if (!oldFlat.has(path2)) {
+      added.push(path2);
+    } else if (oldFlat.get(path2) !== newValue) {
+      modified.push({ path: path2, oldValue: oldFlat.get(path2), newValue });
+    } else {
+      unchanged++;
+    }
+  });
+  oldFlat.forEach((_, path2) => {
+    if (!newFlat.has(path2)) {
+      removed.push(path2);
+    }
+  });
+  return { added, removed, modified, unchanged };
+}
+
 // src/bin/watcher.ts
 import { watch } from "fs";
 function watchFile(filePath, onChange) {
@@ -967,6 +1027,7 @@ Usage:
   tokvista init [--force] [--port 3000] [--no-open] [--no-preview]
   tokvista export <tokens.json> --format <css|scss|json|tailwind> [--output <file>]
   tokvista validate <tokens.json>
+  tokvista diff <old.json> <new.json>
 
 Arguments:
   tokens.json       Path to your tokens file (overrides config.tokens)
@@ -1096,6 +1157,9 @@ function parseArgs(args) {
   if (args[0] === "validate") {
     return parseValidateArgs(args.slice(1));
   }
+  if (args[0] === "diff") {
+    return parseDiffArgs(args.slice(1));
+  }
   return parseServeArgs(args);
 }
 function parseValidateArgs(args) {
@@ -1117,6 +1181,30 @@ function parseValidateArgs(args) {
   if (!tokenFileArg) throw new Error("Token file is required for validate");
   return { command: "validate", tokenFileArg };
 }
+function parseDiffArgs(args) {
+  let oldFileArg;
+  let newFileArg;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (!oldFileArg) {
+      oldFileArg = arg;
+    } else if (!newFileArg) {
+      newFileArg = arg;
+    } else {
+      throw new Error(`Too many arguments. Expected: tokvista diff <old.json> <new.json>`);
+    }
+  }
+  if (!oldFileArg) throw new Error("Old token file is required");
+  if (!newFileArg) throw new Error("New token file is required");
+  return { command: "diff", oldFileArg, newFileArg };
+}
 function parseExportArgs(args) {
   let tokenFileArg;
   let format;
@@ -1825,6 +1913,48 @@ Validating ${resolvedTokenPath}...
     process.exit(1);
   }
 }
+async function runDiffCommand(cwd, options) {
+  const oldPath = path.resolve(cwd, options.oldFileArg);
+  const newPath = path.resolve(cwd, options.newFileArg);
+  if (!existsSync(oldPath)) {
+    throw new Error(`Old token file not found: ${oldPath}`);
+  }
+  if (!existsSync(newPath)) {
+    throw new Error(`New token file not found: ${newPath}`);
+  }
+  const [oldTokens, newTokens] = await Promise.all([
+    readTokens(oldPath),
+    readTokens(newPath)
+  ]);
+  const diff = diffTokens(oldTokens, newTokens);
+  console.log(`
+Comparing tokens:
+  Old: ${oldPath}
+  New: ${newPath}
+`);
+  if (diff.added.length > 0) {
+    console.log(`\u2705 Added (${diff.added.length}):`);
+    diff.added.forEach((path2) => console.log(`  + ${path2}`));
+    console.log("");
+  }
+  if (diff.removed.length > 0) {
+    console.log(`\u274C Removed (${diff.removed.length}):`);
+    diff.removed.forEach((path2) => console.log(`  - ${path2}`));
+    console.log("");
+  }
+  if (diff.modified.length > 0) {
+    console.log(`\u{1F504} Modified (${diff.modified.length}):`);
+    diff.modified.forEach(({ path: path2, oldValue, newValue }) => {
+      console.log(`  ~ ${path2}`);
+      console.log(`    - ${oldValue}`);
+      console.log(`    + ${newValue}`);
+    });
+    console.log("");
+  }
+  console.log(`Unchanged: ${diff.unchanged}`);
+  console.log(`Total changes: ${diff.added.length + diff.removed.length + diff.modified.length}
+`);
+}
 async function main() {
   try {
     const options = parseArgs(process.argv.slice(2));
@@ -1844,6 +1974,10 @@ async function main() {
       await runValidateCommand(cwd, options);
       return;
     }
+    if (options.command === "diff") {
+      await runDiffCommand(cwd, options);
+      return;
+    }
     await runServeCommand(cwd, options);
   } catch (error) {
     console.error(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokvista",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Interactive visual documentation for design tokens.",
   "type": "module",
   "main": "./dist/index.cjs",