dispersa 0.4.2 → 1.0.0

package/dist/{index-CNT2Meyf.d.cts → index-Dajm5rvM.d.ts}

@@ -1,7 +1,305 @@
-import { F as Filter } from './types-DWKq-eJj.cjs';
-import { B as BuildConfigBase, O as OutputConfigBase, P as Preprocessor, D as DispersaOptionsBase } from './types-CussyWwe.cjs';
-import { T as Transform } from './types-BAv39mum.cjs';
-import { R as ResolvedTokens } from './types-Bc0kA7De.cjs';
+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)
@@ -70,129 +368,6 @@ type ResolverDocument = {
  */
 type ModifierInputs<T extends Record<string, string> = Record<string, string>> = T;
 
-/**
- * @license MIT
- * Copyright (c) 2025-present Dispersa Contributors
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * Options for Tailwind CSS v4 renderer
- *
- * Controls how tokens are converted to Tailwind v4 @theme CSS variables.
- *
- * @example Bundle with dark mode overrides
- * ```typescript
- * tailwind({
- *   name: 'tailwind',
- *   file: 'theme.css',
- *   preset: 'bundle',
- *   selector: (modifier, context, isBase) => {
- *     if (isBase) return ':root'
- *     return `[data-${modifier}="${context}"]`
- *   },
- * })
- * ```
- */
-type TailwindRendererOptions = {
-    preset?: 'bundle' | 'standalone';
-    includeImport?: boolean;
-    namespace?: string;
-    minify?: boolean;
-    selector?: string | SelectorFunction;
-    mediaQuery?: string | MediaQueryFunction;
-};
-
-/**
- * @license MIT
- * Copyright (c) 2025-present Dispersa Contributors
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * Options for iOS/SwiftUI renderer
- */
-type IosRendererOptions = {
-    preset?: 'standalone';
-    accessLevel?: 'public' | 'internal';
-    /**
-     * Output structure:
-     * - `'enum'` — nested enums inside a single root enum
-     * - `'grouped'` — namespace enum with separate extensions per token group
-     */
-    structure?: 'enum' | 'grouped';
-    enumName?: string;
-    /** Namespace enum name used in grouped mode (default: 'DesignTokens') */
-    extensionNamespace?: string;
-    colorSpace?: 'sRGB' | 'displayP3';
-    /**
-     * Target Swift language version.
-     * - `'5.9'` (default) — standard static let declarations
-     * - `'6.0'` — adds `nonisolated(unsafe)` to static properties for
-     *   Swift 6 strict concurrency compliance
-     */
-    swiftVersion?: '5.9' | '6.0';
-    /** Number of spaces per indentation level (default 4) */
-    indent?: number;
-    /** Add @frozen annotation to enums and structs for ABI stability (default false) */
-    frozen?: boolean;
-};
-
-/**
- * @license MIT
- * Copyright (c) 2025-present Dispersa Contributors
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * Options for Android/Jetpack Compose renderer
- *
- * Note: `packageName` is marked optional for type compatibility with the Renderer
- * generic, but is validated as required at runtime in the renderer's format() method.
- *
- * @experimental This type is experimental. Properties and behavior may change.
- */
-type AndroidRendererOptions = {
-    preset?: 'standalone' | 'bundle';
-    packageName?: string;
-    objectName?: string;
-    /**
-     * Color output format for Kotlin Color initializers.
-     * - `'argb_hex'` (default) — `Color(0xAARRGGBB)` hex literal
-     * - `'argb_float'` — `Color(r, g, b, a)` float components
-     *
-     * Legacy aliases: `'argb8'` maps to `'argb_hex'`, `'argb_floats'` maps to `'argb_float'`.
-     */
-    colorFormat?: 'argb_hex' | 'argb_float' | 'argb8' | 'argb_floats';
-    /**
-     * Color space for generated Color values.
-     * - `'sRGB'` (default) — standard sRGB color space
-     * - `'displayP3'` — Display P3 wide gamut via `ColorSpaces.DisplayP3`
-     */
-    colorSpace?: 'sRGB' | 'displayP3';
-    /**
-     * Structure mode for token organization.
-     * - `'nested'` (default) — mirror token path hierarchy as nested objects
-     * - `'flat'` — group tokens by $type into semantic sub-objects (Colors, Spacing, etc.)
-     */
-    structure?: 'nested' | 'flat';
-    /**
-     * Kotlin visibility modifier for the generated object and its members.
-     * - `undefined` (default) — no explicit modifier, which means `public` in Kotlin
-     * - `'public'` — explicit `public object` / `public val`
-     * - `'internal'` — `internal object` / `internal val` (useful for KMP / multi-module)
-     */
-    visibility?: 'public' | 'internal';
-    /** Number of spaces per indentation level (default 4) */
-    indent?: number;
-};
-
 /**
  * @fileoverview Renderer system types for token output generation
  *
@@ -384,7 +559,7 @@ type CssRendererOptions = {
  *
  * @example
  * ```typescript
- * const result = await dispersa.build(config)
+ * const result = await build(config)
  * if (result.success) {
  *   result.outputs.forEach(output => {
  *     console.log(`Generated ${output.name}: ${output.path}`)
@@ -644,11 +819,11 @@ type OutputConfig<TOptions extends FormatOptions = FormatOptions> = Omit<OutputC
  *
  * @example Basic usage with global filters and transforms
  * ```typescript
- * import { Dispersa, css, json } from 'dispersa'
+ * import { build, css, json } from 'dispersa'
  * import { byType } from 'dispersa/filters'
  * import { colorToHex, nameKebabCase } from 'dispersa/transforms'
  *
- * await dispersa.build({
+ * await build({
  *   outputs: [
  *     css({ name: 'css', preset: 'bundle', selector: ':root' }),
  *     json({ name: 'json', preset: 'standalone', structure: 'flat' }),
@@ -664,7 +839,7 @@ type OutputConfig<TOptions extends FormatOptions = FormatOptions> = Omit<OutputC
  * import { byType } from 'dispersa/filters'
  * import { nameKebabCase } from 'dispersa/transforms'
  *
- * await dispersa.build({
+ * await build({
  *   outputs: [
  *     css({
  *       name: 'css',
@@ -687,6 +862,8 @@ type BuildConfig = Omit<BuildConfigBase, 'outputs' | 'filters' | 'transforms' |
     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 */
@@ -697,6 +874,8 @@ type BuildConfig = Omit<BuildConfigBase, 'outputs' | 'filters' | 'transforms' |
     preprocessors?: Preprocessor[];
     /** Explicit permutations to build (modifier inputs) */
     permutations?: ModifierInputs[];
+    /** Linting configuration */
+    lint?: LintBuildConfig;
     /** Global lifecycle hooks for the build process */
     hooks?: LifecycleHooks;
 };
@@ -713,4 +892,4 @@ type DispersaOptions = Omit<DispersaOptionsBase, 'validation'> & {
     validation?: ValidationOptions;
 };
 
-export { type AndroidRendererOptions as A, type BuildConfig as B, type CssRendererOptions as C, type DispersaOptions as D, type ErrorCode as E, type FileFunction as F, type IosRendererOptions as I, type LifecycleHooks as L, type ModifierInputs as M, type OutputConfig as O, type PermutationData as P, type ResolverDocument as R, type SelectorFunction as S, type TailwindRendererOptions as T, type ValidationMode as V, type BuildResult as a, type ValidationOptions as b, type BuildError as c, type BuildOutput as d, type FormatOptions as e, type MediaQueryFunction as f, type OutputTree as g, type Renderer as h, type RenderContext as i, type RenderMeta as j, type RenderOutput as k, defineRenderer as l };
+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 };