stablekit.ts 0.6.0 → 0.6.2

package/dist/stylelint.cjs

@@ -26,6 +26,8 @@ module.exports = __toCommonJS(stylelint_exports);
 var pluginRuleName = "stablekit/no-functional-in-utility";
 var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
 var duplicateRulesetRuleName = "stablekit/no-duplicate-ruleset";
+var nearDuplicateRuleName = "stablekit/no-near-duplicate-ruleset";
+var undefinedTokenRuleName = "stablekit/no-undefined-token";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
     return (root, result) => {
@@ -118,13 +120,112 @@ Declarations: ${fingerprint}`,
     rule
   };
 }
+function createNearDuplicatePlugin() {
+  function collectDirectDecls(ruleNode) {
+    const map = /* @__PURE__ */ new Map();
+    for (const child of ruleNode.nodes ?? []) {
+      if (child.type === "decl") {
+        map.set(child.prop, child.value);
+      } else if (child.type === "atrule" && child.name === "apply") {
+        map.set(`@apply`, child.params);
+      }
+    }
+    return map;
+  }
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const groups = /* @__PURE__ */ new Map();
+      root.walkRules((ruleNode) => {
+        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
+        const propMap = collectDirectDecls(ruleNode);
+        if (propMap.size < 2) return;
+        const propKey = [...propMap.keys()].sort().join(", ");
+        const entry = { selector: ruleNode.selector, propKey, propMap, node: ruleNode };
+        const group = groups.get(propKey);
+        if (group) {
+          for (const existing of group) {
+            let diffCount = 0;
+            let diffProp = "";
+            let diffOld = "";
+            let diffNew = "";
+            for (const [prop, value] of entry.propMap) {
+              const existingValue = existing.propMap.get(prop);
+              if (existingValue !== value) {
+                diffCount++;
+                diffProp = prop;
+                diffOld = existingValue ?? "(missing)";
+                diffNew = value;
+              }
+            }
+            if (diffCount === 0) continue;
+            if (diffCount === 1 && diffProp !== "@apply") {
+              result.warn(
+                `Near-duplicate ruleset \u2014 "${ruleNode.selector}" differs from "${existing.selector}" only in ${diffProp} (${diffOld} \u2192 ${diffNew}). Consider consolidating to a single class.`,
+                { node: ruleNode }
+              );
+              break;
+            }
+          }
+          group.push(entry);
+        } else {
+          groups.set(propKey, [entry]);
+        }
+      });
+    };
+  };
+  return {
+    ruleName: nearDuplicateRuleName,
+    rule
+  };
+}
+function createUndefinedTokenPlugin(runtimePrefixes) {
+  const varPattern = /var\(--([a-zA-Z0-9_-]+)/g;
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const defined = /* @__PURE__ */ new Set();
+      root.walkDecls((decl) => {
+        if (decl.prop.startsWith("--")) {
+          defined.add(decl.prop);
+        }
+      });
+      root.walkAtRules("theme", (atRule) => {
+        atRule.walkDecls((decl) => {
+          if (decl.prop.startsWith("--")) {
+            defined.add(decl.prop);
+          }
+        });
+      });
+      root.walkDecls((decl) => {
+        if (decl.prop.startsWith("--")) return;
+        let match;
+        varPattern.lastIndex = 0;
+        while ((match = varPattern.exec(decl.value)) !== null) {
+          const name = `--${match[1]}`;
+          if (defined.has(name)) continue;
+          if (runtimePrefixes.some((p) => name.startsWith(p))) continue;
+          result.warn(
+            `Reference to undefined custom property "${name}". This token is not defined anywhere in this file.`,
+            { node: decl }
+          );
+        }
+      });
+    };
+  };
+  return {
+    ruleName: undefinedTokenRuleName,
+    rule
+  };
+}
 function createStyleLint(options = {}) {
   const {
     ignoreTypes = ["html", "body"],
     functionalTokens = [],
+    runtimeTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin()];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createNearDuplicatePlugin(), createUndefinedTokenPlugin(runtimeTokens)];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -142,6 +243,10 @@ function createStyleLint(options = {}) {
     [descendantColorRuleName]: true,
     // Flag selectors with identical declarations for consolidation.
     [duplicateRulesetRuleName]: true,
+    // Flag near-duplicate rulesets (same props, differ by 1 value).
+    [nearDuplicateRuleName]: true,
+    // Flag var() references to custom properties not defined in this file.
+    [undefinedTokenRuleName]: true,
     // Ban animating layout properties — causes reflow on every frame.
     // Use transform (scaleY, translateY) or opacity instead.
     "declaration-property-value-disallowed-list": [

package/dist/stylelint.d.cts

@@ -40,6 +40,11 @@ interface StyleLintOptions {
      *  e.g. ["--color-status-", "--color-danger"]
      *  Any var() referencing these inside @utility is a lint error. */
     functionalTokens?: string[];
+    /** Custom property prefixes set at runtime (JS, Radix, inline styles)
+     *  that should not be flagged as undefined.
+     *  e.g. ["--radix-", "--bar-"]
+     *  @default [] */
+    runtimeTokens?: string[];
     /** Glob patterns for files to lint.
      *  @default ["src/**\/*.css"] */
     files?: string[];

package/dist/stylelint.d.ts

@@ -40,6 +40,11 @@ interface StyleLintOptions {
      *  e.g. ["--color-status-", "--color-danger"]
      *  Any var() referencing these inside @utility is a lint error. */
     functionalTokens?: string[];
+    /** Custom property prefixes set at runtime (JS, Radix, inline styles)
+     *  that should not be flagged as undefined.
+     *  e.g. ["--radix-", "--bar-"]
+     *  @default [] */
+    runtimeTokens?: string[];
     /** Glob patterns for files to lint.
      *  @default ["src/**\/*.css"] */
     files?: string[];

package/dist/stylelint.js

@@ -2,6 +2,8 @@
 var pluginRuleName = "stablekit/no-functional-in-utility";
 var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
 var duplicateRulesetRuleName = "stablekit/no-duplicate-ruleset";
+var nearDuplicateRuleName = "stablekit/no-near-duplicate-ruleset";
+var undefinedTokenRuleName = "stablekit/no-undefined-token";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
     return (root, result) => {
@@ -94,13 +96,112 @@ Declarations: ${fingerprint}`,
     rule
   };
 }
