dispersa 1.2.0 → 1.3.0

package/dist/dispersa-DJeCN0cP.d.cts

@@ -0,0 +1,567 @@
+import { c as TokenType, L as InternalResolvedTokens, R as ResolvedToken, a as ResolvedTokens } from './types-TQHV1MrY.cjs';
+import { F as Filter } from './types-CAdUV-fa.cjs';
+import { P as Preprocessor } from './types-DUc4vLZH.cjs';
+import { T as Transform } from './types-BltzwVYK.cjs';
+import { i as ResolverDocument, O as OutputConfig, h as ModifierInputs, L as LifecycleHooks, b as BuildResult } from './types-B0cI70Bt.cjs';
+import { B as BuildConfigBase, D as DispersaOptionsBase } from './config-schemas-DnEBhIg0.cjs';
+
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * @fileoverview Core type definitions for the Dispersa linting system
+ *
+ * Inspired by ESLint and Terrazzo, this system provides a plugin-based
+ * architecture for validating design tokens against semantic rules.
+ */
+
+/**
+ * Lint rule severity levels
+ *
+ * - `'off'` - Rule is disabled
+ * - `'warn'` - Rule issues warnings but doesn't fail the build
+ * - `'error'` - Rule issues errors and fails the build (if failOnError is true)
+ */
+type Severity = 'off' | 'warn' | 'error';
+/**
+ * Metadata describing a lint rule
+ *
+ * @template MessageIds - Union type of message IDs this rule can produce
+ */
+type LintRuleMeta<MessageIds extends string = string> = {
+    /** Short name of the rule (e.g., 'require-description') */
+    name: string;
+    /** Human-readable description of what the rule checks */
+    description: string;
+    /** Optional URL to documentation for this rule */
+    url?: string;
+    /** Map of message IDs to message templates (supports {{placeholder}} interpolation) */
+    messages: Record<MessageIds, string>;
+    /** Token types this rule applies to. Default: 'all' */
+    appliesTo?: TokenType[] | 'all';
+};
+/**
+ * Context object passed to rule's create() function
+ *
+ * Provides access to tokens, configuration, and the report function.
+ *
+ * @template MessageIds - Union type of message IDs this rule can produce
+ * @template Options - Rule-specific options type
+ */
+type LintRuleContext<MessageIds extends string = string, Options extends Record<string, unknown> = Record<string, never>> = {
+    /** Fully qualified rule ID (e.g., 'dispersa/require-description') */
+    id: string;
+    /** Merged options (defaultOptions + user config) */
+    options: Options;
+    /** All resolved tokens to validate */
+    tokens: InternalResolvedTokens;
+    /**
+     * Report a lint issue
+     *
+     * @param descriptor - Issue descriptor with token, message ID, and optional data
+     */
+    report(descriptor: LintReportDescriptor<MessageIds>): void;
+};
+/**
+ * Descriptor for reporting a lint issue
+ *
+ * @template MessageIds - Union type of message IDs this rule can produce
+ */
+type LintReportDescriptor<MessageIds extends string = string> = {
+    /** The token that has the issue */
+    token: ResolvedToken;
+    /** ID of the message to use from rule's meta.messages */
+    messageId: MessageIds;
+    /** Data to interpolate into the message (replaces {{key}} placeholders) */
+    data?: Record<string, string | number>;
+};
+/**
+ * A lint rule definition
+ *
+ * Rules are created using the `createRule()` factory function for type safety.
+ *
+ * @template MessageIds - Union type of message IDs this rule can produce
+ * @template Options - Rule-specific options type
+ *
+ * @example
+ * ```typescript
+ * const myRule: LintRule<'MISSING_VALUE', { required: boolean }> = {
+ *   meta: {
+ *     name: 'require-value',
+ *     description: 'Require tokens to have values',
+ *     messages: {
+ *       MISSING_VALUE: "Token '{{name}}' is missing a value",
+ *     },
+ *   },
+ *   defaultOptions: { required: true },
+ *   create({ tokens, report, options }) {
+ *     for (const token of Object.values(tokens)) {
+ *       if (options.required && !token.$value) {
+ *         report({ token, messageId: 'MISSING_VALUE', data: { name: token.name } })
+ *       }
+ *     }
+ *   },
+ * }
+ * ```
+ */
+type LintRule<MessageIds extends string = string, Options extends Record<string, unknown> = Record<string, never>> = {
+    /** Rule metadata */
+    meta: LintRuleMeta<MessageIds>;
+    /** Default options merged with user config */
+    defaultOptions?: Options;
+    /**
+     * Factory function that creates the rule's validation logic
+     *
+     * Called once per lint run with the context object.
+     *
+     * @param context - Rule context with tokens, options, and report function
+     */
+    create(context: LintRuleContext<MessageIds, Options>): void | Promise<void>;
+};
+/**
+ * Base rule type without generic parameters for use in plugin definitions
+ */
+type AnyLintRule = LintRule<string, Record<string, unknown>>;
+/**
+ * A lint plugin that provides rules and configurations
+ *
+ * @example
+ * ```typescript
+ * const myPlugin: LintPlugin = {
+ *   meta: {
+ *     name: 'my-lint-plugin',
+ *     version: '1.0.0',
+ *   },
+ *   rules: {
+ *     'my-rule': myRule,
+ *   },
+ *   configs: {
+ *     recommended: {
+ *       plugins: { my: myPlugin },
+ *       rules: {
+ *         'my/my-rule': 'warn',
+ *       },
+ *     },
+ *   },
+ * }
+ * ```
+ */
+type LintPlugin = {
+    /** Plugin metadata */
+    meta: {
+        /** Package name (e.g., '@dispersa/lint-plugin-a11y') */
+        name: string;
+        /** Semantic version (optional, for debugging/metadata) */
+        version?: string;
+    };
+    /** Rules provided by this plugin */
+    rules: Record<string, AnyLintRule>;
+    /** Predefined configurations */
+    configs?: Record<string, LintConfig>;
+};
+/**
+ * Rule configuration - either severity only or severity with options
+ *
+ * @example
+ * ```typescript
+ * // Severity only
+ * 'error'
+ *
+ * // Severity with options
+ * ['error', { format: 'kebab-case' }]
+ * ```
+ */
+type RuleConfig = Severity | [Severity, Record<string, unknown>];
+/**
+ * Resolved rule configuration with parsed severity and options
+ */
+type ResolvedRuleConfig = {
+    severity: Exclude<Severity, 'off'>;
+    options: Record<string, unknown>;
+};
+/**
+ * Registry for lint rule options types.
+ *
+ * Built-in dispersa rules are registered via declaration merging in `./rules/index.ts`.
+ * Plugin authors can augment this interface to add their own rule types:
+ *
+ * @example
+ * ```typescript
+ * // In your plugin file
+ * declare module 'dispersa/lint' {
+ *   interface RulesRegistry {
+ *     'my-plugin/my-rule': MyRuleOptions
+ *   }
+ * }
+ * ```
+ */
+interface RulesRegistry {
+}
+/**
+ * Type-safe configuration for a single rule from the registry.
+ *
+ * @template K - The rule ID key from RulesRegistry
+ */
+type RuleConfigFor<K extends keyof RulesRegistry> = Severity | [Severity, RulesRegistry[K]];
+/**
+ * Typed rules configuration with intellisense for all registered rules.
+ *
+ * Provides autocomplete for rule IDs and their option types.
+ * Also allows arbitrary string keys for unregistered rules.
+ */
+type TypedRulesConfig = {
+    [K in keyof RulesRegistry]?: RuleConfigFor<K>;
+} & Record<string, RuleConfig>;
+/**
+ * Lint configuration
+ *
+ * @template Rules - Rules configuration type (defaults to TypedRulesConfig for intellisense)
+ *
+ * @example
+ * ```typescript
+ * const config: LintConfig = {
+ *   plugins: {
+ *     dispersa: dispersaPlugin,
+ *     a11y: '@dispersa/lint-plugin-a11y', // Load by string
+ *   },
+ *   rules: {
+ *     'dispersa/require-description': 'warn',
+ *     'dispersa/naming-convention': ['error', { format: 'kebab-case' }],
+ *     'a11y/min-contrast': ['error', { level: 'AA' }],
+ *   },
+ * }
+ * ```
+ */
+type LintConfig<Rules extends Record<string, RuleConfig> = TypedRulesConfig> = {
+    /** Plugins to load (by object or module path string) */
+    plugins?: Record<string, LintPlugin | string>;
+    /** Rule configurations */
+    rules?: Rules;
+    /** Fail build on lint errors (default: true) */
+    failOnError?: boolean;
+};
+/**
+ * Configuration for lint within BuildConfig
+ *
+ * Extends {@link LintConfig} with an `enabled` toggle for opt-in build integration.
+ *
+ * @template Rules - Rules configuration type (defaults to TypedRulesConfig for intellisense)
+ */
+type LintBuildConfig<Rules extends Record<string, RuleConfig> = TypedRulesConfig> = LintConfig<Rules> & {
+    /** Enable linting (default: false, opt-in) */
+    enabled?: boolean;
+};
+/**
+ * Resolved lint configuration with all plugins loaded
+ */
+type ResolvedLintConfig = {
+    /** Whether linting is enabled */
+    enabled: boolean;
+    /** Fail build on errors */
+    failOnError: boolean;
+    /** Loaded plugins indexed by namespace */
+    plugins: Record<string, LintPlugin>;
+    /** Resolved rule configurations */
+    rules: Record<string, ResolvedRuleConfig>;
+};
+/**
+ * A single lint issue
+ */
+type LintIssue = {
+    /** Fully qualified rule ID (e.g., 'dispersa/require-description') */
+    ruleId: string;
+    /** Issue severity */
+    severity: Exclude<Severity, 'off'>;
+    /** Human-readable message */
+    message: string;
+    /** Token name (e.g., 'color.brand.primary') */
+    tokenName: string;
+    /** Token path segments (e.g., ['color', 'brand', 'primary']) */
+    tokenPath: string[];
+};
+/**
+ * Result of a lint run
+ */
+type LintResult = {
+    /** All issues found */
+    issues: LintIssue[];
+    /** Count of error-severity issues */
+    errorCount: number;
+    /** Count of warning-severity issues */
+    warningCount: number;
+};
+/**
+ * Output format for lint results
+ */
+type LintOutputFormat = 'json' | 'stylish' | 'compact';
+/**
+ * Formatter function that converts lint result to output string
+ */
+type LintFormatter = (result: LintResult) => string;
+
+/**
+ * @fileoverview Validation configuration types
+ */
+/** Controls how validation issues are reported */
+type ValidationMode = 'error' | 'warn' | 'off';
+/**
+ * Options that control token and resolver validation behavior.
+ *
+ * @example
+ * ```typescript
+ * const dispersa = new Dispersa({
+ *   validation: { mode: 'warn' },
+ * })
+ * ```
+ */
+type ValidationOptions = {
+    /**
+     * Validation mode.
+     * - `'error'` (default) – throw on validation failures
+     * - `'warn'` – log warnings via `console.warn` but continue processing
+     * - `'off'` – skip validation entirely
+     */
+    mode?: ValidationMode;
+};
+
+/**
+ * @license
+ * Copyright (c) 2025 Dispersa Contributors
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * @fileoverview Build orchestration types
+ *
+ * Contains types for build configuration, permutation handling, and
+ * build-time options. These types define how to drive the build process.
+ */
+
+/**
+ * Complete build configuration for Dispersa
+ *
+ * Defines all aspects of the token build process including input sources,
+ * output targets, transforms, and permutation handling.
+ *
+ * **Complete Token Processing Pipeline:**
+ *
+ * 1. **Preprocessors** (BuildConfig.preprocessors)
+ *    - Operate on raw JSON before parsing
+ *    - Transform raw data structures
+ *    - Example: strip custom metadata, inject env vars
+ *
+ * 2. **Parse & Resolve**
+ *    - Parse token files according to DTCG spec
+ *    - Resolve references between tokens
+ *    - Apply modifiers (themes, modes, etc.)
+ *    - Output: ResolvedTokens
+ *
+ * 3. **Global Filters** (BuildConfig.filters)
+ *    - Applied to all tokens for all outputs
+ *    - Example: exclude deprecated tokens globally
+ *
+ * 4. **Global Transforms** (BuildConfig.transforms)
+ *    - Applied to all tokens for all outputs
+ *    - Example: global naming conventions
+ *
+ * 5. **Per-Output Processing** (for each OutputConfig):
+ *    a. **Output Filters** - Select which tokens to include (AND logic)
+ *    b. **Output Transforms** - Modify selected tokens only
+ *    c. **Renderer** - Generate output format and bundle output
+ *
+ * All transforms and filters are applied in array order.
+ *
+ * @example Basic usage with global filters and transforms
+ * ```typescript
+ * import { build, css, json } from 'dispersa'
+ * import { byType } from 'dispersa/filters'
+ * import { colorToHex, nameKebabCase } from 'dispersa/transforms'
+ *
+ * await build({
+ *   outputs: [
+ *     css({ name: 'css', preset: 'bundle', selector: ':root' }),
+ *     json({ name: 'json', preset: 'standalone', structure: 'flat' }),
+ *   ],
+ *   filters: [byType('color')], // Global filter - only include color tokens for all outputs
+ *   transforms: [nameKebabCase(), colorToHex()], // Global transforms for all outputs
+ * })
+ * ```
+ *
+ * @example Combining global and output-specific filters
+ * ```typescript
+ * import { css, json } from 'dispersa'
+ * import { byType } from 'dispersa/filters'
+ * import { nameKebabCase } from 'dispersa/transforms'
+ *
+ * await build({
+ *   outputs: [
+ *     css({
+ *       name: 'css',
+ *       preset: 'bundle',
+ *       selector: ':root',
+ *     }),
+ *     json({
+ *       name: 'json',
+ *       preset: 'standalone',
+ *       structure: 'flat',
+ *     }),
+ *   ],
+ *   filters: [byType('color')],
+ *   transforms: [nameKebabCase()],
+ * })
+ * ```
+ */
+type BuildConfig = Omit<BuildConfigBase, 'outputs' | 'filters' | 'transforms' | 'preprocessors' | 'permutations'> & {
+    /** Resolver configuration - file path or inline ResolverDocument */
+    resolver?: string | ResolverDocument;
+    /** Output directory for generated files */
+    buildPath?: string;
+    /** Validation mode for token resolution */
+    validation?: ValidationOptions;
+    /** Array of output configurations defining target formats */
+    outputs: OutputConfig[];
+    /** Global filters to apply to all outputs before output-specific filters */
+    filters?: Filter[];
+    /** Global transforms to apply to all tokens before output-specific transforms */
+    transforms?: Transform[];
+    /** Global preprocessors to apply to raw token data before parsing */
+    preprocessors?: Preprocessor[];
+    /** Explicit permutations to build (modifier inputs) */
+    permutations?: ModifierInputs[];
+    /** Linting configuration */
+    lint?: LintBuildConfig;
+    /** Global lifecycle hooks for the build process */
+    hooks?: LifecycleHooks;
+};
+
+/**
+ * Dispersa options with runtime-only validation helpers
+ *
+ * Schema validation supports "validation.mode" but cannot validate functions.
+ */
+type DispersaOptions = Omit<DispersaOptionsBase, 'validation'> & {
+    /** Resolver configuration - file path or inline ResolverDocument */
+    resolver?: string | ResolverDocument;
+    /** Default output directory for generated files */
+    buildPath?: string;
+    validation?: ValidationOptions;
+};
+
+/**
+ * @license
+ * Copyright (c) 2025 Dispersa Contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * DTCG design token processor with multi-format output support
+ *
+ * Dispersa processes DTCG-compliant design tokens through a configurable pipeline,
+ * resolves references and aliases, applies transforms and filters, and generates output
+ * in multiple formats (CSS, JSON, JavaScript).
+ *
+ * **Runtime Validation:**
+ * All functions validate their configuration inputs at runtime, including build configs,
+ * output configs, and custom component registrations. This catches configuration errors
+ * early with helpful error messages.
+ *
+ * Features:
+ * - **Transforms**: Modify token values and names (e.g., convert colors, change case)
+ * - **Filters**: Select which tokens to include in output
+ * - **Preprocessors**: Transform raw token data before parsing
+ * - **Renderers**: Generate output in various formats
+ * - **Runtime validation**: JSON schema validation for all user inputs
+ *
+ * @example Basic build usage
+ * ```typescript
+ * import { build, css } from 'dispersa'
+ * import { nameKebabCase } from 'dispersa/transforms'
+ *
+ * const result = await build({
+ *   resolver: './tokens.resolver.json',
+ *   buildPath: './output',
+ *   outputs: [
+ *     css({
+ *       name: 'css',
+ *       file: 'tokens.css',
+ *       preset: 'bundle',
+ *       selector: ':root',
+ *       transforms: [nameKebabCase()]
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example Mixed presets per output
+ * ```typescript
+ * import { build, css, json } from 'dispersa'
+ *
+ * const result = await build({
+ *   resolver: './tokens.resolver.json',
+ *   buildPath: './output',
+ *   outputs: [
+ *     css({
+ *       name: 'css',
+ *       file: 'tokens.css',
+ *       preset: 'bundle',
+ *       selector: ':root',  // All themes in one CSS file
+ *       transforms: [nameKebabCase()]
+ *     }),
+ *     json({
+ *       name: 'json',
+ *       file: 'tokens-{theme}.json',  // Separate file per theme
+ *       preset: 'standalone',
+ *       structure: 'flat'
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example Using filters and preprocessors
+ * ```typescript
+ * import { build, css } from 'dispersa'
+ * import { byType } from 'dispersa/filters'
+ * import { nameKebabCase } from 'dispersa/transforms'
+ *
+ * const result = await build({
+ *   resolver: './tokens.resolver.json',
+ *   buildPath: './output',
+ *   outputs: [
+ *     css({
+ *       name: 'colors-only',
+ *       file: 'colors.css',
+ *       preset: 'standalone',
+ *       selector: ':root',
+ *       filters: [byType('color')],
+ *       transforms: [nameKebabCase()]
+ *     })
+ *   ],
+ *   permutations: [
+ *     { theme: 'light' },
+ *     { theme: 'dark' }
+ *   ]
+ * })
+ * ```
+ */
+declare function build(config: BuildConfig): Promise<BuildResult>;
+declare function buildOrThrow(config: BuildConfig): Promise<BuildResult>;
+declare function buildPermutation(config: BuildConfig, modifierInputs?: ModifierInputs): Promise<BuildResult>;
+declare function resolveTokens(resolver: string | ResolverDocument, modifierInputs?: ModifierInputs, validation?: ValidationOptions): Promise<ResolvedTokens>;
+type LintOptions = {
+    resolver: string | ResolverDocument;
+    modifierInputs?: ModifierInputs;
+    validation?: ValidationOptions;
+} & LintConfig;
+declare function lint(options: LintOptions): Promise<LintResult>;
+declare function resolveAllPermutations(resolver: string | ResolverDocument): Promise<{
+    tokens: ResolvedTokens;
+    modifierInputs: ModifierInputs;
+}[]>;
+declare function generateTypes(tokens: ResolvedTokens, fileName: string, options?: {
+    moduleName?: string;
+}): Promise<void>;
+
+export { type AnyLintRule as A, type BuildConfig as B, type DispersaOptions as D, type LintOptions as L, type RuleConfig as R, type Severity as S, type TypedRulesConfig as T, type ValidationMode as V, buildOrThrow as a, build as b, buildPermutation as c, resolveAllPermutations as d, type ValidationOptions as e, type LintRule as f, generateTypes as g, type LintConfig as h, type LintResult as i, type LintPlugin as j, type LintFormatter as k, lint as l, type LintRuleMeta as m, type LintRuleContext as n, type LintReportDescriptor as o, type ResolvedRuleConfig as p, type LintBuildConfig as q, resolveTokens as r, type ResolvedLintConfig as s, type LintIssue as t, type LintOutputFormat as u, type RulesRegistry as v, type RuleConfigFor as w };