@agent-scope/tokens 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,585 @@
+/**
+ * @agent-scope/tokens — Color utilities
+ *
+ * Converts hex colors to CIE Lab color space and computes perceptual distance.
+ * Uses a Euclidean distance in Lab space as an approximation of CIEDE2000.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Converts a hex color string to CIE Lab [L, a, b].
+ */
+declare function hexToLab(hex: string): [number, number, number];
+/**
+ * Euclidean distance in CIE Lab space.
+ * Approximates perceptual color difference (simplified CIEDE2000).
+ */
+declare function labDistance(a: [number, number, number], b: [number, number, number]): number;
+/**
+ * Parses a color string to CIE Lab.
+ * Supports #RGB, #RRGGBB, #RRGGBBAA formats.
+ * Returns null if the string is not a recognisable hex color.
+ */
+declare function parseColorToLab(color: string): [number, number, number] | null;
+
+/**
+ * @agent-scope/tokens — Type definitions
+ *
+ * Core types for the design token file parser and resolution engine.
+ *
+ * @packageDocumentation
+ */
+type TokenType = "color" | "dimension" | "fontFamily" | "fontWeight" | "number" | "shadow" | "duration" | "cubicBezier";
+declare const TOKEN_TYPES: ReadonlyArray<TokenType>;
+interface TokenValue {
+    value: string | number;
+    type: TokenType;
+    description?: string;
+}
+interface Token {
+    /** Dot-notation path, e.g. "color.primary.500" */
+    path: string;
+    /** Raw value from the token file (may be a reference like "{color.primary.500}") */
+    value: string | number;
+    /** Fully resolved value, always a string */
+    resolvedValue: string;
+    type: TokenType;
+    description?: string;
+}
+interface TokenFileMeta {
+    name?: string;
+    lastUpdated?: string;
+    updatedBy?: string;
+}
+interface TokenFile {
+    $schema?: string;
+    version: string;
+    meta?: TokenFileMeta;
+    tokens: Record<string, unknown>;
+    themes?: Record<string, Record<string, string>>;
+}
+interface TokenMatch {
+    token: Token;
+    /** True when the resolved value exactly matches the queried value */
+    exact: boolean;
+    /** 0 for exact matches; otherwise the computed distance (Lab distance / numeric diff) */
+    distance: number;
+}
+interface ParsedTokens {
+    tokens: Token[];
+    rawFile: TokenFile;
+}
+type TokenParseErrorCode = "CIRCULAR_REFERENCE" | "INVALID_REFERENCE" | "INVALID_SCHEMA" | "PARSE_ERROR";
+declare class TokenParseError extends Error {
+    readonly code: TokenParseErrorCode;
+    readonly path: string | undefined;
+    constructor(message: string, code: TokenParseErrorCode, path?: string);
+}
+interface ValidationError {
+    path: string;
+    message: string;
+    code: string;
+}
+declare class TokenValidationError extends Error {
+    readonly errors: ValidationError[];
+    constructor(message: string, errors: ValidationError[]);
+}
+
+/**
+ * @agent-scope/tokens — Token resolution engine
+ *
+ * Provides path-based lookup, exact and nearest-match search over a resolved
+ * token set.
+ *
+ * @packageDocumentation
+ */
+
+declare class TokenResolver {
+    private readonly tokens;
+    private readonly tokenMap;
+    constructor(tokens: Token[]);
+    /**
+     * Resolves a token path to its computed string value.
+     * @throws TokenParseError with code INVALID_REFERENCE if path is not found
+     */
+    resolve(path: string): string;
+    /**
+     * Returns an exact-match TokenMatch if any token of the given type has a
+     * resolvedValue that equals the queried value (case-insensitive for colors).
+     * Returns null if no exact match exists.
+     */
+    match(value: string, type: TokenType): TokenMatch | null;
+    /**
+     * Returns the TokenMatch with the smallest computed distance to `value`
+     * among all tokens of the given type.
+     *
+     * Distance computation:
+     * - color: Euclidean distance in CIE Lab space
+     * - dimension / duration: |parsed numeric value difference|
+     * - fontWeight / number: |numeric value difference|
+     * - shadow / fontFamily / cubicBezier: string equality (distance 0 or 1)
+     *
+     * @throws Error if there are no tokens of the specified type
+     */
+    nearest(value: string, type: TokenType): TokenMatch;
+    /**
+     * Lists all tokens, optionally filtered by type and/or category
+     * (the first segment of the dot-notation path, e.g. "color" in "color.primary.500").
+     */
+    list(type?: TokenType, category?: string): Token[];
+    private computeDistance;
+}
+
+/**
+ * @agent-scope/tokens — Compliance Engine
+ *
+ * Audits rendered component CSS styles against a resolved token set.
+ * Reports per-property compliance status, nearest-match suggestions, and
+ * an aggregate compliance percentage.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Represents the structured CSS output from a rendered component, grouped by
+ * property category.
+ */
+type ComputedStyles = {
+    /** Colour properties — values must be hex (#RGB / #RRGGBB / #RRGGBBAA) for
+     *  Lab-distance matching; other formats fall back to exact string match. */
+    colors: Record<string, string>;
+    /** Spacing / layout properties — e.g. paddingTop, marginBottom, gap */
+    spacing: Record<string, string>;
+    /** Typography properties — fontFamily, fontSize, fontWeight, lineHeight */
+    typography: Record<string, string>;
+    /** Border properties — borderRadius, borderWidth */
+    borders: Record<string, string>;
+    /** Shadow properties — boxShadow */
+    shadows: Record<string, string>;
+};
+/** Status for a single audited property. */
+type ComplianceStatus = "on_system" | "OFF_SYSTEM";
+/** Per-property audit result. */
+interface PropertyResult {
+    /** CSS property name, e.g. "background" */
+    property: string;
+    /** The value that was audited */
+    value: string;
+    /** Whether the value maps to a design token (within tolerance) */
+    status: ComplianceStatus;
+    /** Token path of the matched token (only when status is "on_system") */
+    token?: string;
+    /** Nearest token found in the system — always present when a candidate
+     *  type had at least one token. */
+    nearest?: {
+        token: string;
+        value: string;
+        distance: number;
+    };
+}
+/** Full audit result for a single component / style set. */
+interface ComplianceReport {
+    /** Map of property name → result */
+    properties: Record<string, PropertyResult>;
+    /** Number of properties audited (excludes skipped/unsupported) */
+    total: number;
+    /** Number of properties that are on-system */
+    onSystem: number;
+    /** Number of properties that are off-system */
+    offSystem: number;
+    /** on-system count / total; 1 when total === 0 */
+    compliance: number;
+    /** ISO timestamp of when the audit was run */
+    auditedAt: string;
+}
+/** Batch audit report — summary across multiple components. */
+interface BatchReport {
+    /** Per-component compliance report, keyed by component name */
+    components: Record<string, ComplianceReport>;
+    /** Total properties audited across all components */
+    totalProperties: number;
+    /** Total on-system properties across all components */
+    totalOnSystem: number;
+    /** Total off-system properties across all components */
+    totalOffSystem: number;
+    /** Aggregate compliance percentage across all components */
+    aggregateCompliance: number;
+    /** ISO timestamp of when the batch audit was run */
+    auditedAt: string;
+}
+/** Configures fuzzy-matching thresholds per property category. */
+interface ComplianceTolerances {
+    /**
+     * Maximum CIE Lab Euclidean distance for a colour to be considered
+     * on-system. Default: 3.
+     */
+    colorTolerance: number;
+    /**
+     * Maximum pixel difference for a dimension (spacing / border / font-size)
+     * to be considered on-system. Default: 2.
+     */
+    dimensionTolerance: number;
+    /**
+     * Maximum font-weight numeric difference to be considered on-system.
+     * Default: 0 (exact only).
+     */
+    fontWeightTolerance: number;
+}
+/**
+ * Audits rendered component styles against a resolved token set.
+ *
+ * @example
+ * ```ts
+ * const { tokens } = parseTokenFileSync(fs.readFileSync("tokens.json", "utf8"));
+ * const resolver = new TokenResolver(tokens);
+ * const engine = new ComplianceEngine(resolver);
+ *
+ * const report = engine.audit({
+ *   colors:     { background: "#3B82F6", color: "#ffffff" },
+ *   spacing:    { paddingTop: "16px", gap: "8px" },
+ *   typography: { fontFamily: "Inter", fontSize: "14px" },
+ *   borders:    { borderRadius: "4px" },
+ *   shadows:    { boxShadow: "0 1px 3px rgba(0,0,0,0.1)" },
+ * });
+ *
+ * console.log(report.compliance); // e.g. 0.83
+ * ```
+ */
+declare class ComplianceEngine {
+    private readonly resolver;
+    private readonly tolerances;
+    constructor(resolver: TokenResolver, tolerances?: Partial<ComplianceTolerances>);
+    /**
+     * Audits a single component's computed styles against the token set.
+     */
+    audit(styles: ComputedStyles): ComplianceReport;
+    /**
+     * Audits multiple components at once and returns a BatchReport with
+     * per-component scores and an aggregate compliance figure.
+     */
+    auditBatch(components: Map<string, ComputedStyles>): BatchReport;
+    /**
+     * Serialises a ComplianceReport to a JSON string.
+     */
+    static toJSON(report: ComplianceReport | BatchReport): string;
+    /**
+     * Determines the TokenType for a typography property.
+     * lineHeight is dimension if it has a unit, otherwise "number".
+     */
+    private resolveTypographyType;
+    /**
+     * Audits a single CSS property value against a specific token type.
+     * Returns null if the resolver has no tokens of that type (nothing to
+     * audit against — property excluded from totals).
+     */
+    private auditProperty;
+    private getToleranceForType;
+    private buildReport;
+}
+
+/**
+ * @agent-scope/tokens — Export Formats
+ *
+ * Converts a resolved token set into various output formats for downstream
+ * tooling consumption.
+ *
+ * Supported formats:
+ * - `css`      — CSS custom properties (:root { --color-primary-500: … })
+ * - `ts`       — TypeScript const exports (export const colorPrimary500 = …)
+ * - `scss`     — SCSS variable declarations ($color-primary-500: …)
+ * - `tailwind` — Tailwind CSS theme.extend object
+ * - `figma`    — Figma Tokens JSON format
+ *
+ * All formats support theme-aware exports via the `themes` option.
+ *
+ * @packageDocumentation
+ */
+
+/** Supported output format identifiers. */
+type ExportFormat = "css" | "ts" | "scss" | "tailwind" | "figma";
+/** Options shared across all export formats. */
+interface ExportOptions {
+    /**
+     * Theme-aware export: map of theme name → Map<tokenPath, resolvedValue>.
+     *
+     * When present:
+     * - CSS: emits `[data-theme="<name>"] { … }` selector blocks
+     * - TS:  emits a `themes` record alongside the default constants
+     * - SCSS: emits `[data-theme="<name>"] { … }` blocks using custom props
+     * - tailwind/figma: includes per-theme variants in the output
+     */
+    themes?: Map<string, Map<string, string>>;
+    /**
+     * CSS / SCSS: prefix for custom property / variable names.
+     * Default: no prefix (plain dot-path conversion, e.g. `color-primary-500`)
+     */
+    prefix?: string;
+    /**
+     * CSS: selector for the root block.
+     * Default: `:root`
+     */
+    rootSelector?: string;
+}
+/**
+ * Exports a resolved token set to the specified format.
+ *
+ * @param tokens - Flat, resolved token array (from TokenResolver or parseTokenFileSync)
+ * @param format - Target output format
+ * @param options - Optional configuration (prefix, themes, rootSelector)
+ * @returns The formatted output string
+ *
+ * @example
+ * ```ts
+ * const { tokens } = parseTokenFileSync(source);
+ * const css = exportTokens(tokens, "css");
+ * const ts = exportTokens(tokens, "ts");
+ * ```
+ */
+declare function exportTokens(tokens: Token[], format: ExportFormat, options?: ExportOptions): string;
+
+/**
+ * @agent-scope/tokens — Impact Analysis Engine
+ *
+ * Analyses the downstream effects of a design token change on a set of
+ * audited components. Given a token path and a proposed new value, it
+ * returns which components and properties would be affected, together with
+ * a perceptual severity estimate for colour tokens.
+ *
+ * @packageDocumentation
+ */
+
+/** Severity of the visual change introduced by the token edit. */
+type VisualSeverity = "none" | "subtle" | "moderate" | "significant";
+/** Details of which properties within one component reference the token. */
+interface AffectedComponent {
+    /** Component name (key used in the compliance batch report) */
+    name: string;
+    /** List of CSS property names that reference the changed token */
+    affectedProperties: string[];
+    /**
+     * Perceptual severity of the change for this component.
+     * Derived from the colour Lab distance or property-type heuristics.
+     */
+    severity: VisualSeverity;
+}
+/** Full impact report for a single token change. */
+interface ImpactReport {
+    /** The token path that was changed */
+    tokenPath: string;
+    /** The previous resolved value */
+    oldValue: string;
+    /** The proposed new value */
+    newValue: string;
+    /** Type of the token */
+    tokenType: TokenType;
+    /** Number of components that reference this token */
+    affectedComponentCount: number;
+    /** Per-component breakdown */
+    components: AffectedComponent[];
+    /**
+     * Overall visual severity — the maximum severity across all components.
+     * "none" when no components are affected.
+     */
+    overallSeverity: VisualSeverity;
+    /** For colour tokens: CIE Lab Euclidean distance between old and new values */
+    colorDelta?: number;
+}
+/**
+ * Analyses design-token changes and reports which components / properties
+ * would be visually affected.
+ *
+ * @example
+ * ```ts
+ * const analyzer = new ImpactAnalyzer(resolver, complianceReports);
+ * const report = analyzer.impactOf("color.primary.500", "#2563EB");
+ * console.log(report.affectedComponentCount); // e.g. 4
+ * ```
+ */
+declare class ImpactAnalyzer {
+    private readonly resolver;
+    private readonly complianceReports;
+    /**
+     * @param resolver - The token resolver for the current token set
+     * @param complianceReports - Map of component name → ComplianceReport
+     *   (typically from ComplianceEngine.auditBatch)
+     */
+    constructor(resolver: TokenResolver, complianceReports: Map<string, ComplianceReport>);
+    /**
+     * Returns an ImpactReport describing the consequences of changing a token.
+     *
+     * @param tokenPath - Dot-notation path of the token to change
+     * @param newValue - The proposed new resolved value for the token
+     * @throws {Error} if the token does not exist in the resolver
+     */
+    impactOf(tokenPath: string, newValue: string): ImpactReport;
+}
+
+/**
+ * @agent-scope/tokens — Token file parser
+ *
+ * Parses reactscope.tokens.json or .yaml files into a flat, resolved Token[].
+ *
+ * Features:
+ * - JSON and YAML support (auto-detected)
+ * - Schema validation via validateTokenFile()
+ * - Reference resolution: {path.to.token} → resolved value
+ * - Circular reference detection via DFS with visited + inStack sets
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parses a token file (JSON or YAML) into a flat, resolved token array.
+ *
+ * @param input - The raw file contents as a string
+ * @param format - Force "json" or "yaml". If omitted, JSON is tried first,
+ *   then YAML as a fallback.
+ * @returns ParsedTokens — flat Token[] and the validated raw file
+ * @throws TokenParseError on reference errors or circular references
+ * @throws TokenValidationError on schema violations
+ */
+declare function parseTokenFile(input: string, format?: "json" | "yaml"): Promise<ParsedTokens>;
+/**
+ * Synchronous version of parseTokenFile. Only supports JSON format
+ * (YAML requires an async import). Throws if a YAML file is passed.
+ */
+declare function parseTokenFileSync(input: string): ParsedTokens;
+
+/**
+ * @agent-scope/tokens — Theme Support
+ *
+ * Extends the base token resolution with named theme overlays.
+ *
+ * Token files can declare themes in one of two formats:
+ *
+ *   (a) Flat override map (original format, as validated by validator.ts):
+ *       ```json
+ *       { "themes": { "dark": { "color.primary.500": "#60A5FA" } } }
+ *       ```
+ *
+ *   (b) Nested W3C DTCG-style tree (new structured format per spec):
+ *       ```json
+ *       {
+ *         "base": { "color": { "primary": { "500": { "$value": "#3B82F6" } } } },
+ *         "themes": {
+ *           "dark": { "color": { "primary": { "500": { "$value": "#60A5FA" } } } }
+ *         }
+ *       }
+ *       ```
+ *
+ * Theme resolution inherits all base tokens and only overrides specified paths.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extended token file format that supports named theme overlays.
+ * Compatible with both flat-override and nested-tree theme declarations.
+ */
+interface ThemedTokenFile {
+    $schema?: string;
+    version: string;
+    /** Base token tree — the default set every theme inherits from */
+    base?: Record<string, unknown>;
+    /** Standard `tokens` field (used when `base` is absent) */
+    tokens?: Record<string, unknown>;
+    /** Named theme overlays — each key is a theme name */
+    themes?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Extends TokenResolver with theme-aware resolution.
+ *
+ * Themes are layered on top of the base token set: a themed token resolver
+ * uses the same resolved values as the base resolver, but substitutes
+ * override values for any paths declared in the theme.
+ *
+ * @example
+ * ```ts
+ * const { tokens } = parseTokenFileSync(JSON.stringify(tokenFile));
+ * const resolver = new TokenResolver(tokens);
+ * const themeResolver = ThemeResolver.fromTokenFile(resolver, tokenFile);
+ *
+ * themeResolver.resolveThemed("color.primary.500", "dark"); // "#60A5FA"
+ * themeResolver.listThemes(); // ["dark", "brand-b"]
+ * themeResolver.resolveAllThemes("color.primary.500");
+ * // => { base: "#3B82F6", dark: "#60A5FA", "brand-b": "#8B5CF6" }
+ * ```
+ */
+declare class ThemeResolver {
+    private readonly baseResolver;
+    /** Parsed theme overrides: Map<themeName, Map<tokenPath, resolvedValue>> */
+    private readonly themes;
+    constructor(baseResolver: TokenResolver, themes: Map<string, Map<string, string>>);
+    /**
+     * Constructs a ThemeResolver from a TokenResolver and a raw token file object.
+     *
+     * Supports both the flat-override theme format and the nested DTCG-style
+     * format described in the module docstring.
+     */
+    static fromTokenFile(baseResolver: TokenResolver, rawFile: ThemedTokenFile): ThemeResolver;
+    /**
+     * Constructs a ThemeResolver from a TokenResolver and a pre-built
+     * themes map (for use when building programmatically).
+     */
+    static fromThemeMap(baseResolver: TokenResolver, themes: Map<string, Map<string, string>>): ThemeResolver;
+    /**
+     * Resolves a token path to its value in the given theme.
+     * Falls back to the base resolved value if the theme does not override
+     * the requested path.
+     *
+     * @throws {Error} if the token path is not found in the base resolver
+     * @throws {Error} if the theme name is not registered
+     */
+    resolveThemed(path: string, themeName: string): string;
+    /**
+     * Returns the names of all registered themes.
+     */
+    listThemes(): string[];
+    /**
+     * Returns the resolved value for the given token path in every theme,
+     * including the implicit "base" theme.
+     *
+     * Useful for parallel rendering comparisons (e.g. side-by-side theme preview).
+     *
+     * @throws {Error} if the token path is not found in the base resolver
+     */
+    resolveAllThemes(path: string): Record<string, string>;
+    /**
+     * Resolves a token path using the base (no theme) values.
+     * Delegates to the underlying TokenResolver.
+     */
+    resolve(path: string): string;
+    /**
+     * Lists all base tokens, optionally filtered by type and/or category.
+     * Delegates to the underlying TokenResolver.
+     */
+    list(type?: TokenType, category?: string): Token[];
+    /**
+     * Builds a Token[] for the given theme by merging overrides on top of the
+     * base token set.
+     *
+     * The returned tokens have their `resolvedValue` set to the theme value
+     * (or the base value when the theme does not override that path).
+     *
+     * @throws {Error} if the theme name is not registered
+     */
+    buildThemedTokens(themeName: string): Token[];
+}
+
+/**
+ * @agent-scope/tokens — Token file validator
+ *
+ * Validates a raw parsed JSON/YAML object against the token file schema.
+ * Collects all errors before throwing so callers get a complete picture.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Validates a raw parsed object and asserts it matches the `TokenFile` shape.
+ * Throws `TokenValidationError` with all collected issues if validation fails.
+ */
+declare function validateTokenFile(raw: unknown): asserts raw is TokenFile;
+
+export { type AffectedComponent, type BatchReport, ComplianceEngine, type ComplianceReport, type ComplianceStatus, type ComplianceTolerances, type ComputedStyles, type ExportFormat, type ExportOptions, ImpactAnalyzer, type ImpactReport, type ParsedTokens, type PropertyResult, TOKEN_TYPES, ThemeResolver, type ThemedTokenFile, type Token, type TokenFile, type TokenFileMeta, type TokenMatch, TokenParseError, type TokenParseErrorCode, TokenResolver, type TokenType, TokenValidationError, type TokenValue, type ValidationError, type VisualSeverity, exportTokens, hexToLab, labDistance, parseColorToLab, parseTokenFile, parseTokenFileSync, validateTokenFile };