dispersa 0.4.2 → 1.0.0

package/dist/lint.d.cts

@@ -0,0 +1,463 @@
+import { o as LintRule, m as LintConfig, n as LintResult, p as LintPlugin, q as LintFormatter } from './index-De6SjZYH.cjs';
+export { A as AnyLintRule, x as LintBuildConfig, z as LintIssue, G as LintOutputFormat, u as LintReportDescriptor, t as LintRuleContext, s as LintRuleMeta, y as ResolvedLintConfig, w as ResolvedRuleConfig, v as RuleConfig, I as RuleConfigFor, H as RulesRegistry, r as Severity, T as TypedRulesConfig } from './index-De6SjZYH.cjs';
+export { L as LintOptions } from './dispersa-DL3J_Pmz.cjs';
+import { L as InternalResolvedTokens } from './types-TQHV1MrY.cjs';
+import './types-CAdUV-fa.cjs';
+import './types-BHBHRm0a.cjs';
+import 'json-schema-to-ts';
+import './types-BltzwVYK.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 Factory function for creating type-safe lint rules
+ *
+ * Use `createRule()` to define rules with full TypeScript inference
+ * for message IDs and options.
+ */
+
+/**
+ * Factory function for creating type-safe lint rules
+ *
+ * This function provides no runtime behavior - it simply returns the rule
+ * as-is. Its purpose is to provide type inference and autocomplete for
+ * message IDs and options.
+ *
+ * @template MessageIds - Union type of message IDs this rule can produce
+ * @template Options - Rule-specific options type
+ *
+ * @param rule - The rule definition
+ * @returns The same rule definition with full type inference
+ *
+ * @example
+ * ```typescript
+ * import { createRule } from 'dispersa/lint'
+ *
+ * export const requireDescription = createRule<
+ *   'MISSING_DESCRIPTION' | 'TOO_SHORT',
+ *   { minLength?: number }
+ * >({
+ *   meta: {
+ *     name: 'require-description',
+ *     description: 'Require tokens to have descriptions',
+ *     messages: {
+ *       MISSING_DESCRIPTION: "Token '{{name}}' is missing a description",
+ *       TOO_SHORT: "Token '{{name}}' description is too short ({{length}} chars, min {{minLength}})",
+ *     },
+ *   },
+ *   defaultOptions: { minLength: 10 },
+ *   create({ tokens, report, options }) {
+ *     for (const token of Object.values(tokens)) {
+ *       if (!token.$description) {
+ *         report({ token, messageId: 'MISSING_DESCRIPTION', data: { name: token.name } })
+ *       } else if (token.$description.length < options.minLength) {
+ *         report({
+ *           token,
+ *           messageId: 'TOO_SHORT',
+ *           data: { name: token.name, length: token.$description.length, minLength: options.minLength },
+ *         })
+ *       }
+ *     }
+ *   },
+ * })
+ * ```
+ */
+declare function createRule<MessageIds extends string, Options extends Record<string, unknown> = Record<string, never>>(rule: LintRule<MessageIds, Options>): LintRule<MessageIds, Options>;
+/**
+ * Helper type for extracting options type from a rule
+ *
+ * @example
+ * ```typescript
+ * const myRule = createRule<'MSG', { format: string }>({ ... })
+ * type MyOptions = RuleOptions<typeof myRule> // { format: string }
+ * ```
+ */
+type RuleOptions<T extends LintRule> = T extends LintRule<string, infer O> ? O : never;
+/**
+ * Helper type for extracting message IDs from a rule
+ *
+ * @example
+ * ```typescript
+ * const myRule = createRule<'MSG1' | 'MSG2', { format: string }>({ ... })
+ * type MyMessages = RuleMessages<typeof myRule> // 'MSG1' | 'MSG2'
+ * ```
+ */
+type RuleMessages<T extends LintRule> = T extends LintRule<infer M, Record<string, unknown>> ? M : never;
+
+/**
+ * @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 Lint runner that executes rules in parallel against tokens
+ *
+ * The lint runner is responsible for:
+ * - Loading plugins and resolving rule configurations
+ * - Executing rules in parallel for performance
+ * - Collecting and aggregating lint issues
+ * - Interpolating message templates with data
+ */
+
+type LintRunnerOptions = LintConfig & {
+    /** Callback for runner warnings (e.g. unknown rule). Defaults to console.warn. */
+    onWarn?: (message: string) => void;
+};
+/**
+ * Executes lint rules against a set of tokens
+ *
+ * @example
+ * ```typescript
+ * const config: LintConfig = {
+ *   plugins: {
+ *     dispersa: dispersaPlugin,
+ *   },
+ *   rules: {
+ *     'dispersa/require-description': 'warn',
+ *     'dispersa/naming-convention': ['error', { format: 'kebab-case' }],
+ *   },
+ * }
+ *
+ * const runner = new LintRunner(config)
+ * const result = await runner.run(tokens)
+ *
+ * console.log(`Found ${result.errorCount} errors, ${result.warningCount} warnings`)
+ * ```
+ */
+declare class LintRunner {
+    private config;
+    private pluginLoader;
+    private resolvedConfig;
+    private warn;
+    constructor(config: LintRunnerOptions);
+    /**
+     * Run all configured rules against the provided tokens
+     *
+     * Rules are executed in parallel for performance. Issues are collected
+     * and returned with counts by severity.
+     *
+     * @param tokens - Resolved tokens to lint
+     * @returns Lint result with issues and counts
+     */
+    run(tokens: InternalResolvedTokens): Promise<LintResult>;
+    /**
+     * Resolve configuration: load plugins, parse rule configs
+     */
+    private resolveConfig;
+    private filterTokensByAppliesTo;
+    /**
+     * Parse rule configuration into resolved format
+     */
+    private resolveRuleConfig;
+    /**
+     * Resolve a rule from plugins by rule ID
+     *
+     * Rule IDs are formatted as 'namespace/rule-name'
+     */
+    private resolveRule;
+    /**
+     * Interpolate message template with data
+     *
+     * Replaces {{key}} placeholders with values from data
+     */
+    private interpolateMessage;
+    /**
+     * Clear the plugin cache
+     */
+    clearCache(): void;
+}
+
+/**
+ * @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.
+ */
+
+type PluginLoaderOptions = {
+    /**
+     * Base directory for resolving relative plugin paths
+     * @default process.cwd()
+     */
+    cwd?: string;
+};
+/**
+ * Loads lint plugins from various sources
+ *
+ * Handles:
+ * - Inline `LintPlugin` objects (returned as-is)
+ * - Package names (e.g., '@dispersa/lint-plugin-a11y')
+ * - Relative file paths (e.g., './plugins/my-plugin.ts')
+ * - Absolute file paths
+ *
+ * @security **Warning**: Loading plugins from external packages or file paths
+ * executes arbitrary code. Only load plugins from trusted sources.
+ * For programmatic usage, prefer passing plugin objects directly rather than
+ * strings that trigger dynamic imports.
+ *
+ * @example
+ * ```typescript
+ * const loader = new PluginLoader({ cwd: process.cwd() })
+ *
+ * // Load from inline object
+ * const plugin1 = await loader.load(myPlugin)
+ *
+ * // Load from package
+ * const plugin2 = await loader.load('@dispersa/lint-plugin-a11y')
+ *
+ * // Load from file
+ * const plugin3 = await loader.load('./plugins/custom.ts')
+ * ```
+ */
+declare class PluginLoader {
+    private cwd;
+    private jiti;
+    private cache;
+    constructor(options?: PluginLoaderOptions);
+    /**
+     * Load a plugin from an inline object or module path
+     *
+     * @param source - Plugin object or module path string
+     * @returns Loaded plugin
+     * @throws {ConfigurationError} If plugin cannot be loaded or is invalid
+     */
+    load(source: LintPlugin | string): Promise<LintPlugin>;
+    /**
+     * Load multiple plugins
+     *
+     * @param plugins - Record of namespace to plugin source
+     * @returns Record of namespace to loaded plugin
+     */
+    loadAll(plugins: Record<string, LintPlugin | string>): Promise<Record<string, LintPlugin>>;
+    /**
+     * Check if source is an inline plugin object
+     */
+    private isPluginObject;
+    /**
+     * Load a plugin from a module path
+     */
+    private loadFromModule;
+    /**
+     * Load a plugin from a file path using jiti (supports TypeScript)
+     */
+    private loadFromFile;
+    /**
+     * Load a plugin from a package name
+     */
+    private loadFromPackage;
+    /**
+     * Extract plugin from loaded module
+     *
+     * Supports multiple export patterns:
+     * - export default plugin
+     * - export const plugin = {...}
+     * - module.exports = plugin (CJS)
+     */
+    private extractPlugin;
+    /**
+     * Check if object has required plugin structure
+     */
+    private isValidPluginStructure;
+    /**
+     * Validate a loaded plugin
+     */
+    private validatePlugin;
+    /**
+     * Clear the plugin cache
+     */
+    clearCache(): void;
+}
+
+type NamingConventionOptions = {
+    /**
+     * Naming format to enforce
+     * - 'kebab-case': color-brand-primary, red-500, blue-600
+     * - 'camelCase': colorBrandPrimary
+     * - 'PascalCase': ColorBrandPrimary
+     * - 'snake_case': color_brand_primary
+     * - 'screaming-snake': COLOR_BRAND_PRIMARY
+     */
+    format?: 'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case' | 'screaming-snake';
+    /** Token name patterns to ignore (glob patterns) */
+    ignore?: string[];
+    /** Custom regex pattern to validate against */
+    pattern?: string;
+    /**
+     * Allow purely numeric path segments (e.g., spacing.0, spacing.1)
+     * Common in design system scales. Default: true
+     */
+    allowNumericSegments?: boolean;
+};
+declare const namingConvention: LintRule<"INVALID_FORMAT" | "INVALID_SEGMENT", NamingConventionOptions>;
+
+type NoDeprecatedUsageOptions = {
+    /** Token name patterns to ignore (glob patterns) */
+    ignore?: string[];
+};
+declare const noDeprecatedUsage: LintRule<"REFERENCES_DEPRECATED", NoDeprecatedUsageOptions>;
+
+type NoDuplicateValuesOptions = {
+    /** Token name patterns to ignore (glob patterns) */
+    ignore?: string[];
+    /** Only check specific token types */
+    types?: string[];
+};
+declare const noDuplicateValues: LintRule<"DUPLICATE_VALUE", NoDuplicateValuesOptions>;
+
+/**
+ * @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 Types for path-schema rule
+ */
+/**
+ * Definition of a named path segment
+ */
+type SegmentDefinition = {
+    /** Allowed values (array of strings or regex pattern, or single regex) */
+    values: string[] | RegExp | Array<string | RegExp>;
+    /** Human-readable description */
+    description?: string;
+    /** Whether this segment is optional */
+    optional?: boolean;
+};
+/**
+ * Transition rule for context-aware segment validation
+ */
+type TransitionRule = {
+    /** Segment value or pattern to match (from) */
+    from: string | string[] | RegExp;
+    /** Allowed/forbidden segment values or patterns (to) */
+    to: string | string[] | RegExp;
+    /** Whether transition is allowed. Default: true */
+    allow?: boolean;
+};
+/**
+ * Path pattern (string with {segment} placeholders)
+ */
+type PathPattern = string;
+/**
+ * Configuration for path-schema rule
+ */
+type PathSchemaConfig = {
+    /**
+     * Named segment definitions.
+     * Maps segment name to allowed values/description.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   domain: { values: ['color', 'spacing'], description: 'Token domain' },
+     *   layer: { values: ['base', 'semantic', 'component'] },
+     *   scale: { values: ['xs', 'sm', 'md', 'lg', 'xl'] },
+     *   brand: { values: /^[a-z]+$/, description: 'Brand name' },
+     * }
+     * ```
+     */
+    segments?: Record<string, SegmentDefinition>;
+    /**
+     * Valid path patterns using {segment} placeholders.
+     *
+     * @example
+     * ```typescript
+     * [
+     *   'color.base.{brand}',
+     *   'color.semantic.{element}.{role}',
+     *   'color.component.{component}.{element}.{state}',
+     * ]
+     * ```
+     */
+    paths?: PathPattern[];
+    /**
+     * Context-aware transition rules.
+     * Alternative to patterns - define which segments can follow which.
+     *
+     * @example
+     * ```typescript
+     * [
+     *   { from: 'color', to: ['base', 'semantic', 'component'] },
+     *   { from: 'semantic', to: ['text', 'bg', 'border'] },
+     *   { from: 'semantic', to: 'component', allow: false },
+     * ]
+     * ```
+     */
+    transitions?: TransitionRule[];
+    /**
+     * Token name patterns to ignore (glob patterns)
+     */
+    ignore?: string[];
+};
+
+declare const pathSchema: LintRule<"INVALID_PATH" | "UNKNOWN_SEGMENT" | "FORBIDDEN_TRANSITION", PathSchemaConfig>;
+
+type RequireDescriptionOptions = {
+    /** Minimum length for description. Default: 1 */
+    minLength?: number;
+    /** Token name patterns to ignore (glob patterns) */
+    ignore?: string[];
+};
+declare const requireDescription: LintRule<"MISSING_DESCRIPTION" | "TOO_SHORT", RequireDescriptionOptions>;
+
+/**
+ * @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 Built-in lint rules and dispersa plugin
+ */
+
+declare const dispersaPlugin: LintPlugin;
+declare const recommendedConfig: LintConfig;
+declare const strictConfig: LintConfig;
+declare const minimalConfig: LintConfig;
+
+declare module '../types' {
+    interface RulesRegistry {
+        'dispersa/require-description': RequireDescriptionOptions;
+        'dispersa/naming-convention': NamingConventionOptions;
+        'dispersa/no-deprecated-usage': NoDeprecatedUsageOptions;
+        'dispersa/no-duplicate-values': NoDuplicateValuesOptions;
+        'dispersa/path-schema': PathSchemaConfig;
+    }
+}
+
+/**
+ * @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 Lint output formatter interface and utilities
+ */
+
+/**
+ * Format lint results as JSON
+ */
+declare const formatLintJson: LintFormatter;
+/**
+ * Format lint results in a human-readable stylish format
+ */
+declare const formatLintStylish: LintFormatter;
+/**
+ * Format lint results for CI output (compact, parseable)
+ */
+declare const formatLintCompact: LintFormatter;
+
+export { LintConfig, LintFormatter, LintPlugin, LintResult, LintRule, LintRunner, type LintRunnerOptions, type NamingConventionOptions, type NoDeprecatedUsageOptions, type NoDuplicateValuesOptions, type PathSchemaConfig, PluginLoader, type PluginLoaderOptions, type RequireDescriptionOptions, type RuleMessages, type RuleOptions, type SegmentDefinition, type TransitionRule, createRule, dispersaPlugin, formatLintCompact, formatLintJson, formatLintStylish, minimalConfig, namingConvention, noDeprecatedUsage, noDuplicateValues, pathSchema, recommendedConfig, requireDescription, strictConfig };