dispersa 0.4.2 → 1.0.0

package/dist/lint.cjs

@@ -0,0 +1,1017 @@
+'use strict';
+
+var module$1 = require('module');
+var path = require('path');
+var process = require('process');
+var jiti = require('jiti');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var process__default = /*#__PURE__*/_interopDefault(process);
+
+// src/lint/create-rule.ts
+function createRule(rule) {
+  return rule;
+}
+
+// src/shared/errors/index.ts
+var DispersaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DispersaError";
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ConfigurationError = class extends DispersaError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+};
+var PluginLoader = class {
+  cwd;
+  jiti = null;
+  cache = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.cwd = options.cwd ?? process__default.default.cwd();
+  }
+  /**
+   * 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
+   */
+  async load(source) {
+    if (this.isPluginObject(source)) {
+      this.validatePlugin(source);
+      return source;
+    }
+    const modulePath = source;
+    const cached = this.cache.get(modulePath);
+    if (cached) {
+      return cached;
+    }
+    const plugin = await this.loadFromModule(modulePath);
+    this.validatePlugin(plugin);
+    this.cache.set(modulePath, plugin);
+    return plugin;
+  }
+  /**
+   * Load multiple plugins
+   *
+   * @param plugins - Record of namespace to plugin source
+   * @returns Record of namespace to loaded plugin
+   */
+  async loadAll(plugins) {
+    const entries = Object.entries(plugins);
+    const loaded = await Promise.all(
+      entries.map(async ([namespace, source]) => [namespace, await this.load(source)])
+    );
+    return Object.fromEntries(loaded);
+  }
+  /**
+   * Check if source is an inline plugin object
+   */
+  isPluginObject(source) {
+    return typeof source !== "string";
+  }
+  /**
+   * Load a plugin from a module path
+   */
+  async loadFromModule(modulePath) {
+    const resolvedPath = path.isAbsolute(modulePath) ? modulePath : path.resolve(this.cwd, modulePath);
+    const isFilePath = modulePath.startsWith("./") || modulePath.startsWith("../") || path.isAbsolute(modulePath);
+    try {
+      if (isFilePath) {
+        return await this.loadFromFile(resolvedPath);
+      }
+      return await this.loadFromPackage(modulePath);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ConfigurationError(`Failed to load lint plugin '${modulePath}': ${message}`);
+    }
+  }
+  /**
+   * Load a plugin from a file path using jiti (supports TypeScript)
+   */
+  async loadFromFile(filePath) {
+    this.jiti ??= jiti.createJiti(this.cwd, {
+      interopDefault: true
+    });
+    const loaded = await this.jiti(filePath);
+    const plugin = this.extractPlugin(loaded);
+    if (!plugin) {
+      throw new ConfigurationError(`Plugin file '${filePath}' does not export a valid LintPlugin`);
+    }
+    return plugin;
+  }
+  /**
+   * Load a plugin from a package name
+   */
+  async loadFromPackage(packageName) {
+    const require2 = module$1.createRequire(this.cwd);
+    let resolvedPath;
+    try {
+      resolvedPath = require2.resolve(packageName, { paths: [this.cwd] });
+    } catch {
+      try {
+        resolvedPath = require2.resolve(packageName);
+      } catch {
+        throw new ConfigurationError(
+          `Cannot find package '${packageName}'. Make sure it is installed.`
+        );
+      }
+    }
+    this.jiti ??= jiti.createJiti(this.cwd, {
+      interopDefault: true
+    });
+    const loaded = await this.jiti(resolvedPath);
+    const plugin = this.extractPlugin(loaded);
+    if (!plugin) {
+      throw new ConfigurationError(`Package '${packageName}' does not export a valid LintPlugin`);
+    }
+    return plugin;
+  }
+  /**
+   * Extract plugin from loaded module
+   *
+   * Supports multiple export patterns:
+   * - export default plugin
+   * - export const plugin = {...}
+   * - module.exports = plugin (CJS)
+   */
+  extractPlugin(loaded) {
+    if (!loaded || typeof loaded !== "object") {
+      return null;
+    }
+    const module = loaded;
+    if (module.default && this.isValidPluginStructure(module.default)) {
+      return module.default;
+    }
+    if (module.plugin && this.isValidPluginStructure(module.plugin)) {
+      return module.plugin;
+    }
+    if (this.isValidPluginStructure(loaded)) {
+      return loaded;
+    }
+    return null;
+  }
+  /**
+   * Check if object has required plugin structure
+   */
+  isValidPluginStructure(obj) {
+    if (!obj || typeof obj !== "object") {
+      return false;
+    }
+    const plugin = obj;
+    const rules = plugin.rules;
+    if (plugin.meta === void 0 || typeof plugin.meta !== "object" || !plugin.meta.name || rules === void 0 || Object.keys(rules).length === 0) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Validate a loaded plugin
+   */
+  validatePlugin(plugin) {
+    if (!plugin.meta) {
+      throw new ConfigurationError("Lint plugin must have a meta property with name");
+    }
+    if (!plugin.meta.name) {
+      throw new ConfigurationError("Lint plugin meta.name is required");
+    }
+    if (!plugin.rules || typeof plugin.rules !== "object" || Object.keys(plugin.rules).length === 0) {
+      throw new ConfigurationError(
+        `Lint plugin '${plugin.meta.name}' must have a non-empty rules object`
+      );
+    }
+    for (const [ruleName, rule] of Object.entries(plugin.rules)) {
+      if (!rule.meta) {
+        throw new ConfigurationError(
+          `Rule '${ruleName}' in plugin '${plugin.meta.name}' is missing meta property`
+        );
+      }
+      if (!rule.meta.messages || typeof rule.meta.messages !== "object") {
+        throw new ConfigurationError(
+          `Rule '${ruleName}' in plugin '${plugin.meta.name}' is missing meta.messages`
+        );
+      }
+      if (typeof rule.create !== "function") {
+        throw new ConfigurationError(
+          `Rule '${ruleName}' in plugin '${plugin.meta.name}' is missing create function`
+        );
+      }
+    }
+  }
+  /**
+   * Clear the plugin cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+};
+
+// src/lint/lint-runner.ts
+var LintRunner = class {
+  config;
+  pluginLoader;
+  resolvedConfig = null;
+  warn;
+  constructor(config) {
+    this.config = config;
+    this.pluginLoader = new PluginLoader();
+    this.warn = config.onWarn ?? console.warn;
+  }
+  /**
+   * 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
+   */
+  async run(tokens) {
+    this.resolvedConfig ??= await this.resolveConfig();
+    const { rules, plugins } = this.resolvedConfig;
+    const issues = [];
+    if (Object.keys(rules).length === 0) {
+      return { issues: [], errorCount: 0, warningCount: 0 };
+    }
+    const rulePromises = Object.entries(rules).map(async ([ruleId, ruleConfig]) => {
+      const { severity, options } = ruleConfig;
+      const rule = this.resolveRule(ruleId, plugins);
+      if (!rule) {
+        this.warn(`[lint] Unknown rule '${ruleId}' - no plugin provides this rule`);
+        return [];
+      }
+      const reports = [];
+      const applicableTokens = this.filterTokensByAppliesTo(tokens, rule.meta.appliesTo);
+      const mergedOptions = rule.defaultOptions ? { ...rule.defaultOptions, ...options } : options;
+      const context = {
+        id: ruleId,
+        options: mergedOptions,
+        tokens: applicableTokens,
+        report: (descriptor) => {
+          reports.push(descriptor);
+        }
+      };
+      try {
+        await rule.create(context);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return [
+          {
+            ruleId: "lint/rule-error",
+            severity: "error",
+            message: `Rule '${ruleId}' failed: ${message}`,
+            tokenName: "(rule execution)",
+            tokenPath: []
+          }
+        ];
+      }
+      return reports.map((report) => {
+        const messageTemplate = rule.meta.messages[report.messageId];
+        const message = messageTemplate ? this.interpolateMessage(messageTemplate, report.data) : report.messageId;
+        return {
+          ruleId,
+          severity,
+          message,
+          tokenName: report.token.name,
+          tokenPath: report.token.path
+        };
+      });
+    });
+    const allIssues = await Promise.all(rulePromises);
+    issues.push(...allIssues.flat());
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warningCount = issues.filter((i) => i.severity === "warn").length;
+    return { issues, errorCount, warningCount };
+  }
+  /**
+   * Resolve configuration: load plugins, parse rule configs
+   */
+  async resolveConfig() {
+    const { plugins: pluginSources = {}, rules: ruleConfigs = {} } = this.config;
+    const plugins = await this.pluginLoader.loadAll(pluginSources);
+    const rules = {};
+    for (const [ruleId, config] of Object.entries(ruleConfigs)) {
+      const resolved = this.resolveRuleConfig(config);
+      if (resolved) {
+        rules[ruleId] = resolved;
+      }
+    }
+    return {
+      enabled: true,
+      failOnError: this.config.failOnError ?? true,
+      plugins,
+      rules
+    };
+  }
+  filterTokensByAppliesTo(tokens, appliesTo) {
+    if (!appliesTo || appliesTo === "all") {
+      return tokens;
+    }
+    const filtered = {};
+    for (const [name, token] of Object.entries(tokens)) {
+      if (token.$type && appliesTo.includes(token.$type)) {
+        filtered[name] = token;
+      }
+    }
+    return filtered;
+  }
+  /**
+   * Parse rule configuration into resolved format
+   */
+  resolveRuleConfig(config) {
+    if (typeof config === "string") {
+      if (config === "off") {
+        return null;
+      }
+      return { severity: config, options: {} };
+    }
+    const [severity, options = {}] = config;
+    if (severity === "off") {
+      return null;
+    }
+    return { severity, options };
+  }
+  /**
+   * Resolve a rule from plugins by rule ID
+   *
+   * Rule IDs are formatted as 'namespace/rule-name'
+   */
+  resolveRule(ruleId, plugins) {
+    const separatorIndex = ruleId.indexOf("/");
+    if (separatorIndex === -1) {
+      return null;
+    }
+    const namespace = ruleId.slice(0, separatorIndex);
+    const ruleName = ruleId.slice(separatorIndex + 1);
+    const plugin = plugins[namespace];
+    if (!plugin) {
+      return null;
+    }
+    return plugin.rules[ruleName] ?? null;
+  }
+  /**
+   * Interpolate message template with data
+   *
+   * Replaces {{key}} placeholders with values from data
+   */
+  interpolateMessage(template, data) {
+    if (!data) {
+      return template;
+    }
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+      const value = data[key];
+      return value !== void 0 ? String(value) : `{{${key}}}`;
+    });
+  }
+  /**
+   * Clear the plugin cache
+   */
+  clearCache() {
+    this.pluginLoader.clearCache();
+    this.resolvedConfig = null;
+  }
+};
+
+// src/lint/utils/glob-matcher.ts
+var MAX_CACHE_SIZE = 1e3;
+var cache = /* @__PURE__ */ new Map();
+function globToRegex(pattern) {
+  const cached = cache.get(pattern);
+  if (cached) {
+    cache.delete(pattern);
+    cache.set(pattern, cached);
+    return cached;
+  }
+  const regex = new RegExp(
+    "^" + pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
+  );
+  if (cache.size >= MAX_CACHE_SIZE) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== void 0) {
+      cache.delete(oldest);
+    }
+  }
+  cache.set(pattern, regex);
+  return regex;
+}
+function matchesGlob(name, patterns) {
+  return patterns.some((pattern) => globToRegex(pattern).test(name));
+}
+
+// src/lint/utils/reference-extractor.ts
+var ALIAS_PATTERN = /\{([^}]+)\}/g;
+function extractReferences(value) {
+  const refs = [];
+  if (typeof value === "string") {
+    let match;
+    ALIAS_PATTERN.lastIndex = 0;
+    while ((match = ALIAS_PATTERN.exec(value)) !== null) {
+      if (match[1]) {
+        refs.push(match[1]);
+      }
+    }
+  } else if (Array.isArray(value)) {
+    for (const item of value) {
+      refs.push(...extractReferences(item));
+    }
+  } else if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value)) {
+      refs.push(...extractReferences(v));
+    }
+  }
+  return refs;
+}
+
+// src/lint/rules/naming-convention.ts
+var PATTERNS = {
+  "kebab-case": /^([a-z][a-z0-9]*)(-[a-z0-9]+)*$/,
+  camelCase: /^[a-z][a-zA-Z0-9]*$/,
+  PascalCase: /^[A-Z][a-zA-Z0-9]*$/,
+  snake_case: /^([a-z][a-z0-9]*)(_[a-z0-9]+)*$/,
+  "screaming-snake": /^([A-Z][A-Z0-9]*)(_[A-Z0-9]+)*$/
+};
+var DEFAULT_PATTERN = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
+var namingConvention = createRule({
+  meta: {
+    name: "naming-convention",
+    description: "Enforce consistent token naming conventions",
+    messages: {
+      INVALID_FORMAT: "Token '{{name}}' does not match '{{format}}' format",
+      INVALID_SEGMENT: "Segment '{{segment}}' in token '{{name}}' does not match '{{format}}' format"
+    }
+  },
+  defaultOptions: { format: "kebab-case", allowNumericSegments: true },
+  create({ tokens, options, report }) {
+    const format = options.format ?? "kebab-case";
+    const ignore = options.ignore ?? [];
+    const customPattern = options.pattern;
+    const allowNumericSegments = options.allowNumericSegments ?? true;
+    let segmentPattern;
+    if (customPattern) {
+      segmentPattern = new RegExp(customPattern);
+    } else {
+      segmentPattern = PATTERNS[format] ?? DEFAULT_PATTERN;
+    }
+    const numericPattern = /^\d+$/;
+    for (const token of Object.values(tokens)) {
+      if (ignore.length > 0 && matchesGlob(token.name, ignore)) {
+        continue;
+      }
+      const segments = token.path;
+      let hasError = false;
+      for (const segment of segments) {
+        if (allowNumericSegments && numericPattern.test(segment)) {
+          continue;
+        }
+        if (!segmentPattern.test(segment)) {
+          report({
+            token,
+            messageId: "INVALID_SEGMENT",
+            data: { name: token.name, segment, format: customPattern ?? format }
+          });
+          hasError = true;
+          break;
+        }
+      }
+      if (!hasError && customPattern && !segmentPattern.test(token.name)) {
+        report({
+          token,
+          messageId: "INVALID_FORMAT",
+          data: { name: token.name, format: customPattern }
+        });
+      }
+    }
+  }
+});
+
+// src/lint/rules/no-deprecated-usage.ts
+var noDeprecatedUsage = createRule({
+  meta: {
+    name: "no-deprecated-usage",
+    description: "Disallow references to deprecated tokens",
+    messages: {
+      REFERENCES_DEPRECATED: "Token '{{name}}' references deprecated token '{{ref}}'. {{reason}}"
+    }
+  },
+  defaultOptions: {},
+  create({ tokens, options, report }) {
+    const ignore = options.ignore ?? [];
+    const deprecatedTokens = /* @__PURE__ */ new Map();
+    for (const token of Object.values(tokens)) {
+      if (token.$deprecated) {
+        const reason = typeof token.$deprecated === "string" ? token.$deprecated : "";
+        deprecatedTokens.set(token.name, reason || true);
+      }
+    }
+    if (deprecatedTokens.size === 0) {
+      return;
+    }
+    for (const token of Object.values(tokens)) {
+      if (ignore.length > 0 && matchesGlob(token.name, ignore)) {
+        continue;
+      }
+      if (deprecatedTokens.has(token.name)) {
+        continue;
+      }
+      const refs = extractReferences(token.originalValue);
+      for (const ref of refs) {
+        const deprecation = deprecatedTokens.get(ref);
+        if (deprecation) {
+          const reason = deprecation === true ? "" : `(${deprecation})`;
+          report({
+            token,
+            messageId: "REFERENCES_DEPRECATED",
+            data: { name: token.name, ref, reason }
+          });
+        }
+      }
+    }
+  }
+});
+
+// src/lint/rules/no-duplicate-values.ts
+function valueKey(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (value === void 0) {
+    return "undefined";
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(sortKeys(value));
+  }
+  return String(value);
+}
+function sortKeys(obj) {
+  if (Array.isArray(obj)) {
+    return obj.map(sortKeys);
+  }
+  if (typeof obj === "object" && obj !== null) {
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = sortKeys(obj[key]);
+    }
+    return sorted;
+  }
+  return obj;
+}
+var noDuplicateValues = createRule({
+  meta: {
+    name: "no-duplicate-values",
+    description: "Detect tokens with duplicate values (excluding aliases)",
+    messages: {
+      DUPLICATE_VALUE: "Token '{{name}}' has the same value as '{{duplicate}}'. Consider using an alias instead."
+    }
+  },
+  defaultOptions: {},
+  create({ tokens, options, report }) {
+    const ignore = options.ignore ?? [];
+    const types = options.types;
+    const valueMap = /* @__PURE__ */ new Map();
+    for (const token of Object.values(tokens)) {
+      if (ignore.length > 0 && matchesGlob(token.name, ignore)) {
+        continue;
+      }
+      if (token._isAlias) {
+        continue;
+      }
+      if (types && types.length > 0 && !types.includes(token.$type ?? "")) {
+        continue;
+      }
+      const key = valueKey(token.$value);
+      const existing = valueMap.get(key);
+      if (existing) {
+        existing.push(token);
+      } else {
+        valueMap.set(key, [token]);
+      }
+    }
+    for (const tokenList of valueMap.values()) {
+      if (tokenList.length > 1) {
+        const first = tokenList[0];
+        if (!first) {
+          continue;
+        }
+        for (let i = 1; i < tokenList.length; i++) {
+          const current = tokenList[i];
+          if (current) {
+            report({
+              token: current,
+              messageId: "DUPLICATE_VALUE",
+              data: { name: current.name, duplicate: first.name }
+            });
+          }
+        }
+      }
+    }
+  }
+});
+
+// src/lint/rules/path-schema/matcher.ts
+var PathSchemaMatcher = class {
+  segments;
+  pathPatterns;
+  transitionRules;
+  constructor(config) {
+    this.segments = config.segments ?? {};
+    this.pathPatterns = this.compilePaths(config.paths ?? [], this.segments);
+    this.transitionRules = this.compileTransitions(config.transitions ?? []);
+  }
+  /**
+   * Validate a token against the schema
+   */
+  validate(token) {
+    const violations = [];
+    const pathSegments = token.path;
+    const hasPaths = this.pathPatterns.length > 0;
+    const hasTransitions = this.transitionRules.length > 0;
+    if (hasTransitions) {
+      const transitionViolations = this.validateTransitions(pathSegments, token.name);
+      violations.push(...transitionViolations);
+    }
+    if (hasPaths) {
+      const matchesAny = this.pathPatterns.some((p) => this.matchPattern(p, pathSegments));
+      if (!matchesAny) {
+        violations.push({
+          type: "INVALID_PATH",
+          data: { path: token.name }
+        });
+      }
+    }
+    return violations;
+  }
+  /**
+   * Validate transitions between segments.
+   *
+   * Deny rules are checked independently (any match = violation).
+   * Allow rules use OR semantics: at least one must match.
+   */
+  validateTransitions(segments, tokenName) {
+    const violations = [];
+    for (let i = 0; i < segments.length - 1; i++) {
+      const from = segments[i];
+      const to = segments[i + 1];
+      if (!from || !to) {
+        continue;
+      }
+      const applicableRules = this.transitionRules.filter((r) => this.matchesPattern(from, r.from));
+      if (applicableRules.length === 0) {
+        continue;
+      }
+      const denyRules = applicableRules.filter((r) => r.allow === false);
+      const allowRules = applicableRules.filter((r) => r.allow !== false);
+      for (const rule of denyRules) {
+        if (this.matchesPattern(to, rule.to)) {
+          violations.push({
+            type: "FORBIDDEN_TRANSITION",
+            data: { from, to, path: tokenName }
+          });
+        }
+      }
+      if (allowRules.length > 0) {
+        const anyAllowMatches = allowRules.some((r) => this.matchesPattern(to, r.to));
+        if (!anyAllowMatches) {
+          violations.push({
+            type: "FORBIDDEN_TRANSITION",
+            data: { from, to, path: tokenName }
+          });
+        }
+      }
+    }
+    return violations;
+  }
+  /**
+   * Check if a value matches a pattern
+   */
+  matchesPattern(value, pattern) {
+    if (typeof pattern === "string") {
+      return value === pattern;
+    }
+    if (Array.isArray(pattern)) {
+      return pattern.includes(value);
+    }
+    return pattern.test(value);
+  }
+  /**
+   * Compile path patterns into matcher structures
+   */
+  compilePaths(patterns, segments) {
+    return patterns.map((p) => this.parsePattern(p, segments));
+  }
+  /**
+   * Parse a path pattern string into compiled form
+   * - `{name}` is a segment placeholder
+   * - `*` is a wildcard that matches any single segment
+   * - `.` is the path separator (implicit between segments)
+   */
+  parsePattern(pattern, _segments) {
+    const parts = [];
+    const regex = /\{(\w+)\}|(\*)|([^{}*]+)/g;
+    let match;
+    while ((match = regex.exec(pattern)) !== null) {
+      if (match[1]) {
+        parts.push({ type: "segment", name: match[1] });
+      } else if (match[2]) {
+        parts.push({ type: "wildcard" });
+      } else if (match[3]) {
+        parts.push({ type: "literal", value: match[3] });
+      }
+    }
+    return parts;
+  }
+  /**
+   * Match path segments against a compiled pattern using dynamic programming.
+   * Supports optional segments via DP table.
+   *
+   * DP[i][j] = can we match path[0..i) with pattern[0..j)?
+   */
+  matchPattern(pattern, pathSegments) {
+    const patternParts = pattern.filter((p) => p.type === "segment" || p.type === "wildcard");
+    const pathLen = pathSegments.length;
+    const patternLen = patternParts.length;
+    const dp = [];
+    for (let i = 0; i <= pathLen; i++) {
+      dp[i] = [];
+      for (let j = 0; j <= patternLen; j++) {
+        dp[i][j] = false;
+      }
+    }
+    dp[0][0] = true;
+    for (let i = 0; i <= pathLen; i++) {
+      for (let j = 0; j <= patternLen; j++) {
+        const currentState = dp[i][j];
+        if (!currentState) {
+          continue;
+        }
+        if (i === pathLen) {
+          if (j < patternLen && this.isPartOptional(patternParts[j])) {
+            dp[i][j + 1] = true;
+          }
+          continue;
+        }
+        if (j === patternLen) {
+          if (i === pathLen) {
+            dp[i][j] = true;
+          }
+          continue;
+        }
+        const part = patternParts[j];
+        if (i < pathLen && this.matchPatternPart(part, pathSegments[i])) {
+          dp[i + 1][j + 1] = true;
+        }
+        if (this.isPartOptional(part)) {
+          dp[i][j + 1] = true;
+        }
+      }
+    }
+    return dp[pathLen][patternLen] ?? false;
+  }
+  /**
+   * Check if a pattern part is optional based on its segment definition
+   */
+  isPartOptional(part) {
+    if (part.type !== "segment" || !part.name) {
+      return false;
+    }
+    const segmentDef = this.segments[part.name];
+    return segmentDef?.optional ?? false;
+  }
+  /**
+   * Match a single pattern part against a path segment value
+   */
+  matchPatternPart(part, value) {
+    if (part.type === "wildcard") {
+      return true;
+    }
+    if (part.type === "segment" && part.name) {
+      const segment = this.segments[part.name];
+      if (!segment) {
+        return true;
+      }
+      return this.matchesSegmentDefinition(value, segment);
+    }
+    return false;
+  }
+  /**
+   * Check if a value matches a segment definition
+   */
+  matchesSegmentDefinition(value, definition) {
+    const { values } = definition;
+    if (Array.isArray(values)) {
+      return values.some((v) => typeof v === "string" ? v === value : v.test(value));
+    }
+    return values.test(value);
+  }
+  /**
+   * Compile transition rules
+   */
+  compileTransitions(transitions) {
+    return transitions.map((t) => ({
+      from: t.from,
+      to: t.to,
+      allow: t.allow ?? true
+    }));
+  }
+};
+
+// src/lint/rules/path-schema/index.ts
+var pathSchema = createRule({
+  meta: {
+    name: "path-schema",
+    description: "Enforce token path segment structure",
+    messages: {
+      INVALID_PATH: "Token path '{{path}}' does not match any defined pattern",
+      UNKNOWN_SEGMENT: "Segment '{{segment}}' at position {{position}} in '{{path}}' is not valid",
+      FORBIDDEN_TRANSITION: "Segment '{{to}}' cannot follow '{{from}}' in path '{{path}}'"
+    }
+  },
+  defaultOptions: {
+    segments: {},
+    paths: [],
+    transitions: []
+  },
+  create({ tokens, options, report }) {
+    const ignore = options.ignore ?? [];
+    if ((!options.paths || options.paths.length === 0) && (!options.transitions || options.transitions.length === 0)) {
+      return;
+    }
+    const matcher = new PathSchemaMatcher(options);
+    for (const token of Object.values(tokens)) {
+      if (ignore.length > 0 && matchesGlob(token.name, ignore)) {
+        continue;
+      }
+      const violations = matcher.validate(token);
+      for (const violation of violations) {
+        report({
+          token,
+          messageId: violation.type,
+          data: violation.data
+        });
+      }
+    }
+  }
+});
+
+// src/lint/rules/require-description.ts
+var requireDescription = createRule({
+  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: 1 },
+  create({ tokens, options, report }) {
+    const minLength = options.minLength ?? 1;
+    const ignore = options.ignore ?? [];
+    for (const token of Object.values(tokens)) {
+      if (ignore.length > 0 && matchesGlob(token.name, ignore)) {
+        continue;
+      }
+      if (!token.$description) {
+        report({
+          token,
+          messageId: "MISSING_DESCRIPTION",
+          data: { name: token.name }
+        });
+      } else if (token.$description.length < minLength) {
+        report({
+          token,
+          messageId: "TOO_SHORT",
+          data: {
+            name: token.name,
+            length: token.$description.length,
+            minLength
+          }
+        });
+      }
+    }
+  }
+});
+
+// src/lint/rules/index.ts
+function buildDispersaPlugin() {
+  const rules = {
+    "require-description": requireDescription,
+    "naming-convention": namingConvention,
+    "no-deprecated-usage": noDeprecatedUsage,
+    "no-duplicate-values": noDuplicateValues,
+    "path-schema": pathSchema
+  };
+  const plugin = { meta: { name: "dispersa" }, rules, configs: {} };
+  const recommended = {
+    plugins: { dispersa: plugin },
+    rules: {
+      "dispersa/require-description": "warn",
+      "dispersa/naming-convention": ["error", { format: "kebab-case" }],
+      "dispersa/no-deprecated-usage": "warn"
+    }
+  };
+  const strict = {
+    plugins: { dispersa: plugin },
+    rules: {
+      "dispersa/require-description": "error",
+      "dispersa/naming-convention": ["error", { format: "kebab-case" }],
+      "dispersa/no-deprecated-usage": "error",
+      "dispersa/no-duplicate-values": "error"
+    }
+  };
+  const minimal = {
+    plugins: { dispersa: plugin },
+    rules: {
+      "dispersa/no-deprecated-usage": "warn"
+    }
+  };
+  plugin.configs = { recommended, strict, minimal };
+  return { plugin, recommended, strict, minimal };
+}
+var {
+  plugin: dispersaPlugin,
+  recommended: recommendedConfig,
+  strict: strictConfig,
+  minimal: minimalConfig
+} = buildDispersaPlugin();
+
+// src/cli/formatters/lint-formatter.ts
+var formatLintJson = (result) => {
+  return JSON.stringify(result, null, 2);
+};
+var formatLintStylish = (result) => {
+  const lines = [];
+  if (result.issues.length === 0) {
+    return "\u2713 No lint issues found";
+  }
+  const byToken = /* @__PURE__ */ new Map();
+  for (const issue of result.issues) {
+    const existing = byToken.get(issue.tokenName) ?? [];
+    existing.push(issue);
+    byToken.set(issue.tokenName, existing);
+  }
+  for (const [tokenName, issues] of byToken) {
+    lines.push(``);
+    lines.push(`  ${tokenName}`);
+    for (const issue of issues) {
+      const severity = issue.severity === "error" ? "\u2716" : "\u26A0";
+      const label = issue.severity === "error" ? "error" : "warning";
+      lines.push(`    ${severity} ${label}: ${issue.message} [${issue.ruleId}]`);
+    }
+  }
+  lines.push(``);
+  if (result.errorCount > 0 || result.warningCount > 0) {
+    const parts = [];
+    if (result.errorCount > 0) {
+      parts.push(`${result.errorCount} error${result.errorCount === 1 ? "" : "s"}`);
+    }
+    if (result.warningCount > 0) {
+      parts.push(`${result.warningCount} warning${result.warningCount === 1 ? "" : "s"}`);
+    }
+    lines.push(`\u2716 ${parts.join(", ")}`);
+  }
+  return lines.join("\n");
+};
+var formatLintCompact = (result) => {
+  const lines = [];
+  for (const issue of result.issues) {
+    const severity = issue.severity.toUpperCase();
+    lines.push(`${severity}: ${issue.ruleId} - ${issue.message} (token: ${issue.tokenName})`);
+  }
+  if (result.errorCount > 0 || result.warningCount > 0) {
+    lines.push(`SUMMARY: ${result.errorCount} errors, ${result.warningCount} warnings`);
+  }
+  return lines.join("\n");
+};
+/**
+ * @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.
+ */
+
+exports.LintRunner = LintRunner;
+exports.PluginLoader = PluginLoader;
+exports.createRule = createRule;
+exports.dispersaPlugin = dispersaPlugin;
+exports.formatLintCompact = formatLintCompact;
+exports.formatLintJson = formatLintJson;
+exports.formatLintStylish = formatLintStylish;
+exports.minimalConfig = minimalConfig;
+exports.namingConvention = namingConvention;
+exports.noDeprecatedUsage = noDeprecatedUsage;
+exports.noDuplicateValues = noDuplicateValues;
+exports.pathSchema = pathSchema;
+exports.recommendedConfig = recommendedConfig;
+exports.requireDescription = requireDescription;
+exports.strictConfig = strictConfig;
+//# sourceMappingURL=lint.cjs.map
+//# sourceMappingURL=lint.cjs.map