tokka 0.2.1 → 0.2.2

package/compiler/resolver.ts

@@ -0,0 +1,177 @@
+import { type Token, type ResolvedToken, type CompilationError } from "./types.js"
+
+/**
+ * Build a dependency graph from token references
+ */
+export function buildDependencyGraph(tokens: Token[]): Map<string, Set<string>> {
+  const graph = new Map<string, Set<string>>()
+
+  // Initialize nodes
+  for (const token of tokens) {
+    graph.set(token.id, new Set())
+  }
+
+  // Add edges
+  for (const token of tokens) {
+    if (token.references) {
+      const deps = graph.get(token.id)!
+      for (const ref of token.references) {
+        deps.add(ref)
+      }
+    }
+  }
+
+  return graph
+}
+
+/**
+ * Detect cycles in the dependency graph
+ */
+export function detectCycles(graph: Map<string, Set<string>>): string[][] {
+  const cycles: string[][] = []
+  const visited = new Set<string>()
+  const recursionStack = new Set<string>()
+
+  function dfs(node: string, path: string[]): boolean {
+    visited.add(node)
+    recursionStack.add(node)
+    path.push(node)
+
+    const neighbors = graph.get(node) || new Set()
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) {
+        if (dfs(neighbor, path)) {
+          return true
+        }
+      } else if (recursionStack.has(neighbor)) {
+        // Found a cycle
+        const cycleStart = path.indexOf(neighbor)
+        cycles.push([...path.slice(cycleStart), neighbor])
+        return true
+      }
+    }
+
+    recursionStack.delete(node)
+    path.pop()
+    return false
+  }
+
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) {
+      dfs(node, [])
+    }
+  }
+
+  return cycles
+}
+
+/**
+ * Topological sort of tokens by dependencies
+ */
+export function topologicalSort(
+  tokens: Token[],
+  graph: Map<string, Set<string>>
+): Token[] {
+  const sorted: Token[] = []
+  const visited = new Set<string>()
+  const tokenMap = new Map(tokens.map((t) => [t.id, t]))
+
+  function visit(tokenId: string) {
+    if (visited.has(tokenId)) return
+
+    visited.add(tokenId)
+    const deps = graph.get(tokenId) || new Set()
+    for (const dep of deps) {
+      visit(dep)
+    }
+
+    const token = tokenMap.get(tokenId)
+    if (token) {
+      sorted.push(token)
+    }
+  }
+
+  for (const token of tokens) {
+    visit(token.id)
+  }
+
+  return sorted
+}
+
+/**
+ * Resolve token values (alias-only in v1)
+ */
+export function resolveTokens(
+  tokens: Token[],
+  graph: Map<string, Set<string>>
+): { resolved: ResolvedToken[]; errors: CompilationError[] } {
+  const errors: CompilationError[] = []
+
+  // Check for cycles first
+  const cycles = detectCycles(graph)
+  if (cycles.length > 0) {
+    for (const cycle of cycles) {
+      errors.push({
+        type: "cycle",
+        message: `Circular reference detected: ${cycle.join(" → ")}`,
+        tokenId: cycle[0],
+      })
+    }
+    return { resolved: [], errors }
+  }
+
+  // Sort topologically
+  const sorted = topologicalSort(tokens, graph)
+  const resolvedMap = new Map<string, ResolvedToken>()
+
+  // Resolve in dependency order
+  for (const token of sorted) {
+    const resolved: ResolvedToken = { ...token }
+
+    // Resolve direct value
+    if (token.value !== undefined) {
+      resolved.resolvedValue = resolveValue(token.value, resolvedMap)
+    }
+
+    // Resolve modes
+    if (token.modes) {
+      resolved.resolvedModes = {}
+      for (const [mode, value] of Object.entries(token.modes)) {
+        resolved.resolvedModes[mode] = resolveValue(value, resolvedMap)
+      }
+    }
+
+    resolvedMap.set(token.id, resolved)
+  }
+
+  return { resolved: Array.from(resolvedMap.values()), errors }
+}
+
+/**
+ * Resolve a single value (supports alias references)
+ */
+function resolveValue(
+  value: any,
+  resolvedMap: Map<string, ResolvedToken>
+): string {
+  if (typeof value !== "string") {
+    return String(value)
+  }
+
+  // Check if it's a reference to another token
+  // References start with a token ID (no special syntax needed in v1)
+  // If value starts with "var(--", it's a CSS var reference
+  if (value.startsWith("var(--")) {
+    // Extract token ID from CSS var
+    const match = value.match(/var\(--([a-z][a-z0-9-]*)\)/)
+    if (match) {
+      const tokenId = match[1].replace(/-/g, ".")
+      const refToken = resolvedMap.get(tokenId)
+      if (refToken?.resolvedValue) {
+        return refToken.resolvedValue
+      }
+    }
+  }
+
+  return value
+}