+function createNearDuplicatePlugin() {
+  function collectDirectDecls(ruleNode) {
+    const map = /* @__PURE__ */ new Map();
+    for (const child of ruleNode.nodes ?? []) {
+      if (child.type === "decl") {
+        map.set(child.prop, child.value);
+      } else if (child.type === "atrule" && child.name === "apply") {
+        map.set(`@apply`, child.params);
+      }
+    }
+    return map;
+  }
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const groups = /* @__PURE__ */ new Map();
+      root.walkRules((ruleNode) => {
+        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
+        const propMap = collectDirectDecls(ruleNode);
+        if (propMap.size < 2) return;
+        const propKey = [...propMap.keys()].sort().join(", ");
+        const entry = { selector: ruleNode.selector, propKey, propMap, node: ruleNode };
+        const group = groups.get(propKey);
+        if (group) {
+          for (const existing of group) {
+            let diffCount = 0;
+            let diffProp = "";
+            let diffOld = "";
+            let diffNew = "";
+            for (const [prop, value] of entry.propMap) {
+              const existingValue = existing.propMap.get(prop);
+              if (existingValue !== value) {
+                diffCount++;
+                diffProp = prop;
+                diffOld = existingValue ?? "(missing)";
+                diffNew = value;
+              }
+            }
+            if (diffCount === 0) continue;
+            if (diffCount === 1 && diffProp !== "@apply") {
+              result.warn(
+                `Near-duplicate ruleset \u2014 "${ruleNode.selector}" differs from "${existing.selector}" only in ${diffProp} (${diffOld} \u2192 ${diffNew}). Consider consolidating to a single class.`,
+                { node: ruleNode }
+              );
+              break;
+            }
+          }
+          group.push(entry);
+        } else {
+          groups.set(propKey, [entry]);
+        }
+      });
+    };
+  };
+  return {
+    ruleName: nearDuplicateRuleName,
+    rule
+  };
+}
+function createUndefinedTokenPlugin(runtimePrefixes) {
+  const varPattern = /var\(--([a-zA-Z0-9_-]+)/g;
+  const rule = (enabled) => {
+    return (root, result) => {
+      if (!enabled) return;
+      const defined = /* @__PURE__ */ new Set();
+      root.walkDecls((decl) => {
+        if (decl.prop.startsWith("--")) {
+          defined.add(decl.prop);
+        }
+      });
+      root.walkAtRules("theme", (atRule) => {
+        atRule.walkDecls((decl) => {
+          if (decl.prop.startsWith("--")) {
+            defined.add(decl.prop);
+          }
+        });
+      });
+      root.walkDecls((decl) => {
+        if (decl.prop.startsWith("--")) return;
+        let match;
+        varPattern.lastIndex = 0;
+        while ((match = varPattern.exec(decl.value)) !== null) {
+          const name = `--${match[1]}`;
+          if (defined.has(name)) continue;
+          if (runtimePrefixes.some((p) => name.startsWith(p))) continue;
+          result.warn(
+            `Reference to undefined custom property "${name}". This token is not defined anywhere in this file.`,
+            { node: decl }
+          );
+        }
+      });
+    };
+  };
+  return {
+    ruleName: undefinedTokenRuleName,
+    rule
+  };
+}
 function createStyleLint(options = {}) {
   const {
     ignoreTypes = ["html", "body"],
     functionalTokens = [],
+    runtimeTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin()];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createNearDuplicatePlugin(), createUndefinedTokenPlugin(runtimeTokens)];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -118,6 +219,10 @@ function createStyleLint(options = {}) {
     [descendantColorRuleName]: true,
     // Flag selectors with identical declarations for consolidation.
     [duplicateRulesetRuleName]: true,
+    // Flag near-duplicate rulesets (same props, differ by 1 value).
+    [nearDuplicateRuleName]: true,
+    // Flag var() references to custom properties not defined in this file.
+    [undefinedTokenRuleName]: true,
     // Ban animating layout properties — causes reflow on every frame.
     // Use transform (scaleY, translateY) or opacity instead.
     "declaration-property-value-disallowed-list": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stablekit.ts",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "React toolkit for layout stability — zero-shift components for loading states, content swaps, and spatial containers.",
   "type": "module",
   "main": "./dist/index.cjs",