tokvista 1.6.1 → 1.7.1

package/README.md

@@ -109,6 +109,16 @@ npx tokvista export tokens.json --format tailwind --output tailwind.config.js
 npx tokvista export tokens.json --format css
 ```
 
+### Validate Tokens
+
+```bash
+# Check for errors
+npx tokvista validate tokens.json
+
+# Use in CI/CD (exits with code 1 on errors)
+npm run validate-tokens
+```
+
 ### Interactive Setup
 
 ```bash
@@ -138,6 +148,7 @@ Then run `npx tokvista` to use your config.
 | `tokvista [file]` | Token file path (default: `./tokens.json`) |
 | `tokvista init` | Interactive config setup |
 | `tokvista export <file> --format <type>` | Export tokens (css, scss, json, tailwind) |
+| `tokvista validate <file>` | Validate token structure and values |
 | `--config`, `-c` | Config file path |
 | `--port`, `-p` | Server port (default: `3000`) |
 | `--format` | Export format (export only) |

package/dist/bin/tokvista.js

@@ -813,6 +813,128 @@ Sec-WebSocket-Accept: ${accept}\r
   }
 };
 
+// src/bin/validator.ts
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTokenLike2(obj) {
+  return isRecord4(obj) && "value" in obj;
+}
+function isValidColor(value) {
+  return /^#([0-9A-F]{3}|[0-9A-F]{6}|[0-9A-F]{8})$/i.test(value) || /^rgb\(/.test(value) || /^rgba\(/.test(value) || /^hsl\(/.test(value) || /^hsla\(/.test(value) || value === "transparent" || value === "currentColor";
+}
+function isValidDimension(value) {
+  return /^\d+(\.\d+)?(px|rem|em|%|vh|vw)$/.test(value) || value === "0";
+}
+function buildTokenMap(tokens) {
+  const tokenPaths = /* @__PURE__ */ new Set();
+  function walk(node, path2 = []) {
+    if (!isRecord4(node)) return;
+    if (path2.length === 0 && Object.keys(node).some((k) => k.includes("/"))) {
+      Object.values(node).forEach((val) => walk(val, []));
+      return;
+    }
+    if (isTokenLike2(node)) {
+      tokenPaths.add(path2.join("."));
+      return;
+    }
+    Object.entries(node).forEach(([key, val]) => {
+      walk(val, [...path2, key]);
+    });
+  }
+  walk(tokens);
+  return tokenPaths;
+}
+function validateTokens(tokens) {
+  const errors = [];
+  const warnings = [];
+  let totalTokens = 0;
+  const allAliases = [];
+  if (!isRecord4(tokens)) {
+    return {
+      valid: false,
+      errors: [{ type: "error", path: "root", message: "Token file must be a JSON object" }],
+      warnings: [],
+      totalTokens: 0
+    };
+  }
+  const detection = detectTokenFormat(tokens);
+  let normalizedTokens = tokens;
+  if (detection.format !== "token-studio" && detection.format !== "unknown") {
+    normalizedTokens = normalizeTokenFormat(tokens, detection.format);
+  }
+  function walk(node, path2 = []) {
+    if (!isRecord4(node)) return;
+    if (path2.length === 0 && Object.keys(node).some((k) => k.includes("/"))) {
+      Object.values(node).forEach((val) => walk(val, []));
+      return;
+    }
+    if (isTokenLike2(node)) {
+      totalTokens++;
+      const tokenPath = path2.join(".");
+      if (!node.type) {
+        warnings.push({
+          type: "warning",
+          path: tokenPath,
+          message: "Missing type field"
+        });
+      }
+      if (node.value === null || node.value === void 0) {
+        errors.push({
+          type: "error",
+          path: tokenPath,
+          message: "Token value is null or undefined"
+        });
+        return;
+      }
+      const value = String(node.value);
+      if (value.match(/^\{(.+)\}$/)) {
+        allAliases.push({ tokenPath, reference: value });
+      }
+      if (node.type === "color" && !value.startsWith("{")) {
+        if (!isValidColor(value)) {
+          errors.push({
+            type: "error",
+            path: tokenPath,
+            message: `Invalid color value: "${value}"`
+          });
+        }
+      }
+      if (["spacing", "sizing", "borderRadius", "borderWidth"].includes(node.type || "")) {
+        if (!value.startsWith("{") && !isValidDimension(value)) {
+          errors.push({
+            type: "error",
+            path: tokenPath,
+            message: `Invalid dimension value: "${value}"`
+          });
+        }
+      }
+      return;
+    }
+    Object.entries(node).forEach(([key, val]) => {
+      walk(val, [...path2, key]);
+    });
+  }
+  walk(normalizedTokens);
+  const definedTokens = buildTokenMap(normalizedTokens);
+  allAliases.forEach(({ tokenPath, reference }) => {
+    const refPath = reference.slice(1, -1);
+    if (!definedTokens.has(refPath)) {
+      errors.push({
+        type: "error",
+        path: tokenPath,
+        message: `References missing token: ${reference}`
+      });
+    }
+  });
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    totalTokens
+  };
+}
+
 // src/bin/watcher.ts
 import { watch } from "fs";
 function watchFile(filePath, onChange) {
@@ -844,6 +966,7 @@ Usage:
   tokvista [tokens.json] [--config tokvista.config.ts] [--port 3000] [--no-open]
   tokvista init [--force] [--port 3000] [--no-open] [--no-preview]
   tokvista export <tokens.json> --format <css|scss|json|tailwind> [--output <file>]
+  tokvista validate <tokens.json>
 
 Arguments:
   tokens.json       Path to your tokens file (overrides config.tokens)
@@ -970,8 +1093,30 @@ function parseArgs(args) {
   if (args[0] === "export") {
     return parseExportArgs(args.slice(1));
   }
+  if (args[0] === "validate") {
+    return parseValidateArgs(args.slice(1));
+  }
   return parseServeArgs(args);
 }
+function parseValidateArgs(args) {
+  let tokenFileArg;
+  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 (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 validate");
+  return { command: "validate", tokenFileArg };
+}
 function parseExportArgs(args) {
   let tokenFileArg;
   let format;
@@ -1645,6 +1790,41 @@ async function runExportCommand(cwd, options) {
     console.log(output);
   }
 }
+async function runValidateCommand(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 = validateTokens(tokens);
+  console.log(`
+Validating ${resolvedTokenPath}...
+`);
+  if (result.errors.length > 0) {
+    console.log("\u274C Errors:");
+    result.errors.forEach((err) => {
+      console.log(`  ${err.path}: ${err.message}`);
+    });
+    console.log("");
+  }
+  if (result.warnings.length > 0) {
+    console.log("\u26A0\uFE0F  Warnings:");
+    result.warnings.forEach((warn) => {
+      console.log(`  ${warn.path}: ${warn.message}`);
+    });
+    console.log("");
+  }
+  console.log(`Total tokens: ${result.totalTokens}`);
+  console.log(`Errors: ${result.errors.length}`);
+  console.log(`Warnings: ${result.warnings.length}`);
+  if (result.valid) {
+    console.log("\n\u2705 All tokens are valid!\n");
+    process.exit(0);
+  } else {
+    console.log("\n\u274C Validation failed\n");
+    process.exit(1);
+  }
+}
 async function main() {
   try {
     const options = parseArgs(process.argv.slice(2));
@@ -1660,6 +1840,10 @@ async function main() {
       await runExportCommand(cwd, options);
       return;
     }
+    if (options.command === "validate") {
+      await runValidateCommand(cwd, options);
+      return;
+    }
     await runServeCommand(cwd, options);
   } catch (error) {
     console.error(error.message);

package/package.json

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