tokvista 1.14.0 → 1.15.0

package/README.md

@@ -20,6 +20,7 @@ Zero configuration. Multiple formats. One command.
 
 - 🎨 **Beautiful visuals** - Colors, spacing, typography, and components
 - 📊 **Pre-ship checklist** - Analytics tab catches broken aliases, hardcoded values, and architecture issues before you publish
+- 🔥 **Token usage heatmap** - See which tokens are actually used in your codebase
 - 🔄 **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
@@ -112,12 +113,23 @@ 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
 
 # Scan specific directory
 npx tokvista scan ./src --tokens tokens.json
 
+# JSON output for usage heatmap
+npx tokvista scan ./src --tokens tokens.json --format json > usage.json
+
 # Finds:
 # - Unused tokens (safe to remove)
 # - Hardcoded colors that should use tokens
@@ -214,7 +226,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 |
 |--------|-------------|
@@ -248,9 +260,40 @@ npx tokvista build tokens.json --output-dir ./dist --skip-validation
   theme="dark"                // Optional: 'light' | 'dark' | 'system'
   brandColor="#6366f1"        // Optional: primary color
   onTokenClick={(token) => {}} // Optional: click handler
+  usageData={usageData}        // Optional: token usage from scan command
 />
 ```
 
+### Token Usage Heatmap
+
+Show which tokens are actually used in your codebase:
+
+```bash
+# Generate usage data
+npx tokvista scan ./src --tokens tokens.json --format json > usage.json
+```
+
+```tsx
+import { TokenDocumentation } from 'tokvista';
+import tokens from './tokens.json';
+import usageData from './usage.json';
+
+export default function DesignSystem() {
+  return (
+    <TokenDocumentation 
+      tokens={tokens}
+      usageData={usageData}
+    />
+  );
+}
+```
+
+The Analytics tab will show:
+- Used vs unused tokens
+- Adoption percentage
+- List of unused tokens (safe to delete)
+- Files scanned count
+
 ### Custom Fonts
 
 ```tsx

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) {
@@ -1579,6 +1658,7 @@ function parseBuildArgs(args) {
 function parseScanArgs(args) {
   let scanDir;
   let tokenFileArg;
+  let format;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "-h" || arg === "--help") {
@@ -1596,6 +1676,24 @@ function parseScanArgs(args) {
       tokenFileArg = arg.slice("--tokens=".length);
       continue;
     }
+    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}`);
     }
@@ -1605,7 +1703,7 @@ function parseScanArgs(args) {
     scanDir = arg;
   }
   if (!scanDir) throw new Error("Directory to scan or token file is required");
-  return { command: "scan", scanDir, tokenFileArg };
+  return { command: "scan", scanDir, tokenFileArg, format };
 }
 function parseExportArgs(args) {
   let tokenFileArg;
@@ -2430,11 +2528,15 @@ async function runScanCommand(cwd, options) {
       const tokenPath2 = resolvedScanPath;
       const scanDir2 = cwd;
       const tokens2 = await readTokens(tokenPath2);
+      const result2 = await scanTokenUsage(tokenPath2, scanDir2, tokens2);
+      if (options.format === "json") {
+        console.log(JSON.stringify(result2, null, 2));
+        return;
+      }
+      const usagePercent2 = (result2.usedTokens.length / result2.totalTokens * 100).toFixed(1);
       console.log(`
 Scanning ${scanDir2} for token usage...
 `);
-      const result2 = await scanTokenUsage(tokenPath2, scanDir2, tokens2);
-      const usagePercent2 = (result2.usedTokens.length / result2.totalTokens * 100).toFixed(1);
       console.log(`\u{1F4CA} Token Usage Report
 `);
       console.log(`Files scanned: ${result2.filesScanned}`);
@@ -2495,11 +2597,15 @@ Scanning ${scanDir2} for token usage...
     throw new Error(`Token file not found: ${tokenPath}`);
   }
   const tokens = await readTokens(tokenPath);
+  const result = await scanTokenUsage(tokenPath, scanDir, tokens);
+  if (options.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const usagePercent = (result.usedTokens.length / result.totalTokens * 100).toFixed(1);
   console.log(`
 Scanning ${scanDir} for token usage...
 `);
-  const result = await scanTokenUsage(tokenPath, scanDir, tokens);
-  const usagePercent = (result.usedTokens.length / result.totalTokens * 100).toFixed(1);
   console.log(`\u{1F4CA} Token Usage Report
 `);
   console.log(`Files scanned: ${result.filesScanned}`);
@@ -2584,6 +2690,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 +2701,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);
+  }
+}