dispersa 0.4.3 → 1.1.0

package/README.md

@@ -8,6 +8,7 @@ A TypeScript build system for processing [DTCG 2025.10](https://www.designtokens
 - **Multiple outputs** -- CSS custom properties, JSON, JS/TS modules
 - **Extensible pipeline** -- custom preprocessors, filters, transforms, and renderers
 - **Schema validation** -- AJV runtime validation with schema-generated TypeScript types
+- **Linting** -- Plugin-based lint rules for design token validation
 - **In-memory mode** -- use without the filesystem for build tools, APIs, and testing
 - **CLI** -- config-first workflow with auto-discovery
 
@@ -17,6 +18,23 @@ A TypeScript build system for processing [DTCG 2025.10](https://www.designtokens
 
 **Composite types:** `shadow`, `typography`, `border`, `strokeStyle`, `transition`, `gradient`
 
+## Linting
+
+Dispersa includes a plugin-based linting system to validate design tokens against semantic rules. Linting can run standalone or as part of the build pipeline.
+
+```typescript
+import { lint } from 'dispersa'
+import { dispersaPlugin, recommendedConfig } from 'dispersa/lint'
+
+const result = await lint({
+  resolver: './tokens.resolver.json',
+  ...recommendedConfig,
+})
+console.log(`Found ${result.errorCount} errors, ${result.warningCount} warnings`)
+```
+
+Built-in rules include `require-description`, `naming-convention`, `no-deprecated-usage`, `no-duplicate-values`, and `path-schema`. Create custom rules with the `createRule()` factory or build reusable plugins.
+
 ## Getting started
 
 ### New project
@@ -39,7 +57,7 @@ Define tokens inline and build CSS -- no files needed:
 
 ```typescript
 import type { ResolverDocument } from 'dispersa'
-import { Dispersa, css } from 'dispersa'
+import { build, css } from 'dispersa'
 import { colorToHex } from 'dispersa/transforms'
 
 const resolver: ResolverDocument = {
@@ -100,9 +118,11 @@ const resolver: ResolverDocument = {
   resolutionOrder: [{ $ref: '#/sets/base' }, { $ref: '#/modifiers/theme' }],
 }
 
-const dispersa = new Dispersa({ resolver })
+import { build, css } from 'dispersa'
+import { colorToHex } from 'dispersa/transforms'
 
-const result = await dispersa.build({
+const result = await build({
+  resolver,
   outputs: [
     css({
       name: 'css',
@@ -568,7 +588,7 @@ Dispersa can run entirely without the filesystem. Pass a `ResolverDocument` obje
 
 ```typescript
 import type { ResolverDocument } from 'dispersa'
-import { Dispersa, css } from 'dispersa'
+import { build, css } from 'dispersa'
 import { colorToHex } from 'dispersa/transforms'
 
 const resolver: ResolverDocument = {
@@ -590,9 +610,8 @@ const resolver: ResolverDocument = {
   resolutionOrder: [{ $ref: '#/sets/base' }],
 }
 
-const dispersa = new Dispersa({ resolver })
-
-const result = await dispersa.build({
+const result = await build({
+  resolver,
   outputs: [
     css({
       name: 'css',
@@ -734,43 +753,59 @@ export default defineConfig({
 
 ## API reference
 
-### `Dispersa` class
+### Core functions
+
+Dispersa provides standalone functions for all operations:
 
 ```typescript
-const dispersa = new Dispersa(options?: DispersaOptions)
+import {
+  build,
+  buildOrThrow,
+  buildPermutation,
+  resolveTokens,
+  lint,
+  resolveAllPermutations,
+  generateTypes,
+} from 'dispersa'
 ```
 
-**Constructor options:**
-
-| Option       | Type                                    | Description                                            |
-| ------------ | --------------------------------------- | ------------------------------------------------------ |
-| `resolver`   | `string \| ResolverDocument`            | Default resolver (file path or inline object)          |
-| `buildPath`  | `string`                                | Default output directory                               |
-| `validation` | `{ mode?: 'error' \| 'warn' \| 'off' }` | Validation behavior (`'warn'` logs via `console.warn`) |
-
-**Methods:**
-
-| Method                                      | Description                                           |
+| Function                                    | Description                                           |
 | ------------------------------------------- | ----------------------------------------------------- |
 | `build(config)`                             | Build tokens. Returns `BuildResult` (never throws).   |
 | `buildOrThrow(config)`                      | Build tokens. Throws on failure.                      |
 | `buildPermutation(config, modifierInputs?)` | Build a single permutation.                           |
 | `resolveTokens(resolver, modifierInputs?)`  | Resolve tokens for one permutation without rendering. |
+| `lint(options)`                             | Run lint rules on resolved tokens.                    |
 | `resolveAllPermutations(resolver)`          | Resolve tokens for every permutation.                 |
 | `generateTypes(tokens, fileName, options?)` | Generate a `.d.ts` file from resolved tokens.         |
 
+### BuildConfig
+
+When calling `build()` or `buildOrThrow()`, pass a `BuildConfig` object:
+
+| Option       | Type                                    | Description                           |
+| ------------ | --------------------------------------- | ------------------------------------- |
+| `resolver`   | `string \| ResolverDocument`            | Resolver (file path or inline object) |
+| `buildPath`  | `string`                                | Output directory                      |
+| `outputs`    | `OutputConfig[]`                        | Array of output configurations        |
+| `validation` | `{ mode?: 'error' \| 'warn' \| 'off' }` | Validation behavior                   |
+| `filters`    | `Filter[]`                              | Global filters                        |
+| `transforms` | `Transform[]`                           | Global transforms                     |
+| `lint`       | `LintBuildConfig`                       | Lint configuration                    |
+
 ### Subpath exports
 
-| Export                   | Description                                                                  |
-| ------------------------ | ---------------------------------------------------------------------------- |
-| `dispersa`               | `Dispersa` class, builder functions (`css`, `json`, `js`, `tailwind`), types |
-| `dispersa/transforms`    | Built-in transform factories                                                 |
-| `dispersa/filters`       | Built-in filter factories                                                    |
-| `dispersa/builders`      | Output builder functions                                                     |
-| `dispersa/renderers`     | Renderer types, `defineRenderer`, and `outputTree` helper                    |
-| `dispersa/preprocessors` | Preprocessor type                                                            |
-| `dispersa/errors`        | Error classes (`DispersaError`, `TokenReferenceError`, etc.)                 |
-| `dispersa/config`        | `defineConfig` helper for CLI config files                                   |
+| Export                   | Description                                                            |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `dispersa`               | Core functions (`build`, `lint`, etc.), builder functions, types       |
+| `dispersa/transforms`    | Built-in transform factories                                           |
+| `dispersa/filters`       | Built-in filter factories                                              |
+| `dispersa/builders`      | Output builder functions                                               |
+| `dispersa/renderers`     | Renderer types, `defineRenderer`, and `outputTree` helper              |
+| `dispersa/preprocessors` | Preprocessor type                                                      |
+| `dispersa/errors`        | Error classes (`DispersaError`, `TokenReferenceError`, etc.)           |
+| `dispersa/config`        | `defineConfig` helper for CLI config files                             |
+| `dispersa/lint`          | Linting system: `LintRunner`, built-in rules, `createRule`, formatters |
 
 Everything outside these entry points is internal and not a stable API contract.
 

package/dist/android-CRDfSB3_.d.cts

@@ -0,0 +1,126 @@
+import { S as SelectorFunction, M as MediaQueryFunction } from './index-De6SjZYH.cjs';
+
+/**
+ * @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;
+};
+
+export type { AndroidRendererOptions as A, IosRendererOptions as I, TailwindRendererOptions as T };

package/dist/android-DANJjjPO.d.ts

@@ -0,0 +1,126 @@
+import { S as SelectorFunction, M as MediaQueryFunction } from './index-Dajm5rvM.js';
+
+/**
+ * @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;
+};
+
+export type { AndroidRendererOptions as A, IosRendererOptions as I, TailwindRendererOptions as T };