dispersa 1.0.0 → 1.2.0

package/dist/index.cjs

@@ -191,8 +191,39 @@ function getPureAliasReferenceName(value) {
   const match = /^\{([^}]+)\}$/.exec(value);
   return match?.[1]?.trim();
 }
+function rewriteRootReferences(value) {
+  if (typeof value === "string") {
+    return ROOT_REF_PATTERN.test(value) ? value.replace(ROOT_REF_PATTERN, "}") : value;
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const mapped = value.map((item) => {
+      const rewritten = rewriteRootReferences(item);
+      if (rewritten !== item) {
+        changed = true;
+      }
+      return rewritten;
+    });
+    return changed ? mapped : value;
+  }
+  if (typeof value === "object" && value !== null) {
+    let changed = false;
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      const rewritten = rewriteRootReferences(v);
+      if (rewritten !== v) {
+        changed = true;
+      }
+      result[k] = rewritten;
+    }
+    return changed ? result : value;
+  }
+  return value;
+}
+var ROOT_REF_PATTERN;
 var init_token_utils = __esm({
   "src/shared/utils/token-utils.ts"() {
+    ROOT_REF_PATTERN = /\.\$root\}/g;
   }
 });
 
@@ -4177,9 +4208,12 @@ var BuildOrchestrator = class {
         resolver,
         config.transforms,
         config.preprocessors,
-        config.filters,
-        config.lint
+        config.filters
       );
+      if (config.lint?.enabled) {
+        const tokenSets = permutations2.map((p) => p.tokens);
+        await this.pipeline.runLintOnPermutations(tokenSets, config.lint);
+      }
       return this.executeBuild(buildPath, config, permutations2, resolver);
     }
     const permutations = await Promise.all(
@@ -4189,12 +4223,15 @@ var BuildOrchestrator = class {
           modifierInputs,
           config.transforms,
           config.preprocessors,
-          config.filters,
-          config.lint
+          config.filters
         );
         return { tokens, modifierInputs: resolvedInputs };
       })
     );