package/compiler/types.ts

@@ -0,0 +1,118 @@
+import { z } from "zod"
+
+// Token type
+export const tokenTypeSchema = z.enum([
+  "color",
+  "number",
+  "dimension",
+  "radius",
+  "shadow",
+  "typography",
+  "motion",
+  "opacity",
+  "zIndex",
+])
+
+export const tokenSourceSchema = z.enum(["primitive", "semantic", "component"])
+
+export const tokenSchema = z
+  .object({
+    id: z
+      .string()
+      .regex(
+        /^[a-z][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/,
+        "Token ID must be lowercase, dot-separated"
+      ),
+    type: tokenTypeSchema,
+    description: z.string(),
+    source: tokenSourceSchema,
+    value: z.any().optional(),
+    modes: z.record(z.string(), z.any()).optional(),
+    references: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+    deprecated: z.boolean().optional(),
+    replacedBy: z.string().optional(),
+    figma: z
+      .object({
+        collection: z.string().optional(),
+        scopes: z.array(z.string()).optional(),
+        variableName: z.string().optional(),
+      })
+      .optional(),
+  })
+  .refine((data) => data.value !== undefined || data.modes !== undefined, {
+    message: "Token must have either value or modes",
+  })
+
+export type Token = z.infer<typeof tokenSchema>
+export type TokenType = z.infer<typeof tokenTypeSchema>
+export type TokenSource = z.infer<typeof tokenSourceSchema>
+
+// Token file structure
+export const tokenFileSchema = z.object({
+  tokens: z.array(tokenSchema),
+})
+
+export type TokenFile = z.infer<typeof tokenFileSchema>
+
+// System metadata
+export const systemSchema = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/, "System ID must be lowercase kebab-case"),
+  name: z.string(),
+  description: z.string(),
+  tags: z.array(z.string()).optional(),
+  modes: z.array(z.string()).min(1),
+  policies: z
+    .object({
+      radius: z.enum(["sharp", "rounded", "pill"]).optional(),
+      density: z.enum(["compact", "comfortable", "spacious"]).optional(),
+      contrast: z.enum(["low", "medium", "high"]).optional(),
+      motion: z.enum(["none", "subtle", "expressive"]).optional(),
+    })
+    .optional(),
+  defaults: z
+    .object({
+      font: z.string().optional(),
+      iconStyle: z.string().optional(),
+    })
+    .optional(),
+  figma: z
+    .object({
+      collections: z.array(z.string()).optional(),
+    })
+    .optional(),
+})
+
+export type System = z.infer<typeof systemSchema>
+
+// Resolved token (after compilation)
+export interface ResolvedToken extends Token {
+  resolvedValue?: string
+  resolvedModes?: Record<string, string>
+}
+
+// Compilation context
+export interface CompilationContext {
+  tokens: Token[]
+  system: System
+  mode: "tier0" | "tier1" | "tier2"
+}
+
+// Compilation result
+export interface CompilationResult {
+  tokens: ResolvedToken[]
+  errors: CompilationError[]
+  warnings: CompilationWarning[]
+}
+
+export interface CompilationError {
+  type: "schema" | "reference" | "cycle" | "naming" | "layering"
+  message: string
+  tokenId?: string
+}
+
+export interface CompilationWarning {
+  type: "unused" | "deprecated" | "missing-mode"
+  message: string
+  tokenId?: string
+}

package/compiler/validator.ts

