dispersa 1.2.0 → 1.3.0

package/dist/index-Dajm5rvM.d.ts

@@ -1,895 +0,0 @@
-import { c as TokenType, L as InternalResolvedTokens, R as ResolvedToken, a as ResolvedTokens } from './types-TQHV1MrY.js';
-import { F as Filter } from './types-ebxDimRz.js';
-import { B as BuildConfigBase, O as OutputConfigBase, P as Preprocessor, D as DispersaOptionsBase } from './types-8MLtztK3.js';
-import { T as Transform } from './types-DztXKlka.js';
-
-/**
- * @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 DTCG Resolver types (2025.10 specification)
- *
- * The resolver system allows defining token sources, modifiers (themes, modes),
- * and the order in which they should be resolved and merged.
- *
- * ResolverDocument type is defined here to match DTCG 2025.10.
- */
-type ReferenceObject = {
-    $ref: string;
-};
-type TokenSource = ReferenceObject | Record<string, unknown>;
-type Set = {
-    sources: TokenSource[];
-    description?: string;
-    $extensions?: Record<string, unknown>;
-};
-type Modifier = {
-    contexts: Record<string, TokenSource[]>;
-    description?: string;
-    default?: string;
-    $extensions?: Record<string, unknown>;
-};
-type InlineSet = Set & {
-    name: string;
-    type: 'set';
-};
-type InlineModifier = Modifier & {
-    name: string;
-    type: 'modifier';
-};
-type ResolverDocument = {
-    $schema?: string;
-    name?: string;
-    version: '2025.10';
-    description?: string;
-    sets?: Record<string, Set>;
-    modifiers?: Record<string, Modifier>;
-    resolutionOrder: (ReferenceObject | InlineSet | InlineModifier)[];
-    $defs?: Record<string, unknown>;
-};
-/**
- * Map of modifier names to selected context values
- *
- * Used to specify which variation of each modifier to use when resolving tokens.
- * Can be made type-safe by providing a generic type parameter.
- *
- * @template T - Optional specific type for modifier values (defaults to generic Record)
- *
- * @example
- * ```typescript
- * // Generic (default):
- * const inputs: ModifierInputs = {
- *   theme: 'dark',
- *   platform: 'mobile'
- * }
- *
- * // Type-safe:
- * type MyModifiers = { theme: 'light' | 'dark', platform: 'web' | 'mobile' }
- * const inputs: ModifierInputs<MyModifiers> = {
- *   theme: 'dark',  // ✅ Autocomplete!
- *   platform: 'mobile'
- * }
- * ```
- */
-type ModifierInputs<T extends Record<string, string> = Record<string, string>> = T;
-
-/**
- * @fileoverview Renderer system types for token output generation
- *
- * Note: renderers/types and config have a mutual type-only dependency.
- * RenderContext references OutputConfig, while OutputConfig references
- * Renderer/FormatOptions. This is acceptable because type imports are
- * erased at runtime and the coupling is genuine.
- */
-
-/**
- * Generic options object for renderers
- *
- * Each renderer can define its own specific options that extend this base type.
- */
-type FormatOptions = Record<string, unknown>;
-/**
- * Data for a single permutation (combination of modifier values)
- */
-type PermutationData = {
-    tokens: ResolvedTokens;
-    modifierInputs: ModifierInputs;
-};
-/**
- * Metadata for renderers to reason about modifier dimensions.
- */
-type RenderMeta = {
-    dimensions: string[];
-    defaults: Record<string, string>;
-    basePermutation: ModifierInputs;
-};
-/**
- * Context provided to renderer formatters.
- */
-type RenderContext<TOptions extends FormatOptions = FormatOptions> = {
-    permutations: PermutationData[];
-    output: OutputConfig<TOptions>;
-    resolver: ResolverDocument;
-    meta: RenderMeta;
-    buildPath?: string;
-};
-/**
- * Multi-file output representation for renderers.
- */
-type OutputTree = {
-    kind: 'outputTree';
-    files: Record<string, string>;
-};
-type RenderOutput = string | OutputTree;
-/**
- * Output from a build operation
- */
-type BuildOutput = {
-    name: string;
-    /** File path where output was written (undefined for in-memory mode) */
-    path?: string;
-    content: string;
-};
-/**
- * Renderer definition for converting tokens to output format
- *
- * Renderers implement a single `format()` method that can return either
- * a single string or an OutputTree for multi-file outputs.
- *
- * @example Simple renderer with format()
- * ```typescript
- * const scssRenderer: Renderer = {
- *   format: (context) => {
- *     const tokens = context.permutations[0]?.tokens ?? {}
- *     return Object.entries(tokens)
- *       .map(([name, token]) => `$${name}: ${token.$value};`)
- *       .join('\n')
- *   },
- * }
- * ```
- */
-type Renderer<TOptions extends FormatOptions = FormatOptions> = {
-    /**
-     * Preset identifier (e.g., 'bundle', 'standalone', 'modifier')
-     * Indicates which variant of the renderer this is
-     */
-    preset?: string;
-    /**
-     * Convert tokens to output content.
-     *
-     * Renderers receive all resolved permutations and modifier metadata via context.
-     * They can return either a single string (single output file) or an OutputTree
-     * for multi-file outputs.
-     */
-    format: (context: RenderContext<TOptions>, options?: TOptions) => RenderOutput | Promise<RenderOutput>;
-};
-/**
- * Helper for defining custom renderers with full type inference.
- *
- * Works like Vue's `defineComponent()` or Vite's `defineConfig()` --
- * an identity function that enables TypeScript to infer the options type
- * from the generic parameter, giving you autocomplete and type-checking
- * on both `context` and `options` inside `format()`.
- *
- * @example
- * ```typescript
- * import { defineRenderer } from 'dispersa/renderers'
- *
- * type MyOptions = { prefix: string; minify?: boolean }
- *
- * const myRenderer = defineRenderer<MyOptions>({
- *   format(context, options) {
- *     // options is typed as MyOptions | undefined
- *     // context.output.options is typed as MyOptions | undefined
- *     const prefix = options?.prefix ?? 'token'
- *     return Object.entries(context.permutations[0]?.tokens ?? {})
- *       .map(([name, token]) => `${prefix}-${name}: ${token.$value}`)
- *       .join('\n')
- *   },
- * })
- * ```
- */
-declare function defineRenderer<T extends FormatOptions>(renderer: Renderer<T>): Renderer<T>;
-/**
- * Function type for dynamically generating CSS selectors based on modifier context
- *
- * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')
- * @param context - Context value of the modifier (e.g., 'dark', 'mobile')
- * @param isBase - Whether this is the base permutation
- * @param allModifierInputs - All modifier inputs for this permutation
- * @returns CSS selector string (e.g., '[data-theme="dark"]')
- */
-type SelectorFunction = (modifierName: string, context: string, isBase: boolean, allModifierInputs: Record<string, string>) => string;
-/**
- * Function type for dynamically generating media queries based on modifier context
- *
- * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')
- * @param context - Context value of the modifier (e.g., 'dark', 'mobile')
- * @param isBase - Whether this is the base permutation
- * @param allModifierInputs - All modifier inputs for this permutation
- * @returns Media query string (e.g., '(max-width: 768px)') or empty string for no media query
- */
-type MediaQueryFunction = (modifierName: string, context: string, isBase: boolean, allModifierInputs: Record<string, string>) => string;
-/**
- * Options for CSS custom properties renderer
- *
- * Controls how tokens are converted to CSS custom properties (CSS variables).
- *
- * **Note:** Token naming is controlled through transforms, not renderer options.
- * Use `nameKebabCase()` and `namePrefix()` for naming control.
- *
- * @example String-based selectors
- * ```typescript
- * css({
- *   name: 'tokens',
- *   file: 'tokens.css',
- *   transforms: [nameKebabCase(), namePrefix('ds-')],
- *   preset: 'bundle',
- *   selector: ':root',
- * })
- * ```
- *
- * @example Function-based selectors
- * ```typescript
- * outputs: [{
- *   renderer: cssRenderer(),
- *   options: {
- *     preset: 'bundle',
- *     selector: (modifier, context, isBase, allInputs) => {
- *       if (isBase) return ':root'
- *       return `[data-${modifier}="${context}"]`
- *     },
- *     mediaQuery: (modifier, context) => {
- *       if (modifier === 'breakpoint' && context === 'mobile') {
- *         return '(max-width: 768px)'
- *       }
- *       return ''
- *     }
- *   }
- * }]
- * ```
- */
-type CssRendererOptions = {
-    preset?: 'bundle' | 'standalone' | 'modifier';
-    selector?: string | SelectorFunction;
-    mediaQuery?: string | MediaQueryFunction;
-    minify?: boolean;
-    preserveReferences?: boolean;
-};
-
-/**
- * Result of a token build operation
- *
- * Contains success status, generated output files, and any errors encountered.
- *
- * @example
- * ```typescript
- * const result = await build(config)
- * if (result.success) {
- *   result.outputs.forEach(output => {
- *     console.log(`Generated ${output.name}: ${output.path}`)
- *   })
- * } else {
- *   console.error('Build errors:', result.errors)
- * }
- * ```
- */
-/**
- * Error code identifying the type of build error
- */
-type ErrorCode = 'TOKEN_REFERENCE' | 'CIRCULAR_REFERENCE' | 'VALIDATION' | 'FILE_OPERATION' | 'CONFIGURATION' | 'BASE_PERMUTATION' | 'MODIFIER' | 'UNKNOWN';
-/**
- * Structured error from a build operation
- *
- * Preserves typed context from the error hierarchy so consumers
- * can programmatically react to specific failure modes.
- */
-type BuildError = {
-    /** Human-readable error message */
-    message: string;
-    /** Machine-readable error code identifying the failure type */
-    code: ErrorCode;
-    /** File path where the error occurred (for file operation errors) */
-    path?: string;
-    /** Token path where the error occurred (e.g. 'color.primary') */
-    tokenPath?: string;
-    /** Error severity */
-    severity: 'error' | 'warning';
-    /** Suggested alternatives (e.g. similar token names for TOKEN_REFERENCE errors) */
-    suggestions?: string[];
-};
-type BuildResult = {
-    /** Whether the build completed successfully */
-    success: boolean;
-    /** Array of generated output files */
-    outputs: BuildOutput[];
-    /** Array of errors encountered during build (only present if success is false) */
-    errors?: BuildError[];
-};
-
-/**
- * @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;
-};
-
-/**
- * @fileoverview Configuration types for Dispersa
- *
- * Note: config and renderers/types have a mutual type-only dependency.
- * OutputConfig references Renderer/FormatOptions, while RenderContext
- * references OutputConfig. This is acceptable because type imports are
- * erased at runtime and the coupling is genuine (config describes how
- * to drive renderers).
- */
-
-/**
- * Lifecycle hooks for the build process.
- *
- * The same hook type is used on both `BuildConfig.hooks` (global) and
- * `OutputConfig.hooks` (per-output). All hooks are optional and support
- * both sync and async functions.
- *
- * **Execution order:**
- * 1. Global `onBuildStart`
- * 2. For each output: per-output `onBuildStart` → process → per-output `onBuildEnd`
- * 3. Global `onBuildEnd`
- */
-type LifecycleHooks = {
-    /** Called before permutation resolution and output processing begins */
-    onBuildStart?: (context: {
-        config: BuildConfig;
-        resolver: string | ResolverDocument;
-    }) => void | Promise<void>;
-    /** Called after all outputs have been processed (success or failure) */
-    onBuildEnd?: (result: BuildResult) => void | Promise<void>;
-};
-/**
- * Function that generates an output file path based on modifier inputs.
- *
- * Used as the `file` property on `OutputConfig` and builder configs when
- * the file name needs to vary per permutation.
- */
-type FileFunction = (modifierInputs: ModifierInputs) => string;
-/**
- * Output configuration for a single build target
- *
- * Defines how tokens should be formatted and output for a specific target
- * format (CSS, JSON, JavaScript, etc.).
- *
- * **Processing Order:**
- * - Global filters (from BuildConfig) are applied first to all outputs
- * - Then output-specific filters are applied (AND logic with global filters)
- * - Global transforms are applied next
- * - Finally output-specific transforms are applied
- *
- * **Output File Names:**
- * The `file` field supports subdirectories and dynamic naming patterns.
- * Parent directories are created automatically.
- *
- * @example Using builder helpers (recommended)
- * ```typescript
- * import { css, json } from 'dispersa'
- * import { colorToHex, dimensionToPx } from 'dispersa/transforms'
- *
- * // CSS output with transforms
- * css({
- *   name: 'css',
- *   file: 'css/tokens.css',
- *   preset: 'bundle',
- *   selector: ':root',
- *   transforms: [colorToHex(), dimensionToPx()],
- * })
- *
- * // JSON output with static filename
- * json({
- *   name: 'json',
- *   file: 'json/tokens.json',
- *   preset: 'standalone',
- *   structure: 'flat',
- * })
- * ```
- *
- * @example Pattern-based and function-based filenames
- * ```typescript
- * import { css } from 'dispersa'
- *
- * // Standalone mode with pattern-based filename
- * css({
- *   name: 'css-standalone',
- *   file: 'tokens-{theme}-{platform}.css', // → tokens-light-web.css, tokens-dark-mobile.css
- *   preset: 'standalone',
- *   selector: ':root',
- * })
- *
- * // Function-based filename
- * css({
- *   name: 'css-custom',
- *   preset: 'standalone',
- *   selector: ':root',
- *   file: (modifierInputs) => {
- *     const parts = Object.entries(modifierInputs).map(([k, v]) => `${k}-${v}`)
- *     return `tokens-${parts.join('-')}.css`
- *   },
- * })
- * ```
- *
- * @see CssRendererOptions
- * @see JsonRendererOptions
- * @see JsModuleRendererOptions
- */
-type OutputConfig<TOptions extends FormatOptions = FormatOptions> = Omit<OutputConfigBase, 'renderer' | 'transforms' | 'filters' | 'file'> & {
-    /** Renderer instance (created via renderer factory function) */
-    renderer: Renderer<TOptions>;
-    /**
-     * Array of filter objects to apply
-     * Filters are applied before transforms (to select which tokens to process)
-     */
-    filters?: Filter[];
-    /** Array of transform objects to apply */
-    transforms?: Transform[];
-    /**
-     * Output file path, can be static or dynamic
-     *
-     * Supports subdirectories (e.g., "css/tokens.css").
-     * In standalone preset (one file per permutation), supports:
-     * - Pattern strings with placeholders: `tokens-{theme}-{platform}.css`
-     * - Function that receives modifierInputs: `(modifierInputs) => \`tokens-${...}.css\``
-     * - Plain string (applies default pattern with all modifiers)
-     *
-     * @example
-     * ```typescript
-     * // Static filename (bundle preset or single permutation)
-     * file: 'tokens.css'
-     *
-     * // With subdirectory
-     * file: 'css/tokens.css'
-     *
-     * // Pattern with placeholders (standalone preset)
-     * file: 'tokens-{theme}-{platform}.css'
-     *
-     * // Function for complex logic (standalone preset)
-     * file: (modifierInputs) => {
-     *   const parts = Object.entries(modifierInputs).map(([k, v]) => `${k}-${v}`)
-     *   return `output/${parts.join('-')}/tokens.css`
-     * }
-     * ```
-     */
-    file?: string | FileFunction;
-    /**
-     * Renderer-specific options passed to the formatter.
-     */
-    options?: TOptions;
-    /**
-     * Lifecycle hooks for this output.
-     *
-     * Per-output hooks fire in addition to global hooks on BuildConfig.
-     * `onBuildStart` fires before this output is processed,
-     * `onBuildEnd` fires after this output finishes (success or failure).
-     */
-    hooks?: LifecycleHooks;
-};
-/**
- * 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;
-};
-
-export { type AnyLintRule as A, type BuildConfig as B, type CssRendererOptions as C, type DispersaOptions as D, type ErrorCode as E, type FileFunction as F, type LintOutputFormat as G, type RulesRegistry as H, type RuleConfigFor as I, type LifecycleHooks as L, type MediaQueryFunction as M, type OutputConfig as O, type PermutationData as P, type Renderer as R, type SelectorFunction as S, type TypedRulesConfig as T, type ValidationMode as V, type ValidationOptions as a, type BuildError as b, type BuildOutput as c, type BuildResult as d, type FormatOptions as e, type OutputTree as f, type RenderContext as g, type RenderMeta as h, type RenderOutput as i, type ModifierInputs as j, type ResolverDocument as k, defineRenderer as l, type LintConfig as m, type LintResult as n, type LintRule as o, type LintPlugin as p, type LintFormatter as q, type Severity as r, type LintRuleMeta as s, type LintRuleContext as t, type LintReportDescriptor as u, type RuleConfig as v, type ResolvedRuleConfig as w, type LintBuildConfig as x, type ResolvedLintConfig as y, type LintIssue as z };