stylelint-plugin-rhythmguard 2.1.0 → 3.0.0

package/src/rules/use-scale/index.js

@@ -5,6 +5,7 @@ const valueParser = require('postcss-value-parser');
 const {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,
@@ -29,13 +30,19 @@ const {
   walkTransformTranslateNodes,
 } = require('../../utils/value-utils');
 
+const {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  autoScaleFallbackNote,
+  resolveAutoScale,
+} = require('../../utils/scale-inference');
+
 const ruleName = 'rhythmguard/use-scale';
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, lower, upper) =>
-    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).`,
+  rejected: (value, lower, upper, note = '') =>
+    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
 function getFixedNodeValue(parsedLength, nearestPx, options) {
@@ -82,7 +89,16 @@ function checkLengthValue({
     return false;
   }
 
-  if (parsedLength.unit === '%' && options.allowPercentages) {
+  if (parsedLength.unit === '%') {
+    if (options.allowPercentages) {
+      return false;
+    }
+
+    report(node.value, decl, node, null, null, '%');
+    return false;
+  }
+
+  if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
     return false;
   }
 
@@ -180,8 +196,21 @@ const ruleFunction = (primary, secondaryOptions) => {
       });
     }
 
+    if (options.scaleAuto) {
+      const inference = resolveAutoScale({
+        baseFontSize: options.baseFontSize,
+        root,
+        scaleSources: options.scaleSources,
+        tailwindConfigPath: options.tailwindConfigPath,
+        tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
+      });
+      options.scale = inference.scale;
+      options.scaleInference = inference;
+    }
+
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     const scaleCache = new Map();
+    let fallbackNote = autoScaleFallbackNote(options.scaleInference);
 
     const getScaleStateForProperty = (prop) => {
       const cached = scaleCache.get(prop);
@@ -208,7 +237,7 @@ const ruleFunction = (primary, secondaryOptions) => {
       const payload = {
         endIndex,
         index,
-        message: messages.rejected(value, lower, upper),
+        message: messages.rejected(value, lower, upper, fallbackNote),
         node: decl,
         result,
         ruleName,
@@ -221,6 +250,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         };
       }
 
+      fallbackNote = '';
       stylelint.utils.report(payload);
     };
 

package/src/utils/length.js

@@ -25,6 +25,21 @@ function parseLengthToken(rawValue) {
   return { number, raw: value, unit };
 }
 
+/**
+ * A hairline is a non-zero length that resolves to one CSS pixel or less:
+ * 1px, -1px, 0.5px, 0.0625rem. Such values compensate for a border width or a
+ * rendering quirk; they are not spacing decisions, so the scale rules exempt
+ * them by default (`allowHairlines`).
+ */
+function isHairlineLength(parsedLength, baseFontSize) {
+  if (!parsedLength || parsedLength.number === 0 || parsedLength.unit === '%') {
+    return false;
+  }
+
+  const px = toPx(Math.abs(parsedLength.number), parsedLength.unit || 'px', baseFontSize);
+  return px !== null && px > 0 && px <= 1;
+}
+
 function toPx(number, unit, baseFontSize) {
   if (unit === '' || unit === 'px') {
     return number;
@@ -168,6 +183,7 @@ function nearestScaleValues(target, scale) {
 module.exports = {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,

package/src/utils/options.js

@@ -65,6 +65,22 @@ function isUnitStrategy(value) {
   return value === 'convert' || value === 'exact';
 }
 
+function isAutoScaleLiteral(value) {
+  return value === 'auto';
+}
+
+function isScaleEntryOrAuto(value) {
+  return isAutoScaleLiteral(value) || isScaleEntry(value);
+}
+
+function isScaleSourceEntry(value) {
+  if (isNonEmptyString(value)) {
+    return true;
+  }
+
+  return isPlainObject(value) && (isNonEmptyString(value.path) || isNonEmptyString(value.file));
+}
+
 function isScaleEntry(value) {
   if (typeof value === 'number') {
     return Number.isFinite(value) && value >= 0;
@@ -237,7 +253,10 @@ function validateSecondaryOptionShapes(result, ruleName, secondaryOptions, schem
       continue;
     }
 
-    if (descriptor.expectsArray && !Array.isArray(optionValue)) {
+    const literalAllowed = Array.isArray(descriptor.allowLiterals)
+      && descriptor.allowLiterals.includes(optionValue);
+
+    if (descriptor.expectsArray && !Array.isArray(optionValue) && !literalAllowed) {
       valid = false;
       result.warn(
         `Invalid value ${stringifyOptionValue(optionValue)} for option "${optionName}" of rule "${ruleName}"`,
@@ -412,6 +431,9 @@ function resolveUnits(options) {
 }
 
 const SCALE_VALIDATION_SCHEMA = Object.freeze({
+  allowHairlines: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   allowNegative: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -443,9 +465,17 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isNonEmptyString,
   }),
   scale: Object.freeze({
-    entryValidator: isScaleEntry,
+    allowLiterals: ['auto'],
+    entryValidator: isScaleEntryOrAuto,
     expectsArray: true,
   }),
+  scaleSources: Object.freeze({
+    entryValidator: isScaleSourceEntry,
+    expectsArray: true,
+  }),
+  tailwindConfigPath: Object.freeze({
+    entryValidator: isNonEmptyString,
+  }),
   unitStrategy: Object.freeze({
     entryValidator: isUnitStrategy,
   }),
@@ -487,6 +517,9 @@ const NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA = Object.freeze({
 });
 
 const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
+  allowHairlines: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   allowNumericScale: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -528,7 +561,12 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     expectsObject: true,
   }),
   scale: Object.freeze({
-    entryValidator: isScaleEntry,
+    allowLiterals: ['auto'],
+    entryValidator: isScaleEntryOrAuto,
+    expectsArray: true,
+  }),
+  scaleSources: Object.freeze({
+    entryValidator: isScaleSourceEntry,
     expectsArray: true,
   }),
   tailwindConfigPath: Object.freeze({
@@ -578,6 +616,7 @@ function buildScaleOptions(rawOptions) {
   const scaleSelection = resolveScaleSelection(options, DEFAULT_SCALE);
 
   return {
+    allowHairlines: options.allowHairlines !== false,
     allowNegative: options.allowNegative !== false,
     allowPercentages: options.allowPercentages !== false,
     baseFontSize:
@@ -600,6 +639,13 @@ function buildScaleOptions(rawOptions) {
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
     scale: scaleSelection.scale,
+    scaleAuto: isAutoScaleLiteral(options.scale),
+    scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
+    tailwindConfigPath:
+      typeof options.tailwindConfigPath === 'string' && options.tailwindConfigPath.length > 0
+        ? options.tailwindConfigPath
+        : null,
+    tokenPatternExplicit: typeof options.tokenPattern === 'string' && options.tokenPattern.length > 0,
     tokenFunctions: Array.isArray(options.tokenFunctions)
       ? options.tokenFunctions.map((value) => String(value).toLowerCase())
       : ['var', 'theme', 'token'],
@@ -617,6 +663,7 @@ function buildTokenOptions(rawOptions) {
   const scaleSelection = resolveScaleSelection(options, DEFAULT_SCALE);
 
   return {
+    allowHairlines: options.allowHairlines !== false,
     allowNumericScale: options.allowNumericScale === true,
     baseFontSize:
       typeof options.baseFontSize === 'number' &&
@@ -637,6 +684,9 @@ function buildTokenOptions(rawOptions) {
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
     scale: scaleSelection.scale,
+    scaleAuto: isAutoScaleLiteral(options.scale),
+    scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
+    tokenPatternExplicit: typeof options.tokenPattern === 'string' && options.tokenPattern.length > 0,
     tailwindConfigPath:
       typeof options.tailwindConfigPath === 'string' && options.tailwindConfigPath.length > 0
         ? options.tailwindConfigPath

package/src/utils/scale-inference.js

@@ -0,0 +1,351 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseLengthToken, toPx } = require('./length');
+const { buildEffectiveTokenMap } = require('./token-map');
+const { collectScssTokens, createTokenKindMatcher, parseTokenSources } = require('./token-sources');
+const { getScalePreset } = require('../presets/scales');
+
+// Matches the audit default so lint and audit agree on what a spacing token is.
+const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing)(-|$)';
+// Tailwind v4 defines one base (`--spacing: 0.25rem`) and derives utilities by multiplying it.
+const TAILWIND_BASE_TOKENS = new Set(['--spacing', '--space']);
+const TAILWIND_SPACING_MULTIPLIERS = [
+  0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96,
+];
+const FALLBACK_PRESET = 'rhythmic-4';
+// Zero plus at least three distinct token values; a one- or two-token scale is worse than the default.
+const MIN_INFERRED_SCALE_LENGTH = 4;
+const RC_FILE = '.rhythmguardrc.json';
+
+const sourceCache = new Map();
+const TOKEN_PACKAGES = require('./token-packages.json').packages;
+
+/**
+ * Installed design-token packages that ship a spacing scale (allowlist in
+ * token-packages.json). Resolved from the project, so only what the project
+ * actually depends on is read. Returns token-source entries.
+ */
+function readDirectDependencies(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.devDependencies || {}),
+      ...Object.keys(pkg.peerDependencies || {}),
+    ]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Project roots from cwd up to the repository boundary (first directory holding
+ * .git), each with the dependencies it declares directly. Hoisted monorepo
+ * installs are found by walking up; a stray global node_modules is never
+ * consulted because the walk stops at the repository.
+ */
+function projectRoots(cwd) {
+  const roots = [];
+  let current = path.resolve(cwd);
+  for (;;) {
+    const direct = readDirectDependencies(current);
+    if (direct) {
+      roots.push({ dir: current, direct });
+    }
+    const parent = path.dirname(current);
+    if (fs.existsSync(path.join(current, '.git')) || parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return roots;
+}
+
+function discoverTokenPackages(cwd = process.cwd()) {
+  const sources = [];
+  const roots = projectRoots(cwd);
+  for (const entry of TOKEN_PACKAGES) {
+    // Only packages the project depends on directly count. A transitive
+    // tailwindcss (for example via stylelint-config-tailwindcss) must not hand
+    // a non-Tailwind project the Tailwind scale.
+    const owner = roots.find((root) => root.direct.has(entry.name));
+    if (!owner) {
+      continue;
+    }
+    const root = roots
+      .map((candidate) => path.join(candidate.dir, 'node_modules', entry.name))
+      .find((dir) => fs.existsSync(path.join(dir, 'package.json')));
+    if (!root) {
+      continue;
+    }
+    for (const file of entry.files) {
+      const resolved = path.join(root, file);
+      if (fs.existsSync(resolved)) {
+        sources.push({
+          format: 'auto',
+          package: entry.name,
+          path: resolved,
+          ...(entry.tokenPattern ? { tokenPattern: entry.tokenPattern } : {}),
+        });
+      }
+    }
+  }
+  return sources;
+}
+
+function pxValuesFromKeys(keys, baseFontSize) {
+  const values = new Set([0]);
+
+  for (const key of keys) {
+    const parsed = parseLengthToken(String(key));
+    if (!parsed) {
+      continue;
+    }
+
+    const px = toPx(Math.abs(parsed.number), parsed.unit || 'px', baseFontSize);
+    if (px !== null && Number.isFinite(px)) {
+      values.add(px);
+    }
+  }
+
+  return Array.from(values).sort((a, b) => a - b);
+}
+
+function normalizeSource(source, baseDir) {
+  if (typeof source === 'string') {
+    return { format: 'auto', path: path.resolve(baseDir, source) };
+  }
+
+  if (source && typeof source === 'object') {
+    const rawPath = source.path || source.file;
+    if (typeof rawPath !== 'string') {
+      return null;
+    }
+
+    return {
+      format: typeof source.format === 'string' ? source.format : 'auto',
+      path: path.resolve(source.baseDir || baseDir, rawPath),
+      ...(source.tokenPattern ? { tokenPattern: source.tokenPattern } : {}),
+    };
+  }
+
+  return null;
+}
+
+function cacheKey(sources) {
+  return sources
+    .map((source) => {
+      let mtime = 'missing';
+      try {
+        mtime = String(fs.statSync(source.path).mtimeMs);
+      } catch {
+        // missing file: key still changes when it appears
+      }
+      return `${source.path}|${source.format}|${source.tokenPattern || ''}|${mtime}`;
+    })
+    .join('\n');
+}
+
+function scaleFromSources(sources, baseFontSize) {
+  const normalized = sources.map((source) => normalizeSource(source, process.cwd())).filter(Boolean);
+  if (normalized.length === 0) {
+    return null;
+  }
+
+  const key = `${baseFontSize}\n${cacheKey(normalized)}`;
+  if (sourceCache.has(key)) {
+    return sourceCache.get(key);
+  }
+
+  const parsed = parseTokenSources({ baseFontSize, sources: normalized, tokenKind: 'spacing' });
+  // scaleFromDefinitions also expands a bare Tailwind --spacing base into its multiples.
+  const scale = scaleFromDefinitions(parsed.definitions, baseFontSize);
+  const outcome = scale
+    ? {
+      files: parsed.sources.map((source) => source.file),
+      scale,
+      tokenCount: parsed.definitions.size,
+      warnings: parsed.warnings,
+    }
+    : null;
+
+  sourceCache.set(key, outcome);
+  return outcome;
+}
+
+/** Build a px scale from token definitions as produced by token-sources.js / contract.js. */
+function scaleFromDefinitions(definitions, baseFontSize = 16) {
+  const keys = [];
+  const baseKeys = [];
+  for (const definition of definitions.values()) {
+    if (TAILWIND_BASE_TOKENS.has(definition.token)) {
+      baseKeys.push(...definition.normalizedValues);
+      continue;
+    }
+    keys.push(...definition.normalizedValues);
+  }
+  const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
+  return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
+}
+
+/** Merge Tailwind-style base multiples into a scale when a bare --spacing/--space base is defined. */
+function expandTailwindBase(scale, baseKeys, baseFontSize) {
+  const bases = pxValuesFromKeys(baseKeys, baseFontSize).filter((value) => value > 0);
+  if (bases.length === 0) {
+    return scale;
+  }
+  const values = new Set(scale);
+  for (const base of bases) {
+    for (const multiplier of TAILWIND_SPACING_MULTIPLIERS) {
+      values.add(Math.round(base * multiplier * 1000) / 1000);
+    }
+  }
+  return Array.from(values).sort((a, b) => a - b);
+}
+
+function rcTokenSources(cwd) {
+  const rcPath = path.join(cwd, RC_FILE);
+  if (!fs.existsSync(rcPath)) {
+    return [];
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
+  } catch {
+    return [];
+  }
+
+  const audit = config && typeof config === 'object' ? config.audit : null;
+  const sources = audit && Array.isArray(audit.tokenSources) ? audit.tokenSources : [];
+  const baseDir = path.dirname(rcPath);
+
+  return sources
+    .map((source) => normalizeSource(source, baseDir))
+    .filter(Boolean);
+}
+
+/**
+ * Sass variables and maps declared in the linted stylesheet itself (postcss-scss
+ * exposes them as declarations whose prop starts with `$`). Evaluated with the
+ * same collector the audit uses; component variables such as $dropdown-spacer
+ * are excluded by the anchored name rule.
+ */
+function sassValuesFromRoot(root) {
+  const lines = [];
+  root.walkDecls((decl) => {
+    if (typeof decl.prop === 'string' && decl.prop.startsWith('$')) {
+      lines.push(`${decl.prop}: ${decl.value};`);
+    }
+  });
+  if (lines.length === 0) {
+    return [];
+  }
+  return collectScssTokens(lines.join('\n'), createTokenKindMatcher('spacing')).map((token) => token.value);
+}
+
+function scaleFromTokenMap(map, baseFontSize, extraKeys = []) {
+  const keys = [...extraKeys];
+  const baseKeys = [];
+  for (const [key, reference] of Object.entries(map)) {
+    const name = String(reference).match(/^var\((--[\w-]+)\)$/);
+    if (name && TAILWIND_BASE_TOKENS.has(name[1])) {
+      baseKeys.push(key);
+    } else {
+      keys.push(key);
+    }
+  }
+  const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
+  return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
+}
+
+/**
+ * Resolve `scale: "auto"`. First matching source wins; sources are not merged so
+ * the provenance is a single file list or the stylesheet.
+ */
+function resolveAutoScale({
+  baseFontSize = 16,
+  root,
+  scaleSources = [],
+  tailwindConfigPath = null,
+  tokenPattern = DEFAULT_AUTO_TOKEN_PATTERN,
+} = {}) {
+  const fromOption = scaleFromSources(scaleSources, baseFontSize);
+  if (fromOption) {
+    return { source: 'scaleSources', ...fromOption };
+  }
+
+  const fromRc = scaleFromSources(rcTokenSources(process.cwd()), baseFontSize);
+  if (fromRc) {
+    return { source: 'rhythmguardrc', ...fromRc };
+  }
+
+  let tokenRegex;
+  try {
+    tokenRegex = new RegExp(tokenPattern);
+  } catch {
+    tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN);
+  }
+
+  if (root) {
+    const stylesheetMap = buildEffectiveTokenMap({
+      options: { baseFontSize, tokenMap: {}, tokenMapFromCssCustomProperties: true },
+      root,
+      tokenRegex,
+    });
+    const scale = scaleFromTokenMap(stylesheetMap, baseFontSize, sassValuesFromRoot(root));
+    if (scale) {
+      return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
+    }
+  }
+
+  if (tailwindConfigPath) {
+    const tailwindMap = buildEffectiveTokenMap({
+      options: {
+        baseFontSize,
+        tailwindConfigPath,
+        tokenMap: {},
+        tokenMapFromTailwindSpacing: true,
+      },
+      root,
+      tokenRegex,
+    });
+    const scale = scaleFromTokenMap(tailwindMap, baseFontSize);
+    if (scale) {
+      return { files: [tailwindConfigPath], scale, source: 'tailwind', tokenCount: scale.length - 1, warnings: [] };
+    }
+  }
+
+  const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize);
+  if (fromPackages) {
+    return { source: 'token-package', ...fromPackages };
+  }
+
+  return {
+    files: [],
+    preset: FALLBACK_PRESET,
+    scale: getScalePreset(FALLBACK_PRESET),
+    source: 'fallback',
+    tokenCount: 0,
+    warnings: [],
+  };
+}
+
+function autoScaleFallbackNote(inference) {
+  if (!inference || inference.source !== 'fallback') {
+    return '';
+  }
+
+  return `No spacing tokens were found for scale "auto"; using preset "${inference.preset}".`;
+}
+
+module.exports = {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  autoScaleFallbackNote,
+  discoverTokenPackages,
+  resolveAutoScale,
+  scaleFromDefinitions,
+};

package/src/utils/token-map.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { parseTokenValueLength } = require('./token-sources');
+
 const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
@@ -43,7 +45,7 @@ function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize) {
     return;
   }
 
-  const parsed = parseLengthToken(rawLength);
+  const parsed = parseTokenValueLength(rawLength);
   if (!parsed) {
     return;
   }
@@ -196,7 +198,7 @@ function mergeTokenMapFromCssCustomProperties({
       return;
     }
 
-    const parsed = parseLengthToken(decl.value);
+    const parsed = parseTokenValueLength(decl.value);
     if (!parsed || parsed.number === 0) {
       return;
     }

package/src/utils/token-packages.json

@@ -0,0 +1,48 @@
+{
+  "$comment": "Design-token packages whose installed files declare a spacing scale. Used by scale: \"auto\" after the project's own stylesheets are checked. Each entry lists the files to read (relative to the package root) and, when the package does not use space/spacing names, the token pattern to match. Additions welcome; keep them to files that ship in the published package.",
+  "packages": [
+    {
+      "name": "tailwindcss",
+      "files": [
+        "theme.css"
+      ],
+      "note": "Tailwind v4 base multiplier --spacing"
+    },
+    {
+      "name": "@radix-ui/themes",
+      "files": [
+        "tokens.css"
+      ],
+      "note": "--space-1..9 as calc(<px> * var(--scaling))"
+    },
+    {
+      "name": "@mantine/core",
+      "files": [
+        "styles.css"
+      ],
+      "note": "--mantine-spacing-* as calc(<rem> * var(--mantine-scale))"
+    },
+    {
+      "name": "@primer/primitives",
+      "files": [
+        "dist/css/base/size/size.css"
+      ],
+      "tokenPattern": "^--base-size-\\d+$",
+      "note": "Primer names its spacing ladder size"
+    },
+    {
+      "name": "@shopify/polaris-tokens",
+      "files": [
+        "dist/css/styles.css"
+      ],
+      "note": "--p-space-* in rem"
+    },
+    {
+      "name": "@spectrum-css/tokens",
+      "files": [
+        "dist/css/global-vars.css"
+      ],
+      "note": "--spectrum-spacing-* in px"
+    }
+  ]
+}