tokvista 1.13.0 → 1.14.1

package/README.md

@@ -19,6 +19,7 @@ Zero configuration. Multiple formats. One command.
 ## Features
 
 - 🎨 **Beautiful visuals** - Colors, spacing, typography, and components
+- 📊 **Pre-ship checklist** - Analytics tab catches broken aliases, hardcoded values, and architecture issues before you publish
 - 🔄 **Multi-format support** - Token Studio, W3C, Style Dictionary, Supernova, Figma API
 - 📋 **Smart copy** - CSS Variables, SCSS, or Tailwind with one click
 - 🔍 **Instant search** - `Cmd+K` / `Ctrl+K` to find any token
@@ -111,6 +112,14 @@ npx tokvista init --no-preview
 ### Scan & Analyze
 
 ```bash
+# Check token health (human-readable)
+npx tokvista analytics tokens.json
+
+# JSON output for CI/CD pipelines
+npx tokvista analytics tokens.json --format json
+# Exit code 1 if broken aliases found
+# Perfect for GitHub Actions, GitLab CI, etc.
+
 # Scan for token usage and issues
 npx tokvista scan tokens.json
 
@@ -213,7 +222,7 @@ npx tokvista build tokens.json --output-dir ./dist --skip-validation
 | `tokvista diff <old> <new>` | Compare two token files |
 | `tokvista export <file>` | Export tokens to various formats |
 | `tokvista convert <file>` | Convert between token formats |
-| `tokvista build <file>` | Build all formats (validate + export) |
+| `tokvista analytics <file>` | Check token health (CI/CD ready) |
 
 | Option | Description |
 |--------|-------------|

package/dist/bin/tokvista.js

@@ -1262,6 +1262,82 @@ async function scanTokenUsage(tokensPath, scanDir, tokens) {
   };
 }
 
+// src/utils/analytics.ts
+function isTokenLeaf(value) {
+  return typeof value === "object" && value !== null && "type" in value && "value" in value;
+}
+function isAlias(value) {
+  return typeof value === "string" && /^\{[^{}]+\}$/.test(value.trim());
+}
+function collectStats(obj, tokenMap, layer, path2 = [], stats) {
+  if (!obj || typeof obj !== "object") return stats;
+  if (isTokenLeaf(obj)) {
+    stats.total++;
+    stats[layer]++;
+    const type = obj.type || "unknown";
+    if (!stats.byType[type]) {
+      stats.byType[type] = { total: 0, foundation: 0, semantic: 0, components: 0 };
+    }
+    stats.byType[type].total++;
+    stats.byType[type][layer]++;
+    if (type === "unknown") {
+      const rawType = String(obj.type || "missing");
+      stats.otherTypes[rawType] = (stats.otherTypes[rawType] || 0) + 1;
+    }
+    if (isAlias(obj.value)) {
+      stats.aliases++;
+      const resolved = resolveTokenValue(obj.value, tokenMap);
+      if (resolved === obj.value) {
+        stats.brokenAliases.push({ path: path2.join("."), reference: obj.value });
+      }
+    } else {
+      stats.hardcoded++;
+      if (layer === "semantic") {
+        stats.hardcodedInSemantic++;
+        stats.hardcodedSemanticPaths.push(path2.join("."));
+      }
+      if (layer === "components") {
+        stats.hardcodedInComponents++;
+        stats.hardcodedComponentPaths.push(path2.join("."));
+      }
+    }
+    return stats;
+  }
+  if (Array.isArray(obj)) {
+    obj.forEach((item, i) => collectStats(item, tokenMap, layer, [...path2, String(i)], stats));
+  } else {
+    Object.entries(obj).forEach(
+      ([key, value]) => collectStats(value, tokenMap, layer, [...path2, key], stats)
+    );
+  }
+  return stats;
+}
+function analyzeTokens(tokens) {
+  const tokenMap = createTokenMap(tokens);
+  const foundation = extractFoundationSet(tokens);
+  const semantic = extractSemanticSet(tokens);
+  const components = extractComponentSet(tokens);
+  const result = {
+    total: 0,
+    foundation: 0,
+    semantic: 0,
+    components: 0,
+    byType: {},
+    aliases: 0,
+    hardcoded: 0,
+    brokenAliases: [],
+    hardcodedInSemantic: 0,
+    hardcodedInComponents: 0,
+    hardcodedSemanticPaths: [],
+    hardcodedComponentPaths: [],
+    otherTypes: {}
+  };
+  collectStats(foundation, tokenMap, "foundation", [], result);
+  collectStats(semantic, tokenMap, "semantic", [], result);
+  collectStats(components, tokenMap, "components", [], result);
+  return result;
+}
+
 // src/bin/watcher.ts
 import { watch } from "fs";
 function watchFile(filePath, onChange) {
@@ -1443,6 +1519,9 @@ function parseArgs(args) {
   if (args[0] === "scan") {
     return parseScanArgs(args.slice(1));
   }
+  if (args[0] === "analytics") {
+    return parseAnalyticsArgs(args.slice(1));
+  }
   return parseServeArgs(args);
 }
 function parseValidateArgs(args) {
@@ -2584,6 +2663,10 @@ async function main() {
       await runScanCommand(cwd, options);
       return;
     }
+    if (options.command === "analytics") {
+      await runAnalyticsCommand(cwd, options);
+      return;
+    }
     await runServeCommand(cwd, options);
   } catch (error) {
     console.error(error.message);
@@ -2591,3 +2674,90 @@ async function main() {
   }
 }
 void main();
+function parseAnalyticsArgs(args) {
+  let tokenFileArg;
+  let format;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--format") {
+      const next = args[index + 1];
+      if (!next) throw new Error("Missing value for --format");
+      if (!["json", "text"].includes(next)) {
+        throw new Error("Format must be: json or text");
+      }
+      format = next;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--format=")) {
+      const val = arg.slice("--format=".length);
+      if (!["json", "text"].includes(val)) {
+        throw new Error("Format must be: json or text");
+      }
+      format = val;
+      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 analytics");
+  return { command: "analytics", tokenFileArg, format };
+}
+async function runAnalyticsCommand(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 result = analyzeTokens(tokens);
+  if (options.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.brokenAliases.length > 0 ? 1 : 0);
+  }
+  console.log(`
+\u{1F4CA} Token Analytics
+`);
+  console.log(`Total: ${result.total}`);
+  console.log(`Foundation: ${result.foundation}`);
+  console.log(`Semantic: ${result.semantic}`);
+  console.log(`Components: ${result.components}
+`);
+  console.log(`Aliases: ${result.aliases}`);
+  console.log(`Hardcoded: ${result.hardcoded}
+`);
+  if (result.brokenAliases.length > 0) {
+    console.log(`\u274C Broken Aliases (${result.brokenAliases.length}):`);
+    result.brokenAliases.slice(0, 10).forEach(({ path: path2, reference }) => {
+      console.log(`  ${path2} \u2192 ${reference}`);
+    });
+    if (result.brokenAliases.length > 10) {
+      console.log(`  ... and ${result.brokenAliases.length - 10} more`);
+    }
+    console.log("");
+  }
+  if (result.hardcodedInSemantic > 0) {
+    console.log(`\u26A0\uFE0F  ${result.hardcodedInSemantic} hardcoded values in Semantic layer`);
+  }
+  if (result.hardcodedInComponents > 0) {
+    console.log(`\u26A0\uFE0F  ${result.hardcodedInComponents} hardcoded values in Components layer`);
+  }
+  if (result.hardcodedInSemantic > 0 || result.hardcodedInComponents > 0) {
+    console.log("");
+  }
+  if (result.brokenAliases.length > 0) {
+    console.log("\u274C Quality check failed\n");
+    process.exit(1);
+  } else {
+    console.log("\u2705 All checks passed\n");
+    process.exit(0);
+  }
+}