@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

package/src/bundler/index.ts

@@ -0,0 +1,151 @@
+/**
+ * Schema bundler - bundles schemas for distribution
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { bundleSchemaFromDirectory } from "@/bundler/bundle-schema";
+import type {
+  BundledRegistry,
+  ColorSpecification,
+  FunctionSpecification,
+  SchemaSpecification,
+} from "@/bundler/types.js";
+import { getSubdirectories } from "@/bundler/utils";
+
+/**
+ * Default registry URL for build-time bundling
+ */
+const DEFAULT_REGISTRY_URL = "https://schema.tokenscript.dev.gcp.tokens.studio";
+
+/**
+ * Bundle a single schema from its directory
+ */
+async function bundleSchema(schemaDir: string, schemaSlug: string): Promise<SchemaSpecification> {
+  // Use shared bundling logic with baseUrl for build-time
+  const bundled = await bundleSchemaFromDirectory(schemaDir, {
+    baseUrl: DEFAULT_REGISTRY_URL,
+  });
+
+  // Add slug from folder name
+  bundled.slug = schemaSlug;
+
+  return bundled;
+}
+
+/**
+ * Bundle all color type schemas from a category directory
+ */
+async function bundleTypeCategory(categoryDir: string): Promise<ColorSpecification[]> {
+  const bundles: ColorSpecification[] = [];
+  const schemaSlugs = await getSubdirectories(categoryDir);
+
+  for (const slug of schemaSlugs) {
+    const schemaDir = join(categoryDir, slug);
+    console.log(`  Bundling ${slug}...`);
+
+    try {
+      const bundle = await bundleSchema(schemaDir, slug);
+      if (bundle.type === "color") {
+        bundles.push(bundle as ColorSpecification);
+      }
+    } catch (error) {
+      console.error(`  ✗ Failed to bundle ${slug}:`, error);
+    }
+  }
+
+  return bundles;
+}
+
+/**
+ * Bundle all function schemas from a category directory
+ */
+async function bundleFunctionCategory(categoryDir: string): Promise<FunctionSpecification[]> {
+  const bundles: FunctionSpecification[] = [];
+  const schemaSlugs = await getSubdirectories(categoryDir);
+
+  for (const slug of schemaSlugs) {
+    const schemaDir = join(categoryDir, slug);
+    console.log(`  Bundling ${slug}...`);
+
+    try {
+      const bundle = await bundleSchema(schemaDir, slug);
+      if (bundle.type === "function") {
+        bundles.push(bundle as FunctionSpecification);
+      }
+    } catch (error) {
+      console.error(`  ✗ Failed to bundle ${slug}:`, error);
+    }
+  }
+
+  return bundles;
+}
+
+/**
+ * Bundle all schemas from the schemas directory
+ */
+export async function bundleAllSchemas(
+  schemasDir: string,
+  outputDir: string,
+): Promise<BundledRegistry> {
+  // Bundle types
+  console.log("\nBundling type schemas...");
+  const typesDir = join(schemasDir, "types");
+  const types = await bundleTypeCategory(typesDir);
+  console.log(`✓ Bundled ${types.length} type schemas`);
+
+  // Bundle functions
+  console.log("\nBundling function schemas...");
+  const functionsDir = join(schemasDir, "functions");
+  const functions = await bundleFunctionCategory(functionsDir);
+  console.log(`✓ Bundled ${functions.length} function schemas`);
+
+  // Create bundled registry
+  const registry: BundledRegistry = {
+    version: "0.0.10",
+    types,
+    functions,
+    metadata: {
+      generatedAt: new Date().toISOString(),
+      totalSchemas: types.length + functions.length,
+    },
+  };
+
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true });
+
+  // Write complete registry
+  const registryPath = join(outputDir, "registry.json");
+  await writeFile(registryPath, JSON.stringify(registry, null, 2));
+  console.log(`\n✓ Written complete registry to ${registryPath}`);
+
+  // Write individual category bundles
+  const typesPath = join(outputDir, "types.json");
+  await writeFile(typesPath, JSON.stringify({ version: registry.version, types }, null, 2));
+  console.log(`✓ Written types bundle to ${typesPath}`);
+
+  const functionsPath = join(outputDir, "functions.json");
+  await writeFile(functionsPath, JSON.stringify({ version: registry.version, functions }, null, 2));
+  console.log(`✓ Written functions bundle to ${functionsPath}`);
+
+  // Write individual schema bundles
+  const typesOutputDir = join(outputDir, "types");
+  await mkdir(typesOutputDir, { recursive: true });
+  for (const type of types) {
+    const typePath = join(typesOutputDir, `${type.slug}.json`);
+    await writeFile(typePath, JSON.stringify(type, null, 2));
+  }
+  console.log(`✓ Written ${types.length} individual type schemas`);
+
+  const functionsOutputDir = join(outputDir, "functions");
+  await mkdir(functionsOutputDir, { recursive: true });
+  for (const func of functions) {
+    const funcPath = join(functionsOutputDir, `${func.slug}.json`);
+    await writeFile(funcPath, JSON.stringify(func, null, 2));
+  }
+  console.log(`✓ Written ${functions.length} individual function schemas`);
+
+  return registry;
+}
+
+export type * from "@/bundler/types.js";

