@rafters/shared 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ezmode Games
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @rafters/shared
+
+> The data model the rest of Rafters is built on: W3C DTCG token schemas, base types, and the utilities that read a component's own intelligence.
+
+Everything in Rafters that describes a token, a color, or a component agrees on
+one set of shapes. This package holds them. It is Zod-first, so every schema is
+both a runtime validator and a TypeScript type. Parse external data through the
+schema and you get a typed value or a clear error, never an unchecked `any`.
+
+## Install
+
+Published as TypeScript source; consumers need a bundler or tsx/vite. Plain
+`node` cannot import it.
+
+```bash
+pnpm add @rafters/shared
+```
+
+Import from another package:
+
+```ts
+import {
+  OKLCHSchema,
+  DTCGColorTokenSchema,
+  oklchToDTCG,
+  parseJSDocIntelligence,
+  parseFillSignature,
+  ImportPendingSchema,
+  RAFTERS_VERSION,
+} from '@rafters/shared';
+```
+
+Types live at the same entry, plus a narrow `./types` subpath for the schema
+layer on its own:
+
+```ts
+import type { OKLCH, DTCGColorToken, ComponentIntelligence } from '@rafters/shared/types';
+```
+
+## What's inside
+
+### Token schemas (`types.ts`)
+
+The W3C Design Token Community Group spec, expressed as Zod schemas Rafters can
+validate against.
+
+- `OKLCHSchema` / `OKLCH` — the color primitive. Every color in the system is
+  OKLCH before it is anything else.
+- `DTCGTokenBaseSchema`, `DTCGColorTokenSchema`, `DTCGGroupSchema`,
+  `DTCGFileSchema` — a token, a color token, a group, and a whole `.tokens.json`
+  file, following the DTCG shape.
+- `oklchToDTCG(oklch)` / `dtcgToOKLCH(dtcg)` — cross the line between the color
+  primitive and the on-disk token value.
+- `ComponentIntelligenceSchema`, `ColorIntelligenceSchema`, `IntelligenceSchema`
+  and friends — the shapes the MCP and Studio read when they describe a
+  component or a color.
+- `COMPUTED` — a sentinel symbol. Set a token to it and the system reverts that
+  token to its computed value instead of a hardcoded override.
+
+### Component intelligence (`component-intelligence.ts`)
+
+A component carries its own design guidance in a JSDoc block. This module reads
+it back out.
+
+- `parseJSDocIntelligence(source)` — pull the six-tag intelligence block out of a
+  component's source into a structured object.
+- `extractVariants`, `extractSizes`, `extractDependencies`,
+  `extractPrimitiveDependencies`, `extractJSDocDependencies` — targeted reads for
+  one facet at a time.
+- `findComponentCategory(registry, name)` — look up a category by name in a
+  registry. `DEFAULT_COMPONENT_CATEGORIES` is the registry Rafters ships.
+- `validateComponentIntelligence(...)` — check a parsed block and return warnings
+  for what's missing or malformed.
+- `toDisplayName(name)` — turn a component id into its display name.
+
+### Fill signatures (`fill-signature.ts`)
+
+`fill=` is a compact color vocabulary, not a styling grammar. `fill="muted/50"`
+is the muted color at 50% alpha; `fill="barbie-pink-to-ken-brown"` is a two-stop
+gradient. `to`, `via`, and `from` are reserved segments.
+
+- `parseFillSignature(input)` — parse a fill string into stops and alpha.
+- `validateFillSignature(signature, hasWord)` — check every stop word against a
+  vocabulary predicate; returns the first unresolvable word, or `null`.
+- `expandFillSignature(signature, context, hasWord?)` — expand a signature into
+  the classes it sets, for the given context (`surface` or `text`).
+- `foregroundWordFor(...)` — pick the readable foreground word for a surface fill.
+
+### Import pending (`import-pending.ts`)
+
+The schema for tokens found during `rafters init` detection and left awaiting
+review. Written to `.rafters/import-pending.json`, read by the CLI prompts and
+the Studio review UI.
+
+- `ImportPendingSchema` and its parts (`PendingTokenSchema`,
+  `PendingPaletteSchema`, `ImportOriginalSchema`, `ImportModificationsSchema`).
+- `ImportDecisionSchema` — `pending`, `accepted`, `rejected`, or `modified`.
+
+Each pending entry keeps the original source variable, the proposed Rafters
+token, the user's decision, and the confidence and rationale behind the mapping.
+
+### Version (`version.ts`)
+
+- `RAFTERS_VERSION` — the lockstep suite version, written by
+  `packages/cli/scripts/sync-version.ts` from the CLI's own version at build
+  time. Read by the API root endpoint and anywhere else that reports it.
+
+## Testing
+
+```bash
+pnpm --filter @rafters/shared test
+```
+
+## Notes
+
+- Everything external is parsed through a schema. That is the rule the whole
+  design system leans on, so this package is where it starts.
+- Schemas and their inferred types share a name (`OKLCHSchema` validates,
+  `OKLCH` is the type). Import the schema to check data, the type to annotate it.
+- Published as TypeScript source. It gains nothing from a build step, but a
+  consumer needs a bundler or tsx/vite to import it — plain `node` cannot.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rafters/shared",
+  "version": "0.2.3",
+  "description": "Shared W3C DTCG schemas, base types, and utilities for Rafters design system",
+  "homepage": "https://rafters.studio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafters-studio/rafters.git",
+    "directory": "packages/shared"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf .turbo coverage"
+  },
+  "dependencies": {
+    "comment-parser": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "zocker": "catalog:"
+  }
+}