@@ -0,0 +1,194 @@
+import { type Token, type CompilationError } from "./types.js"
+
+// Semantic token category prefixes
+const SEMANTIC_PREFIXES = [
+  "surface.",
+  "text.",
+  "border.",
+  "icon.",
+  "shadow.",
+  "focus.",
+  "overlay.",
+  "motion.",
+  "space.",
+  "radius.",
+  "typography.",
+]
+
+/**
+ * Validate token naming conventions
+ */
+export function validateTokenNaming(tokens: Token[]): CompilationError[] {
+  const errors: CompilationError[] = []
+
+  for (const token of tokens) {
+    // Validate semantic token prefixes
+    if (token.source === "semantic") {
+      const hasValidPrefix = SEMANTIC_PREFIXES.some((prefix) =>
+        token.id.startsWith(prefix)
+      )
+      if (!hasValidPrefix) {
+        errors.push({
+          type: "naming",
+          message: `Semantic token "${token.id}" must start with one of: ${SEMANTIC_PREFIXES.join(", ")}`,
+          tokenId: token.id,
+        })
+      }
+    }
+
+    // Validate component token prefixes (must be component name + dot)
+    if (token.source === "component") {
+      const parts = token.id.split(".")
+      if (parts.length < 2) {
+        errors.push({
+          type: "naming",
+          message: `Component token "${token.id}" must follow format: <component>.<property>`,
+          tokenId: token.id,
+        })
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Validate token uniqueness
+ */
+export function validateTokenUniqueness(tokens: Token[]): CompilationError[] {
+  const errors: CompilationError[] = []
+  const seen = new Map<string, Token>()
+
+  for (const token of tokens) {
+    if (seen.has(token.id)) {
+      errors.push({
+        type: "schema",
+        message: `Duplicate token ID: "${token.id}"`,
+        tokenId: token.id,
+      })
+    }
+    seen.set(token.id, token)
+  }
+
+  return errors
+}
+
+/**
+ * Validate token references exist
+ */
+export function validateTokenReferences(tokens: Token[]): CompilationError[] {
+  const errors: CompilationError[] = []
+  const tokenIds = new Set(tokens.map((t) => t.id))
+
+  for (const token of tokens) {
+    if (token.references) {
+      for (const ref of token.references) {
+        if (!tokenIds.has(ref)) {
+          errors.push({
+            type: "reference",
+            message: `Token "${token.id}" references non-existent token "${ref}"`,
+            tokenId: token.id,
+          })
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Validate token layering rules (Tier 2 only)
+ */
+export function validateTokenLayering(
+  tokens: Token[],
+  strict: boolean = false
+): CompilationError[] {
+  if (!strict) return []
+
+  const errors: CompilationError[] = []
+  const tokenMap = new Map(tokens.map((t) => [t.id, t]))
+
+  for (const token of tokens) {
+    if (!token.references || token.references.length === 0) continue
+
+    // Primitives may not reference anything
+    if (token.source === "primitive") {
+      errors.push({
+        type: "layering",
+        message: `Primitive token "${token.id}" may not reference other tokens`,
+        tokenId: token.id,
+      })
+    }
+
+    // Semantics may reference primitives and other semantics
+    if (token.source === "semantic") {
+      for (const ref of token.references) {
+        const refToken = tokenMap.get(ref)
+        if (refToken && refToken.source === "component") {
+          errors.push({
+            type: "layering",
+            message: `Semantic token "${token.id}" may not reference component token "${ref}"`,
+            tokenId: token.id,
+          })
+        }
+      }
+    }
+
+    // Component tokens may reference semantics and primitives
+    if (token.source === "component") {
+      for (const ref of token.references) {
+        const refToken = tokenMap.get(ref)
+        if (refToken && refToken.source === "component") {
+          // Allow component-to-component references but warn
+          // (could be useful for variants)
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Validate mode coverage
+ */
+export function validateModeCoverage(
+  tokens: Token[],
+  requiredModes: string[]
+): CompilationError[] {
+  const errors: CompilationError[] = []
+
+  for (const token of tokens) {
+    if (token.modes) {
+      const tokenModes = Object.keys(token.modes)
+      const missingModes = requiredModes.filter((m) => !tokenModes.includes(m))
+      if (missingModes.length > 0) {
+        errors.push({
+          type: "schema",
+          message: `Token "${token.id}" missing required modes: ${missingModes.join(", ")}`,
+          tokenId: token.id,
+        })
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Run all validations
+ */
+export function validateTokens(
+  tokens: Token[],
+  requiredModes: string[],
+  options: { strict?: boolean } = {}
+): CompilationError[] {
+  return [
+    ...validateTokenUniqueness(tokens),
+    ...validateTokenNaming(tokens),
+    ...validateTokenReferences(tokens),
+    ...validateModeCoverage(tokens, requiredModes),
+    ...validateTokenLayering(tokens, options.strict),
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokka",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "description": "A shadcn-compatible UI foundation with a real token system and optional Figma exports",
   "bin": "./dist/index.js",
@@ -13,7 +13,8 @@
   "files": [
     "dist",
     "systems",
-    "components"
+    "components",
+    "compiler"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
@@ -22,7 +23,6 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@tokka/compiler": "workspace:*",
     "commander": "^11.1.0",
     "prompts": "^2.4.2",
     "kleur": "^4.1.5",