package/src/bundler/schema-dependency-resolver.ts

@@ -0,0 +1,299 @@
+/**
+ * Utilities for resolving schema dependencies automatically
+ */
+
+import { join } from "node:path";
+import { log } from "@tests/helpers/logger.js";
+import type {
+  ColorSpecification,
+  FunctionSpecification,
+  SchemaSpecification,
+} from "@/bundler/types.js";
+import { extractSchemaName, parseSchemaUri } from "@/utils/schema-uri";
+import { bundleSchemaFromDirectory } from "./bundle-schema.js";
+
+export interface SchemaReference {
+  slug: string;
+  type: "type" | "function";
+  uri: string;
+}
+
+export interface ExtractRequirementsOptions {
+  /**
+   * Whether to include type dependencies from color conversions
+   * Useful for testing to ensure all conversion types are loaded
+   * @default false
+   */
+  includeColorTypeDependencies?: boolean;
+}
+
+/**
+ * Extract all required schema URIs from a schema specification
+ * Only extracts explicit requirements - not conversions (which are capabilities, not dependencies)
+ * However, for testing purposes, can optionally include color type dependencies from conversions
+ */
+function extractRequirements(
+  spec: SchemaSpecification,
+  options: ExtractRequirementsOptions = {},
+): string[] {
+  const requirements: string[] = [];
+
+  if (spec.type === "function") {
+    // Functions can have explicit requirements
+    const funcSpec = spec as FunctionSpecification;
+    if (funcSpec.requirements) {
+      requirements.push(...funcSpec.requirements);
+    }
+  } else if (spec.type === "color" && options.includeColorTypeDependencies) {
+    // Color types have requirements through conversions (when flag is enabled)
+    // This is useful for testing to ensure all conversion types are loaded
+    const colorSpec = spec as ColorSpecification;
+    for (const conversion of colorSpec.conversions || []) {
+      // Add source if it's not $self
+      if (conversion.source !== "$self") {
+        requirements.push(conversion.source);
+      }
+      // Add target if it's not $self
+      if (conversion.target !== "$self") {
+        requirements.push(conversion.target);
+      }
+    }
+  }
+  // Note: By default, color types don't have dependencies via conversions
+  // Conversions are capabilities, not requirements
+
+  return requirements;
+}
+
+/**
+ * Resolve a URI to a schema slug and type
+ * Works with both full URIs and just schema names
+ *
+ * @example
+ * resolveSchemaReference("/api/v1/core/rgb-color/0/") => { slug: "rgb-color", type: "type" }
+ * resolveSchemaReference("rgb-color") => { slug: "rgb-color", type: "type" }
+ */
+export function resolveSchemaReference(uriOrName: string): SchemaReference | null {
+  // Try parsing as URI first
+  const components = parseSchemaUri(uriOrName);
+
+  if (components) {
+    // Successfully parsed as URI
+    const type = components.category === "function" ? "function" : "type";
+    return {
+      slug: components.name,
+      type,
+      uri: uriOrName,
+    };
+  }
+
+  // Try extracting name (handles partial URIs)
+  const extractedName = extractSchemaName(uriOrName);
+  if (extractedName) {
+    return {
+      slug: extractedName,
+      type: "type", // Default to type if we can't determine
+      uri: uriOrName,
+    };
+  }
+
+  // Treat as plain slug
+  if (uriOrName && !uriOrName.includes("/")) {
+    return {
+      slug: uriOrName,
+      type: "type", // Default to type
+      uri: "", // No URI, just a slug
+    };
+  }
+
+  return null;
+}
+
+export interface ResolvedDependencies {
+  types: string[];
+  functions: string[];
+}
+
+export interface DependencyNode {
+  slug: string;
+  type: "type" | "function";
+  dependencies: string[];
+}
+
+export interface CollectRequiredSchemasOptions extends ExtractRequirementsOptions {
+  baseUrl?: string;
+  schemasDir?: string;
+}
+
+/**
+ * Recursively collect all required schemas for a given schema
+ * Returns a flat list of all dependencies (including transitive ones)
+ *
+ * @param slugOrUri - Schema slug (e.g., "rgb-color") or full URI
+ * @param type - Schema type ("type" or "function"), optional if URI is provided
+ * @param options - Options for dependency collection
+ * @returns Object with separated type and function dependencies
+ *
+ * @example
+ * // Using slug
+ * await collectRequiredSchemas("invert", "function")
+ * // => { types: ["rgb-color", "hex-color"], functions: [] }
+ *
+ * // Using URI
+ * await collectRequiredSchemas("/api/v1/core/rgb-color/0/")
+ * // => { types: ["hex-color"], functions: [] }
+ */
+export async function collectRequiredSchemas(
+  slugOrUri: string,
+  type?: "type" | "function",
+  options: CollectRequiredSchemasOptions = {},
+): Promise<ResolvedDependencies> {
+  const { baseUrl, schemasDir, ...extractOptions } = options;
+  const visited = new Set<string>();
+  const typeSchemas = new Set<string>();
+  const functionSchemas = new Set<string>();
+
+  async function traverse(currentSlugOrUri: string, currentType?: "type" | "function") {
+    // Resolve to a proper schema reference
+    const ref = resolveSchemaReference(currentSlugOrUri);
+    if (!ref) {
+      log.warn(`Could not resolve schema reference: ${currentSlugOrUri}`);
+      return;
+    }
+
+    // Use provided type if available, otherwise use resolved type
+    const effectiveType = currentType || ref.type;
+    const slug = ref.slug;
+
+    // Create a unique key for visited tracking
+    const key = `${effectiveType}:${slug}`;
+    if (visited.has(key)) {
+      return;
+    }
+    visited.add(key);
+
+    // Try to load the schema
+    let spec: SchemaSpecification;
+    try {
+      // Dynamically determine schema directory
+      const categoryDir = effectiveType === "type" ? "types" : "functions";
+      const resolvedSchemasDir =
+        schemasDir || process.env.SCHEMAS_DIR || join(process.cwd(), "src/schemas");
+      const schemaDir = join(resolvedSchemasDir, categoryDir, slug);
+
+      spec = await bundleSchemaFromDirectory(schemaDir, baseUrl ? { baseUrl } : undefined);
+    } catch (error) {
+      log.warn(`Failed to load schema ${slug} (${effectiveType}):`, error);
+      return;
+    }
+
+    // Extract requirements from this schema
+    const requirements = extractRequirements(spec, extractOptions);
+
+    // Recursively traverse requirements
+    for (const reqUri of requirements) {
+      const reqRef = resolveSchemaReference(reqUri);
+      if (reqRef) {
+        // Add to appropriate set
+        if (reqRef.type === "function") {
+          functionSchemas.add(reqRef.slug);
+        } else {
+          typeSchemas.add(reqRef.slug);
+        }
+
+        // Recursively collect dependencies
+        await traverse(reqUri, reqRef.type);
+      }
+    }
+  }
+
+  // Start traversal
+  await traverse(slugOrUri, type);
+
+  return {
+    types: Array.from(typeSchemas),
+    functions: Array.from(functionSchemas),
+  };
+}
+
+/**
+ * Collect all schemas needed for a list of schemas (including their dependencies)
+ *
+ * @example
+ * await collectRequiredSchemasForList([
+ *   { slug: "invert", type: "function" },
+ *   { slug: "rgb-color", type: "type" }
+ * ])
+ * // => { types: ["rgb-color", "hex-color"], functions: ["invert"] }
+ */
+export async function collectRequiredSchemasForList(
+  schemas: Array<{ slug: string; type: "type" | "function" }>,
+  options: CollectRequiredSchemasOptions = {},
+): Promise<ResolvedDependencies> {
+  const allTypes = new Set<string>();
+  const allFunctions = new Set<string>();
+
+  for (const schema of schemas) {
+    const deps = await collectRequiredSchemas(schema.slug, schema.type, options);
+
+    // Add the schema itself
+    if (schema.type === "function") {
+      allFunctions.add(schema.slug);
+    } else {
+      allTypes.add(schema.slug);
+    }
+
+    // Add dependencies
+    for (const t of deps.types) {
+      allTypes.add(t);
+    }
+    for (const f of deps.functions) {
+      allFunctions.add(f);
+    }
+  }
+
+  return {
+    types: Array.from(allTypes),
+    functions: Array.from(allFunctions),
+  };
+}
+
+/**
+ * Collect dependency tree for schemas (non-recursive, shows direct dependencies only)
+ */
+export async function collectDependencyTree(
+  schemas: Array<{ slug: string; type: "type" | "function" }>,
+  options: CollectRequiredSchemasOptions = {},
+): Promise<Map<string, DependencyNode>> {
+  const { baseUrl, schemasDir, ...extractOptions } = options;
+  const tree = new Map<string, DependencyNode>();
+
+  for (const schema of schemas) {
+    const categoryDir = schema.type === "type" ? "types" : "functions";
+    const resolvedSchemasDir =
+      schemasDir || process.env.SCHEMAS_DIR || join(process.cwd(), "src/schemas");
+    const schemaDir = join(resolvedSchemasDir, categoryDir, schema.slug);
+
+    try {
+      const spec = await bundleSchemaFromDirectory(schemaDir, baseUrl ? { baseUrl } : undefined);
+      const requirements = extractRequirements(spec, extractOptions);
+
+      // Extract just the slugs from URIs
+      const dependencySlugs = requirements.map((uri) => {
+        const ref = resolveSchemaReference(uri);
+        return ref ? `${ref.type}:${ref.slug}` : uri;
+      });
+
+      const key = `${schema.type}:${schema.slug}`;
+      tree.set(key, {
+        slug: schema.slug,
+        type: schema.type,
+        dependencies: dependencySlugs,
+      });
+    } catch (error) {
+      log.warn(`Failed to load schema ${schema.slug} (${schema.type}):`, error);
+    }
+  }
+
+  return tree;
+}