+    if (config.lint?.enabled) {
+      const tokenSets = permutations.map((p) => p.tokens);
+      await this.pipeline.runLintOnPermutations(tokenSets, config.lint);
+    }
     return this.executeBuild(buildPath, config, permutations, resolver);
   }
   /**
@@ -4802,6 +4839,34 @@ var LintRunner = class {
     this.pluginLoader.clearCache();
     this.resolvedConfig = null;
   }
+  /**
+   * Run lint on multiple token sets with deduplication
+   *
+   * When running lint across multiple permutations (e.g., light/dark themes),
+   * the same issue may appear multiple times. This method deduplicates issues
+   * by ruleId, tokenName, and message.
+   *
+   * Use this for both standalone lint and build lint to ensure identical output.
+   *
+   * @param tokenSets - Array of resolved token sets to lint
+   * @returns Combined lint result with deduplicated issues
+   */
+  async runMultiple(tokenSets) {
+    const results = await Promise.all(tokenSets.map((tokens) => this.run(tokens)));
+    const allIssues = results.flatMap((result) => result.issues);
+    const seen = /* @__PURE__ */ new Set();
+    const deduplicated = [];
+    for (const issue of allIssues) {
+      const key = `${issue.ruleId}:${issue.tokenName}:${issue.message}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        deduplicated.push(issue);
+      }
+    }
+    const errorCount = deduplicated.filter((i) => i.severity === "error").length;
+    const warningCount = deduplicated.filter((i) => i.severity === "warn").length;
+    return { issues: deduplicated, errorCount, warningCount };
+  }
 };
 
 // src/shared/constants.ts
@@ -5950,17 +6015,35 @@ var ResolutionEngine = class {
   /**
    * Merge two token objects (later values override earlier ones)
    */
-  mergeTokens(target, source) {
+  mergeTokens(target, source, path7 = []) {
     const result = { ...target };
     for (const [key, value] of Object.entries(source)) {
-      const isGroup = typeof value === "object" && value !== null && !Array.isArray(value) && !("$value" in value);
-      if (!isGroup) {
+      const currentPath = [...path7, key];
+      const isSourceGroup = typeof value === "object" && value !== null && !Array.isArray(value) && !("$value" in value);
+      const targetValue = target[key];
+      const isTargetGroup = typeof targetValue === "object" && targetValue !== null && !Array.isArray(targetValue) && !("$value" in targetValue);
+      if (targetValue !== void 0 && !key.startsWith("$")) {
+        if (isSourceGroup && !isTargetGroup) {
+          this.validationHandler.warn(
+            `Token '${currentPath.join(".")}' is being replaced by a group. This may cause loss of existing children.`
+          );
+        } else if (!isSourceGroup && isTargetGroup) {
+          const targetHasChildren = Object.keys(targetValue).some((k) => !k.startsWith("$"));
+          if (targetHasChildren) {
+            this.validationHandler.warn(
+              `Group '${currentPath.join(".")}' is being replaced by a token. Existing children will be lost.`
+            );
+          }
+        }
+      }
+      if (!isSourceGroup) {
         result[key] = value;
         continue;
       }
       result[key] = this.mergeTokens(
         result[key] ?? {},
-        value
+        value,
+        currentPath
       );
     }
     return result;
@@ -6000,6 +6083,7 @@ var ResolutionEngine = class {
 
 // src/build/pipeline/token-pipeline.ts
 init_errors();
+init_token_utils();
 init_validation_handler();
 init_errors();
 
@@ -6461,40 +6545,12 @@ var TokenParser = class {
 };
 
 // src/build/pipeline/token-pipeline.ts
-var ROOT_REF_PATTERN = /\.\$root\}/g;
-function rewriteRootReferences(value) {
-  if (typeof value === "string") {
-    return ROOT_REF_PATTERN.test(value) ? value.replace(ROOT_REF_PATTERN, "}") : value;
-  }
-  if (Array.isArray(value)) {
-    let changed = false;
-    const mapped = value.map((item) => {
-      const rewritten = rewriteRootReferences(item);
-      if (rewritten !== item) changed = true;
-      return rewritten;
-    });
-    return changed ? mapped : value;
-  }
-  if (typeof value === "object" && value !== null) {
-    let changed = false;
-    const result = {};
-    for (const [k, v] of Object.entries(value)) {
-      const rewritten = rewriteRootReferences(v);
-      if (rewritten !== v) changed = true;
-      result[k] = rewritten;
-    }
-    return changed ? result : value;
-  }
-  return value;
-}
 var TokenPipeline = class {
   options;
   validationHandler;
   resolverLoader;
   tokenParser;
   aliasResolver;
-  lintRunner = null;
-  lintConfigCache = null;
   constructor(options = {}) {
     this.options = options;
     this.validationHandler = new ValidationHandler(options.validation);
@@ -6514,22 +6570,22 @@ var TokenPipeline = class {
    * 6. Parse and flatten token structure
    * 7. Resolve alias references
    * 8. Strip $root from token names/paths (DTCG structural mechanism, transparent in output)
-   * 9. Run lint rules (if enabled)
-   * 10. Apply filters (if provided) — runs first to remove tokens before transforms
-   * 11. Apply transforms (if provided) — runs on the already-filtered token set
+   * 9. Apply filters (if provided) — runs first to remove tokens before transforms
+   * 10. Apply transforms (if provided) — runs on the already-filtered token set
    *
    * Each stage is explicitly typed to ensure correct order and prevent temporal coupling.
    *
+   * Note: Linting is handled separately via runLintOnPermutations() to enable
+   * deduplication across multiple permutations.
+   *
    * @param resolver - Either a file path (string) or an inline ResolverDocument object
    * @param modifierInputs - Modifier values for this permutation
    * @param transformList - Optional transforms to apply
    * @param preprocessorList - Optional preprocessors to apply
    * @param filterList - Optional filters to apply before transforms
-   * @param lintConfig - Optional lint configuration for this run
-   * @returns Final tokens, resolution engine, and lint result
+   * @returns Final tokens and resolution engine
    */
-  async resolve(resolver, modifierInputs, transformList, preprocessorList, filterList, lintConfig) {
-    const effectiveLintConfig = lintConfig ?? this.options.lint;
+  async resolve(resolver, modifierInputs, transformList, preprocessorList, filterList) {
     const stage1 = await this.loadResolver(resolver);
     const engine = this.createEngine(stage1);
     const result = await this.runPipelineStages(
@@ -6537,14 +6593,12 @@ var TokenPipeline = class {
       modifierInputs,
       preprocessorList,
       filterList,
-      transformList,
-      effectiveLintConfig
+      transformList
     );
     return {
       tokens: result.tokens,
       resolutionEngine: result.resolutionEngine,
-      modifierInputs: result.modifierInputs,
-      lintResult: result.lintResult
+      modifierInputs: result.modifierInputs
     };
   }
   /**
@@ -6554,15 +6608,14 @@ var TokenPipeline = class {
    * `resolveAllPermutations()` (parallel permutations) to keep the
    * stage sequence defined in exactly one place.
    */
-  async runPipelineStages(engine, modifierInputs, preprocessorList, filterList, transformList, lintConfig) {
+  async runPipelineStages(engine, modifierInputs, preprocessorList, filterList, transformList) {
     const rawTokens = await this.resolveTokens(engine, modifierInputs);
     const preprocessed = await this.preprocessTokens(rawTokens, preprocessorList);
     const refResolved = await this.resolveReferences(preprocessed);
     const flattened = this.flattenTokens(refResolved);
     const aliasResolved = this.resolveAliases(flattened);
     const rootStripped = this.stripRootTokenNames(aliasResolved);
-    const linted = await this.runLintStage(rootStripped, lintConfig);
-    const filtered = this.applyFilterStage(linted, filterList);
+    const filtered = this.applyFilterStage(rootStripped, filterList);
     return this.applyTransformStage(filtered, transformList);
   }
   /**
@@ -6676,45 +6729,8 @@ var TokenPipeline = class {
     return { ...stage, aliasResolvedTokens: result };
   }
   /**
-   * Stage 9: Run lint rules against tokens
-   *
-   * Linting runs after alias resolution and $root stripping but before
-   * filters and transforms. This ensures rules see the full token set
-   * with resolved values.
-   */
-  async runLintStage(stage, lintConfig) {
-    if (!lintConfig?.enabled) {
-      return stage;
-    }
-    if (!this.lintRunner || !this.isLintConfigEqual(this.lintConfigCache, lintConfig)) {
-      this.lintRunner = new LintRunner({
-        plugins: lintConfig.plugins,
-        rules: lintConfig.rules,
-        onWarn: (msg) => this.validationHandler.warn(msg)
-      });
-      this.lintConfigCache = lintConfig;
-    }
-    const lintResult = await this.lintRunner.run(stage.aliasResolvedTokens);
-    if (lintResult.errorCount > 0 && lintConfig.failOnError !== false) {
-      throw new exports.LintError(lintResult.issues);
-    }
-    for (const issue of lintResult.issues.filter((i) => i.severity === "warn")) {
-      this.validationHandler.warn(
-        `[${issue.ruleId}] ${issue.message} (token: ${issue.tokenName})`
-      );
-    }
-    return { ...stage, lintResult };
-  }
-  isLintConfigEqual(a, b) {
-    if (!a || !b) return false;
-    if (a.enabled !== b.enabled) return false;
-    if (a.failOnError !== b.failOnError) return false;
-    if (a.plugins !== b.plugins) return false;
-    if (a.rules !== b.rules) return false;
-    return true;
-  }
   /**
-   * Stage 10: Apply filters to the linted token set
+   * Stage 9: Apply filters to tokens after alias resolution and $root stripping
    */
   applyFilterStage(stage, filterList) {
     let tokens = stage.aliasResolvedTokens;
@@ -6724,7 +6740,7 @@ var TokenPipeline = class {
     return { ...stage, aliasResolvedTokens: tokens };
   }
   /**
-   * Stage 11: Apply transforms to the filtered token set
+   * Stage 10: Apply transforms to the filtered token set
    */
   applyTransformStage(stage, transformList) {
     let tokens = stage.aliasResolvedTokens;
@@ -6758,10 +6774,8 @@ var TokenPipeline = class {
    * @param transformList - Optional transforms to apply
    * @param preprocessorList - Optional preprocessors to apply
    * @param filterList - Optional filters to apply before transforms
-   * @param lintConfig - Optional lint configuration for this run
    */
-  async resolveAllPermutations(resolver, transformList, preprocessorList, filterList, lintConfig) {
-    const effectiveLintConfig = lintConfig ?? this.options.lint;
+  async resolveAllPermutations(resolver, transformList, preprocessorList, filterList) {
     const stage1 = await this.loadResolver(resolver);
     const discoveryEngine = this.createEngine(stage1);
     const permutationInputs = discoveryEngine.resolutionEngine.generatePermutations();
@@ -6774,17 +6788,39 @@ var TokenPipeline = class {
           modifierInputs,
           preprocessorList,
           filterList,
-          transformList,
-          effectiveLintConfig
+          transformList
         );
         return {
           tokens: result.tokens,
-          modifierInputs: result.modifierInputs,
-          lintResult: result.lintResult
+          modifierInputs: result.modifierInputs
         };
       })
     );
   }
+  /**
+   * Run lint on tokens from multiple permutations with deduplication
+   *
+   * This runs lint once on all permutation token sets combined and deduplicates
+   * issues. Use this after resolveAllPermutations() for consistent lint behavior.
+   */
+  async runLintOnPermutations(permutationTokens, lintConfig) {
+    if (!lintConfig.enabled) {
+      return { issues: [], errorCount: 0, warningCount: 0 };
+    }
+    const runner = new LintRunner({
+      plugins: lintConfig.plugins,
+      rules: lintConfig.rules,
+      onWarn: (msg) => this.validationHandler.warn(msg)
+    });
+    const result = await runner.runMultiple(permutationTokens);
+    for (const issue of result.issues.filter((i) => i.severity === "warn")) {
+      this.validationHandler.warn(`[${issue.ruleId}] ${issue.message} (token: ${issue.tokenName})`);
+    }
+    if (result.errorCount > 0 && lintConfig.failOnError !== false) {
+      throw new exports.LintError(result.issues);
+    }
+    return result;
+  }
   /**
    * Apply preprocessors to raw tokens
    */
@@ -6874,12 +6910,19 @@ async function resolveTokens(resolver, modifierInputs = {}, validation) {
 async function lint(options) {
   const { resolver, modifierInputs = {}, validation, ...lintConfig } = options;
   const pipeline = createPipeline({ validation });
-  const tokens = await resolvePipeline(pipeline, resolver, modifierInputs);
   const runner = new LintRunner({
     ...lintConfig,
     failOnError: lintConfig.failOnError ?? true
   });
-  const result = await runner.run(tokens);
+  let tokenSets;
+  if (Object.keys(modifierInputs).length > 0) {
+    const { tokens } = await pipeline.resolve(resolver, modifierInputs);
+    tokenSets = [tokens];
+  } else {
+    const permutations = await pipeline.resolveAllPermutations(resolver);
+    tokenSets = permutations.map((p) => p.tokens);
+  }
+  const result = await runner.runMultiple(tokenSets);
   if (result.errorCount > 0 && lintConfig.failOnError !== false) {
     throw new exports.LintError(result.issues);
   }