tokvista 1.7.1 → 1.9.0

package/README.md

@@ -119,6 +119,34 @@ 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
+```
+
+### Convert Formats
+
+```bash
+# Convert to W3C DTCG format
+npx tokvista convert tokens.json --to w3c --output tokens-w3c.json
+
+# Convert to Style Dictionary
+npx tokvista convert tokens.json --to style-dictionary --output tokens-sd.json
+
+# Convert to Supernova array format
+npx tokvista convert tokens.json --to supernova --output tokens-sn.json
+
+# Print to stdout
+npx tokvista convert tokens.json --to w3c
+```
+
 ### Interactive Setup
 
 ```bash
@@ -149,6 +177,8 @@ 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 |
+| `tokvista convert <file> --to <format>` | Convert between token formats |
 | `--config`, `-c` | Config file path |
 | `--port`, `-p` | Server port (default: `3000`) |
 | `--format` | Export format (export only) |

package/dist/bin/tokvista.js

@@ -935,6 +935,159 @@ 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/converter.ts
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTokenLike4(obj) {
+  return isRecord6(obj) && "value" in obj;
+}
+function toW3C(tokens) {
+  function walk(node) {
+    if (!isRecord6(node)) return node;
+    if (Object.keys(node).some((k) => k.includes("/"))) {
+      const result2 = {};
+      Object.entries(node).forEach(([key, val]) => {
+        Object.assign(result2, walk(val));
+      });
+      return result2;
+    }
+    if (isTokenLike4(node)) {
+      return {
+        $value: node.value,
+        ...node.type ? { $type: node.type } : {}
+      };
+    }
+    const result = {};
+    Object.entries(node).forEach(([key, val]) => {
+      result[key] = walk(val);
+    });
+    return result;
+  }
+  return walk(tokens);
+}
+function toStyleDictionary(tokens) {
+  function walk(node) {
+    if (!isRecord6(node)) return node;
+    if (Object.keys(node).some((k) => k.includes("/"))) {
+      const result2 = {};
+      Object.entries(node).forEach(([key, val]) => {
+        Object.assign(result2, walk(val));
+      });
+      return result2;
+    }
+    if (isTokenLike4(node)) {
+      return node;
+    }
+    const result = {};
+    Object.entries(node).forEach(([key, val]) => {
+      result[key] = walk(val);
+    });
+    return result;
+  }
+  return walk(tokens);
+}
+function toSupernova(tokens) {
+  const result = [];
+  let idCounter = 1;
+  function walk(node, path2 = []) {
+    if (!isRecord6(node)) return;
+    if (path2.length === 0 && Object.keys(node).some((k) => k.includes("/"))) {
+      Object.values(node).forEach((val) => walk(val, []));
+      return;
+    }
+    if (isTokenLike4(node)) {
+      result.push({
+        id: String(idCounter++),
+        name: path2[path2.length - 1] || "token",
+        tokenType: node.type || "unknown",
+        value: node.value
+      });
+      return;
+    }
+    Object.entries(node).forEach(([key, val]) => {
+      walk(val, [...path2, key]);
+    });
+  }
+  walk(tokens);
+  return result;
+}
+function convertTokenFormat(tokens, targetFormat) {
+  if (targetFormat === "token-studio") {
+    return tokens;
+  }
+  switch (targetFormat) {
+    case "w3c":
+      return toW3C(tokens);
+    case "style-dictionary":
+      return toStyleDictionary(tokens);
+    case "supernova":
+      return toSupernova(tokens);
+    default:
+      throw new Error(`Unsupported target format: ${targetFormat}`);
+  }
+}
+
 // src/bin/watcher.ts
 import { watch } from "fs";
 function watchFile(filePath, onChange) {
@@ -967,6 +1120,8 @@ 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>
+  tokvista convert <tokens.json> --to <w3c|style-dictionary|supernova> [--output <file>]
 
 Arguments:
   tokens.json       Path to your tokens file (overrides config.tokens)
@@ -1096,6 +1251,12 @@ function parseArgs(args) {
   if (args[0] === "validate") {
     return parseValidateArgs(args.slice(1));
   }
+  if (args[0] === "diff") {
+    return parseDiffArgs(args.slice(1));
+  }
+  if (args[0] === "convert") {
+    return parseConvertArgs(args.slice(1));
+  }
   return parseServeArgs(args);
 }
 function parseValidateArgs(args) {
@@ -1117,6 +1278,81 @@ 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 parseConvertArgs(args) {
+  let tokenFileArg;
+  let to;
+  let output;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--to") {
+      const next = args[index + 1];
+      if (!next) throw new Error("Missing value for --to");
+      if (!["w3c", "style-dictionary", "supernova", "token-studio"].includes(next)) {
+        throw new Error("Format must be: w3c, style-dictionary, supernova, or token-studio");
+      }
+      to = next;
+      index += 1;
+      continue;
+    }
+    if (arg === "--output" || arg === "-o") {
+      const next = args[index + 1];
+      if (!next) throw new Error("Missing value for --output");
+      output = next;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--to=")) {
+      const val = arg.slice("--to=".length);
+      if (!["w3c", "style-dictionary", "supernova", "token-studio"].includes(val)) {
+        throw new Error("Format must be: w3c, style-dictionary, supernova, or token-studio");
+      }
+      to = val;
+      continue;
+    }
+    if (arg.startsWith("--output=")) {
+      output = arg.slice("--output=".length);
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (tokenFileArg) {
+      throw new Error(`Only one token file is supported. Unexpected value: "${arg}"`);
+    }
+    tokenFileArg = arg;
+  }
+  if (!tokenFileArg) throw new Error("Token file is required for convert");
+  if (!to) throw new Error("--to is required (w3c, style-dictionary, supernova, or token-studio)");
+  return { command: "convert", tokenFileArg, to, output };
+}
 function parseExportArgs(args) {
   let tokenFileArg;
   let format;
@@ -1825,6 +2061,70 @@ 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 runConvertCommand(cwd, options) {
+  const resolvedTokenPath = path.resolve(cwd, options.tokenFileArg);
+  if (!existsSync(resolvedTokenPath)) {
+    throw new Error(`Token file not found: ${resolvedTokenPath}`);
+  }
+  const tokens = await readTokens(resolvedTokenPath);
+  const detection = detectTokenFormat(tokens);
+  let normalizedTokens = tokens;
+  if (detection.format !== "token-studio" && detection.format !== "unknown") {
+    normalizedTokens = normalizeTokenFormat(tokens, detection.format);
+  }
+  const converted = convertTokenFormat(normalizedTokens, options.to);
+  const output = JSON.stringify(converted, null, 2);
+  if (options.output) {
+    const outputPath = path.resolve(cwd, options.output);
+    await writeFile(outputPath, output, "utf8");
+    console.log(`Converted ${detection.format} \u2192 ${options.to}`);
+    console.log(`Output: ${outputPath}`);
+  } else {
+    console.log(output);
+  }
+}
 async function main() {
   try {
     const options = parseArgs(process.argv.slice(2));
@@ -1844,6 +2144,14 @@ async function main() {
       await runValidateCommand(cwd, options);
       return;
     }
+    if (options.command === "diff") {
+      await runDiffCommand(cwd, options);
+      return;
+    }
+    if (options.command === "convert") {
+      await runConvertCommand(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.9.0",
   "description": "Interactive visual documentation for design tokens.",
   "type": "module",
   "main": "./dist/index.cjs",