package/src/bundler/selective-bundler.test.ts

@@ -0,0 +1,94 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { bundleSelectiveSchemas } from "./selective-bundler.js";
+
+const SCHEMAS_DIR = join(process.cwd(), "src/schemas");
+
+describe("Selective Bundler", () => {
+  it("should bundle a single type schema", async () => {
+    const result = await bundleSelectiveSchemas({
+      schemas: ["hex-color"],
+      schemasDir: SCHEMAS_DIR,
+    });
+
+    expect(result.schemas).toHaveLength(1);
+    expect(result.schemas[0].uri).toContain("hex-color");
+    expect(result.schemas[0].schema.type).toBe("color");
+    expect(result.metadata.requestedSchemas).toEqual(["hex-color"]);
+  });
+
+  it("should bundle multiple type schemas with dependencies", async () => {
+    const result = await bundleSelectiveSchemas({
+      schemas: ["rgb-color", "oklch-color"],
+      schemasDir: SCHEMAS_DIR,
+    });
+
+    // Should include requested schemas plus dependencies
+    expect(result.schemas.length).toBeGreaterThan(2);
+
+    // Check that requested schemas are included
+    const uris = result.schemas.map((s) => s.uri);
+    expect(uris.some((uri) => uri.includes("rgb-color"))).toBe(true);
+    expect(uris.some((uri) => uri.includes("oklch-color"))).toBe(true);
+
+    // Check that hex-color (a common dependency) is included
+    expect(uris.some((uri) => uri.includes("hex-color"))).toBe(true);
+  });
+
+  it("should bundle function schema with type dependencies", async () => {
+    const result = await bundleSelectiveSchemas({
+      schemas: ["function:invert"],
+      schemasDir: SCHEMAS_DIR,
+    });
+
+    const uris = result.schemas.map((s) => s.uri);
+
+    // Should include the function itself
+    expect(uris.some((uri) => uri.includes("/function/invert/"))).toBe(true);
+
+    // Should include type dependencies (rgb-color, hex-color)
+    expect(uris.some((uri) => uri.includes("rgb-color"))).toBe(true);
+    expect(uris.some((uri) => uri.includes("hex-color"))).toBe(true);
+  });
+
+  it("should inline script content", async () => {
+    const result = await bundleSelectiveSchemas({
+      schemas: ["hex-color"],
+      schemasDir: SCHEMAS_DIR,
+    });
+
+    const hexSchema = result.schemas[0].schema;
+
+    if (hexSchema.type === "color") {
+      // Check that initializer script is inlined (not a file reference)
+      const initScript = hexSchema.initializers[0].script.script;
+      expect(initScript).not.toContain("./");
+      expect(initScript.length).toBeGreaterThan(10);
+    }
+  });
+
+  it("should use provided base URL in URIs", async () => {
+    const customBaseUrl = "https://custom.example.com";
+
+    const result = await bundleSelectiveSchemas({
+      schemas: ["hex-color"],
+      schemasDir: SCHEMAS_DIR,
+      baseUrl: customBaseUrl,
+    });
+
+    expect(result.schemas[0].uri).toContain(customBaseUrl);
+  });
+
+  it("should include metadata", async () => {
+    const result = await bundleSelectiveSchemas({
+      schemas: ["rgb-color"],
+      schemasDir: SCHEMAS_DIR,
+    });
+
+    expect(result.metadata.requestedSchemas).toEqual(["rgb-color"]);
+    expect(result.metadata.resolvedDependencies).toContain("rgb-color");
+    expect(result.metadata.resolvedDependencies).toContain("hex-color");
+    expect(result.metadata.generatedAt).toBeDefined();
+    expect(new Date(result.metadata.generatedAt).getTime()).toBeGreaterThan(0);
+  });
+});