package/src/component-intelligence.ts

@@ -0,0 +1,477 @@
+/**
+ * Component Intelligence
+ * Types and utilities for parsing component intelligence metadata from JSDoc comments
+ *
+ * Intelligence metadata captures design decisions and cognitive load information
+ * embedded in component source files via JSDoc tags.
+ *
+ * ---- Canonical JSDoc Intelligence Format ----
+ *
+ * All Rafters components use 6 intelligence tags in their JSDoc block.
+ * The canonical format for usage patterns is DO:/NEVER: lines under @usage-patterns.
+ *
+ * Example (from button.tsx):
+ *
+ *   /**
+ *    * Interactive button component for user actions
+ *    *
+ *    * @cognitive-load 3/10 - Simple action trigger with clear visual hierarchy
+ *    * @attention-economics Size hierarchy: sm=tertiary, default=secondary, lg=primary
+ *    * @trust-building Destructive actions require confirmation patterns
+ *    * @accessibility WCAG AAA compliant with 44px minimum touch targets
+ *    * @semantic-meaning Variant mapping: default=main, destructive=irreversible
+ *    *
+ *    * @usage-patterns
+ *    * DO: Primary: Main user goal, maximum 1 per section
+ *    * DO: Secondary: Alternative paths, supporting actions
+ *    * NEVER: Multiple primary buttons competing for attention
+ *    * /
+ *
+ * Parsing paths:
+ *   1. Canonical: DO:/NEVER: lines within the @usage-patterns tag value
+ *   2. Legacy: Separate @do and @never tags (still supported)
+ *
+ * Both paths populate the same usagePatterns.dos[] and usagePatterns.nevers[] arrays.
+ * If both formats appear in the same block, results are merged (no deduplication).
+ *
+ * Required intelligence tags (all 6 should be present on every component):
+ *   - @cognitive-load (number/10 format, e.g. "3/10 - Description")
+ *   - @attention-economics (free text)
+ *   - @trust-building (free text)
+ *   - @accessibility (free text)
+ *   - @semantic-meaning (free text)
+ *   - @usage-patterns (with DO:/NEVER: lines)
+ */
+
+import { parse, type Spec } from 'comment-parser';
+import { z } from 'zod';
+
+// ==================== Types ====================
+
+/**
+ * Intelligence metadata extracted from component JSDoc comments
+ * Named JSDocIntelligence to avoid conflict with ComponentIntelligence in types.ts
+ */
+export interface JSDocIntelligence {
+  /** Cognitive load score (0-10 scale) */
+  cognitiveLoad?: number;
+  /** Attention economics guidance */
+  attentionEconomics?: string;
+  /** Accessibility requirements and guidance */
+  accessibility?: string;
+  /** Trust-building patterns */
+  trustBuilding?: string;
+  /** Semantic meaning and purpose */
+  semanticMeaning?: string;
+  /** Usage patterns with dos and nevers */
+  usagePatterns?: {
+    dos: string[];
+    nevers: string[];
+  };
+}
+
+/**
+ * A component category is a label + description. The library ships a default
+ * registry covering the rafters component taxonomy; consumers may use, extend,
+ * or replace it. Built-in and user-defined categories are structurally identical.
+ */
+export const ComponentCategorySchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+});
+export type ComponentCategory = z.infer<typeof ComponentCategorySchema>;
+
+export const DEFAULT_COMPONENT_CATEGORIES: ComponentCategory[] = [
+  { name: 'layout', description: 'Components for structuring and organizing content' },
+  { name: 'form', description: 'Input controls and form elements' },
+  { name: 'feedback', description: 'Status indicators and user feedback' },
+  { name: 'navigation', description: 'Wayfinding and navigation components' },
+  { name: 'overlay', description: 'Modals, dialogs, and overlay components' },
+  { name: 'data-display', description: 'Components for displaying data and content' },
+  { name: 'utility', description: 'Helper and utility components' },
+];
+
+/** Look up a category by name in a registry. Returns undefined if not found. */
+export const findComponentCategory = (
+  registry: readonly ComponentCategory[],
+  name: string,
+): ComponentCategory | undefined => registry.find((c) => c.name === name);
+
+/**
+ * Structured dependency information extracted from JSDoc tags
+ */
+export interface JSDocDependencies {
+  /** Runtime dependencies from @dependencies tag */
+  runtime: string[];
+  /** Dev dependencies from @devDependencies tag */
+  dev: string[];
+  /** Internal workspace dependencies from @internal-dependencies tag */
+  internal: string[];
+}
+
+/**
+ * Full component metadata including intelligence
+ */
+export interface ComponentMetadata {
+  /** Component file name (without extension) */
+  name: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Brief description from JSDoc */
+  description?: string;
+  /** Category name -- reference into a ComponentCategory registry */
+  category: string;
+  /** Intelligence metadata */
+  intelligence?: JSDocIntelligence;
+  /** Available variants */
+  variants: string[];
+  /** Available sizes */
+  sizes: string[];
+  /** External dependencies */
+  dependencies: string[];
+  /** Primitive dependencies */
+  primitives: string[];
+  /** Structured dependency information from JSDoc tags */
+  jsDocDependencies?: JSDocDependencies;
+  /** Relative file path */
+  filePath: string;
+}
+
+// ==================== Parser ====================
+
+/**
+ * Parse JSDoc comments from source to extract intelligence metadata
+ */
+export function parseJSDocIntelligence(source: string): JSDocIntelligence | undefined {
+  const blocks = parse(source);
+  if (blocks.length === 0) return undefined;
+
+  const intelligence: JSDocIntelligence = {};
+  let hasAnyField = false;
+
+  // Process all JSDoc blocks
+  for (const block of blocks) {
+    for (const tag of block.tags) {
+      const tagName = tag.tag.toLowerCase();
+      const value = getTagValue(tag);
+
+      switch (tagName) {
+        case 'cognitive-load':
+        case 'cognitiveload': {
+          // Parse format: "6/10 - Description" or just "6"
+          const match = value.match(/^(\d+)(?:\/10)?/);
+          if (match?.[1]) {
+            const num = Number.parseInt(match[1], 10);
+            if (!Number.isNaN(num) && num >= 0 && num <= 10) {
+              intelligence.cognitiveLoad = num;
+              hasAnyField = true;
+            }
+          }
+          break;
+        }
+        case 'attention-economics':
+        case 'attentioneconomics':
+          intelligence.attentionEconomics = value;
+          hasAnyField = true;
+          break;
+        case 'accessibility':
+          intelligence.accessibility = value;
+          hasAnyField = true;
+          break;
+        case 'trust-building':
+        case 'trustbuilding':
+          intelligence.trustBuilding = value;
+          hasAnyField = true;
+          break;
+        case 'semantic-meaning':
+        case 'semanticmeaning':
+          intelligence.semanticMeaning = value;
+          hasAnyField = true;
+          break;
+        case 'usage-patterns':
+        case 'usagepatterns':
+          // Parse DO:/NEVER: patterns from value
+          parseUsagePatternsInline(value, intelligence);
+          hasAnyField = true;
+          break;
+        case 'do':
+          if (!intelligence.usagePatterns) {
+            intelligence.usagePatterns = { dos: [], nevers: [] };
+          }
+          intelligence.usagePatterns.dos.push(value);
+          hasAnyField = true;
+          break;
+        case 'never':
+          if (!intelligence.usagePatterns) {
+            intelligence.usagePatterns = { dos: [], nevers: [] };
+          }
+          intelligence.usagePatterns.nevers.push(value);
+          hasAnyField = true;
+          break;
+      }
+    }
+  }
+
+  return hasAnyField ? intelligence : undefined;
+}
+
+/**
+ * Parse usage patterns from inline format
+ * Format: "DO: foo NEVER: bar DO: baz"
+ */
+function parseUsagePatternsInline(value: string, intelligence: JSDocIntelligence): void {
+  if (!intelligence.usagePatterns) {
+    intelligence.usagePatterns = { dos: [], nevers: [] };
+  }
+
+  // Match DO: patterns - use negative lookahead to match any chars except keywords
+  const doMatches = value.matchAll(/DO:\s*((?:(?!DO:|NEVER:).)+?)(?=(?:DO:|NEVER:|$))/gi);
+  for (const match of doMatches) {
+    const text = match[1]?.trim();
+    if (text) intelligence.usagePatterns.dos.push(text);
+  }
+
+  // Match NEVER: patterns - use negative lookahead to match any chars except keywords
+  const neverMatches = value.matchAll(/NEVER:\s*((?:(?!DO:|NEVER:).)+?)(?=(?:DO:|NEVER:|$))/gi);
+  for (const match of neverMatches) {
+    const text = match[1]?.trim();
+    if (text) intelligence.usagePatterns.nevers.push(text);
+  }
+}
+
+/**
+ * Extract the full value from a JSDoc tag (name + description)
+ */
+function getTagValue(tag: Spec): string {
+  const parts: string[] = [];
+  if (tag.name) parts.push(tag.name);
+  if (tag.description) parts.push(tag.description);
+  return parts.join(' ').trim();
+}
+
+/**
+ * Parse description from JSDoc (first line before tags)
+ */
+export function parseDescription(source: string): string | undefined {
+  const blocks = parse(source);
+  if (blocks.length === 0) return undefined;
+
+  const description = blocks[0]?.description;
+  return description ? description.trim() : undefined;
+}
+
+// ==================== Extraction Utilities ====================
+
+/**
+ * Extract variants from component source
+ * Looks for variant prop type definitions
+ */
+export function extractVariants(source: string): string[] {
+  // Match variant type like: variant?: 'default' | 'secondary' | 'destructive'
+  const match = source.match(/variant\??\s*:\s*(['"][^'"]+['"](?:\s*\|\s*['"][^'"]+['"])*)/);
+
+  if (!match?.[1]) return ['default'];
+
+  const values: string[] = [];
+  const allMatches = [...match[1].matchAll(/['"]([^'"]+)['"]/g)];
+
+  for (const m of allMatches) {
+    const val = m[1];
+    if (val) values.push(val);
+  }
+
+  return values.length > 0 ? values : ['default'];
+}
+
+/**
+ * Extract sizes from component source
+ */
+export function extractSizes(source: string): string[] {
+  // Match size type like: size?: 'sm' | 'default' | 'lg'
+  const match = source.match(/size\??\s*:\s*(['"][^'"]+['"](?:\s*\|\s*['"][^'"]+[''])*)/);
+
+  if (!match?.[1]) return ['default'];
+
+  const values: string[] = [];
+  const allMatches = [...match[1].matchAll(/['"]([^'"]+)['"]/g)];
+
+  for (const m of allMatches) {
+    const val = m[1];
+    if (val) values.push(val);
+  }
+
+  return values.length > 0 ? values : ['default'];
+}
+
+/**
+ * Extract external dependencies from imports
+ */
+export function extractDependencies(source: string): string[] {
+  const deps: string[] = [];
+  const allMatches = [...source.matchAll(/import\s+.*?from\s+['"]([^'"]+)['"]/g)];
+
+  for (const match of allMatches) {
+    const pkg = match[1];
+    // Only include external packages, not relative imports
+    if (pkg && !pkg.startsWith('.') && !pkg.startsWith('/')) {
+      if (!deps.includes(pkg)) {
+        deps.push(pkg);
+      }
+    }
+  }
+
+  return deps;
+}
+
+/**
+ * Extract primitive dependencies from source
+ */
+export function extractPrimitiveDependencies(source: string): string[] {
+  const primitives: string[] = [];
+  const allMatches = [...source.matchAll(/import\s+.*?from\s+['"]([^'"]+)['"]/g)];
+
+  for (const match of allMatches) {
+    const pkg = match[1];
+    // Check if it's a primitive import
+    if (pkg && (pkg.includes('/primitives/') || pkg.includes('../primitives/'))) {
+      const primitiveName = pkg
+        .split('/')
+        .pop()
+        ?.replace(/\.(ts|tsx)$/, '');
+      if (primitiveName && !primitives.includes(primitiveName)) {
+        primitives.push(primitiveName);
+      }
+    }
+  }
+
+  return primitives;
+}
+
+/** Maps lowercase JSDoc tag names to their JSDocDependencies field */
+const DEP_TAG_MAP: Record<string, keyof JSDocDependencies> = {
+  dependencies: 'runtime',
+  devdependencies: 'dev',
+  'internal-dependencies': 'internal',
+  internaldependencies: 'internal',
+};
+
+/**
+ * Extract structured dependency information from JSDoc tags
+ *
+ * Parses three dependency tags from JSDoc comments:
+ * - @dependencies - runtime dependencies (e.g., nanostores@^0.11.0)
+ * - @devDependencies - dev dependencies
+ * - @internal-dependencies - internal workspace dependencies (e.g., @rafters/color-utils)
+ *
+ * Values are split on whitespace. Tags present but empty produce empty arrays.
+ * Missing tags also produce empty arrays.
+ */
+export function extractJSDocDependencies(source: string): JSDocDependencies {
+  const result: JSDocDependencies = { runtime: [], dev: [], internal: [] };
+  const blocks = parse(source);
+  if (blocks.length === 0) return result;
+
+  for (const block of blocks) {
+    for (const tag of block.tags) {
+      const field = DEP_TAG_MAP[tag.tag.toLowerCase()];
+      if (!field) continue;
+
+      const value = getTagValue(tag).trim();
+      if (value) {
+        const tokens = value.split(/\s+/).filter(Boolean);
+        const validTokens: string[] = [];
+        for (const token of tokens) {
+          if (token.startsWith('(')) break;
+          validTokens.push(token);
+        }
+        result[field].push(...validTokens);
+      }
+    }
+  }
+
+  return {
+    runtime: [...new Set(result.runtime)],
+    dev: [...new Set(result.dev)],
+    internal: [...new Set(result.internal)],
+  };
+}
+
+/**
+ * Convert kebab-case to Title Case
+ */
+export function toDisplayName(name: string): string {
+  return name
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+// ==================== Validation ====================
+
+/** The 6 required intelligence tags for a complete component */
+const REQUIRED_TAGS = [
+  'cognitiveLoad',
+  'attentionEconomics',
+  'accessibility',
+  'trustBuilding',
+  'semanticMeaning',
+  'usagePatterns',
+] as const;
+
+/**
+ * A warning produced when component intelligence metadata is incomplete or suspect
+ */
+export interface IntelligenceWarning {
+  /** Warning severity: "missing" for absent data, "empty" for present but hollow data */
+  level: 'missing' | 'empty';
+  /** Human-readable warning message */
+  message: string;
+}
+
+/**
+ * Validate component intelligence metadata for completeness.
+ *
+ * Detects two classes of problems:
+ *   1. Missing required intelligence tags (all 6 should be present)
+ *   2. usagePatterns present but with zero DO: or NEVER: lines extracted
+ *      (suggests a parsing failure or malformed JSDoc)
+ *
+ * Returns an empty array when the intelligence is complete and well-formed.
+ */
+export function validateComponentIntelligence(
+  componentName: string,
+  intelligence: JSDocIntelligence | undefined,
+): IntelligenceWarning[] {
+  const warnings: IntelligenceWarning[] = [];
+
+  if (!intelligence) {
+    warnings.push({
+      level: 'missing',
+      message: `${componentName}: No intelligence metadata found. All 6 tags are required.`,
+    });
+    return warnings;
+  }
+
+  for (const tag of REQUIRED_TAGS) {
+    const value = intelligence[tag];
+    if (value === undefined || value === null) {
+      warnings.push({
+        level: 'missing',
+        message: `${componentName}: Missing required intelligence tag "@${tag}".`,
+      });
+    }
+  }
+
+  // Check for hollow usagePatterns (tag present but no DO:/NEVER: extracted)
+  if (intelligence.usagePatterns) {
+    const { dos, nevers } = intelligence.usagePatterns;
+    if (dos.length === 0 && nevers.length === 0) {
+      warnings.push({
+        level: 'empty',
+        message: `${componentName}: @usage-patterns present but zero DO: or NEVER: lines extracted. Check JSDoc format.`,
+      });
+    }
+  }
+
+  return warnings;
+}