package/src/bundler/selective-bundler.ts

@@ -0,0 +1,159 @@
+/**
+ * Selective schema bundler for CLI
+ * Bundles specific schemas with automatic dependency resolution
+ */
+
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { bundleSchemaFromDirectory } from "./bundle-schema.js";
+import {
+  collectDependencyTree,
+  collectRequiredSchemasForList,
+  type DependencyNode,
+} from "./schema-dependency-resolver.js";
+import type { ColorSpecification, FunctionSpecification } from "./types.js";
+
+export interface SelectiveBundleOptions {
+  schemas: string[]; // Schema slugs to bundle
+  schemasDir?: string; // Source directory (default: src/schemas)
+  baseUrl?: string; // Registry URL for URIs
+}
+
+export interface BundledSchemaEntry {
+  uri: string;
+  schema: ColorSpecification | FunctionSpecification;
+}
+
+export interface SelectiveBundleResult {
+  schemas: BundledSchemaEntry[];
+  metadata: {
+    requestedSchemas: string[];
+    resolvedDependencies: string[];
+    generatedAt: string;
+  };
+  dependencyTree: Map<string, DependencyNode>;
+}
+
+/**
+ * Detect whether a schema is a type or function by checking which directory exists
+ */
+async function detectSchemaType(
+  slug: string,
+  schemasDir: string,
+): Promise<"type" | "function" | null> {
+  const typeDir = join(schemasDir, "types", slug);
+  const functionDir = join(schemasDir, "functions", slug);
+
+  try {
+    await access(typeDir);
+    return "type";
+  } catch {
+    // Not a type, try function
+  }
+
+  try {
+    await access(functionDir);
+    return "function";
+  } catch {
+    // Not found in either
+  }
+
+  return null;
+}
+
+/**
+ * Bundle specific schemas with automatic dependency resolution
+ */
+export async function bundleSelectiveSchemas(
+  options: SelectiveBundleOptions,
+): Promise<SelectiveBundleResult> {
+  const schemasDir = options.schemasDir || join(process.cwd(), "src/schemas");
+  const baseUrl = options.baseUrl || "https://schema.tokenscript.dev.gcp.tokens.studio";
+
+  // Parse schema slugs - they might have type prefixes like "function:invert"
+  const parsedSchemas = await Promise.all(
+    options.schemas.map(async (slug) => {
+      if (slug.includes(":")) {
+        const [type, name] = slug.split(":");
+        return {
+          slug: name,
+          type: (type === "function" ? "function" : "type") as "type" | "function",
+        };
+      }
+
+      // Auto-detect type by checking which directory exists
+      const detectedType = await detectSchemaType(slug, schemasDir);
+      if (detectedType === null) {
+        throw new Error(
+          `Schema '${slug}' not found in types or functions directories. ` +
+            `Use 'function:${slug}' or 'type:${slug}' prefix to be explicit.`,
+        );
+      }
+
+      return { slug, type: detectedType };
+    }),
+  );
+
+  // Collect all required schemas (including dependencies)
+  // For CLI bundling, we include color type dependencies so conversions work
+  const deps = await collectRequiredSchemasForList(parsedSchemas, {
+    baseUrl,
+    schemasDir,
+    includeColorTypeDependencies: true,
+  });
+
+  // Collect dependency tree for all schemas (including resolved dependencies)
+  const allParsedSchemas = [
+    ...deps.types.map((slug) => ({ slug, type: "type" as const })),
+    ...deps.functions.map((slug) => ({ slug, type: "function" as const })),
+  ];
+  const dependencyTree = await collectDependencyTree(allParsedSchemas, {
+    baseUrl,
+    schemasDir,
+    includeColorTypeDependencies: true,
+  });
+
+  // Track all schema slugs for metadata
+  const allSchemas = [...new Set([...deps.types, ...deps.functions])];
+
+  // Bundle all schemas
+  const bundledSchemas: BundledSchemaEntry[] = [];
+
+  // Bundle type schemas
+  for (const typeSlug of deps.types) {
+    const schemaDir = join(schemasDir, "types", typeSlug);
+    const bundled = await bundleSchemaFromDirectory(schemaDir, { baseUrl });
+
+    if (bundled.type === "color") {
+      const uri = `${baseUrl}/api/v1/core/${typeSlug}/0/`;
+      bundledSchemas.push({
+        uri,
+        schema: bundled as ColorSpecification,
+      });
+    }
+  }
+
+  // Bundle function schemas
+  for (const funcSlug of deps.functions) {
+    const schemaDir = join(schemasDir, "functions", funcSlug);
+    const bundled = await bundleSchemaFromDirectory(schemaDir, { baseUrl });
+
+    if (bundled.type === "function") {
+      const uri = `${baseUrl}/api/v1/function/${funcSlug}/0/`;
+      bundledSchemas.push({
+        uri,
+        schema: bundled as FunctionSpecification,
+      });
+    }
+  }
+
+  return {
+    schemas: bundledSchemas,
+    metadata: {
+      requestedSchemas: options.schemas,
+      resolvedDependencies: allSchemas,
+      generatedAt: new Date().toISOString(),
+    },
+    dependencyTree,
+  };
+}