stylelint-plugin-rhythmguard 0.1.0

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

@@ -0,0 +1,246 @@
+'use strict';
+
+const stylelint = require('stylelint');
+const valueParser = require('postcss-value-parser');
+const {
+  formatLength,
+  fromPx,
+  nearestScaleValues,
+  normalizeScale,
+  numbersEqual,
+  parseLengthToken,
+  toPx,
+} = require('../../utils/length');
+const { buildScaleOptions } = require('../../utils/options');
+const {
+  createTokenRegex,
+  declarationValueIndex,
+  isKeyword,
+  isMathFunction,
+  isTokenFunction,
+  propertyMatches,
+  walkRootValueNodes,
+  walkTransformTranslateNodes,
+} = require('../../utils/value-utils');
+
+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 spacing value "${value}". Use spacing scale values (nearest: ${lower} or ${upper}).`,
+});
+
+function getFixedNodeValue(parsedLength, nearestPx, options) {
+  const unit = parsedLength.unit || 'px';
+
+  if (unit === '%' || !options.units.includes(unit)) {
+    return null;
+  }
+
+  const signedNearest = parsedLength.number < 0 ? -Math.abs(nearestPx) : nearestPx;
+  const converted = fromPx(signedNearest, unit, options.baseFontSize);
+
+  if (converted === null) {
+    return null;
+  }
+
+  return formatLength(converted, unit);
+}
+
+function checkLengthValue({
+  decl,
+  node,
+  options,
+  report,
+  scalePx,
+}) {
+  const parsedLength = parseLengthToken(node.value);
+
+  if (!parsedLength) {
+    return false;
+  }
+
+  if (parsedLength.number === 0) {
+    return false;
+  }
+
+  if (parsedLength.unit === '%' && options.allowPercentages) {
+    return false;
+  }
+
+  if (!options.allowNegative && parsedLength.number < 0) {
+    report(node.value, decl, node);
+    return false;
+  }
+
+  if (
+    parsedLength.unit &&
+    parsedLength.unit !== '%' &&
+    !options.units.includes(parsedLength.unit)
+  ) {
+    return false;
+  }
+
+  const pxValue = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
+
+  if (pxValue === null) {
+    return false;
+  }
+
+  const isOnScale = scalePx.some((scaleValue) => numbersEqual(scaleValue, pxValue));
+  if (isOnScale) {
+    return false;
+  }
+
+  const nearest = nearestScaleValues(pxValue, scalePx);
+  if (!nearest) {
+    return false;
+  }
+
+  const fixedValue = options.fixToScale
+    ? getFixedNodeValue(parsedLength, nearest.nearest, options)
+    : null;
+
+  report(node.value, decl, node, nearest, fixedValue);
+  return true;
+}
+
+const ruleFunction = (primary, secondaryOptions) => {
+  return (root, result) => {
+    const valid = stylelint.utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    });
+
+    if (!valid) {
+      return;
+    }
+
+    const options = buildScaleOptions(secondaryOptions);
+    if (options.invalidPreset) {
+      stylelint.utils.report({
+        message: messages.invalidPreset(options.invalidPreset, options.presetNames),
+        node: root,
+        result,
+        ruleName,
+      });
+    }
+
+    const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
+    const scalePx = normalizeScale(options.scale, options.baseFontSize);
+
+    const report = (value, decl, node, nearest, fixedValue = null) => {
+      const index = declarationValueIndex(decl) + node.sourceIndex;
+      const endIndex = index + node.value.length;
+      const lower = nearest ? formatLength(nearest.lower, 'px') : 'n/a';
+      const upper = nearest ? formatLength(nearest.upper, 'px') : 'n/a';
+
+      const payload = {
+        endIndex,
+        index,
+        message: messages.rejected(value, lower, upper),
+        node: decl,
+        result,
+        ruleName,
+      };
+
+      if (fixedValue) {
+        payload.fix = () => {
+          node.value = fixedValue;
+          return true;
+        };
+      }
+
+      stylelint.utils.report(payload);
+    };
+
+    root.walkDecls((decl) => {
+      const prop = decl.prop.toLowerCase();
+      if (prop.startsWith('--')) {
+        return;
+      }
+
+      if (!propertyMatches(prop, options.properties)) {
+        return;
+      }
+
+      const parsed = valueParser(decl.value);
+      let changed = false;
+
+      if (prop === 'transform') {
+        walkTransformTranslateNodes(parsed, (node) => {
+          changed =
+            checkLengthValue({
+              decl,
+              node,
+              options,
+              report,
+              scalePx,
+            }) || changed;
+        });
+      } else {
+        walkRootValueNodes(parsed, (node, parentFunctionName) => {
+          if (node.type === 'function') {
+            if (isTokenFunction(node, options.tokenFunctions, tokenRegex)) {
+              return true;
+            }
+
+            if (
+              isMathFunction(node.value) &&
+              !options.enforceInsideMathFunctions
+            ) {
+              return true;
+            }
+
+            return false;
+          }
+
+          if (node.type !== 'word') {
+            return false;
+          }
+
+          if (isKeyword(node.value, options.ignoreValues)) {
+            return false;
+          }
+
+          if (
+            parentFunctionName &&
+            isMathFunction(parentFunctionName) &&
+            !options.enforceInsideMathFunctions
+          ) {
+            return false;
+          }
+
+          changed =
+            checkLengthValue({
+              decl,
+              node,
+              options,
+              report,
+              scalePx,
+            }) || changed;
+
+          return false;
+        });
+      }
+
+      if (changed) {
+        decl.value = parsed.toString();
+      }
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+ruleFunction.meta = {
+  fixable: true,
+  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguarduse-scale',
+};
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);
+module.exports.ruleName = ruleName;
+module.exports.messages = messages;
+module.exports.meta = ruleFunction.meta;

package/src/utils/constants.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const SPACING_PROPERTY_PATTERNS = [
+  /^margin(?:-.+)?$/,
+  /^padding(?:-.+)?$/,
+  /^gap$/,
+  /^row-gap$/,
+  /^column-gap$/,
+  /^inset(?:-.+)?$/,
+  /^scroll-margin(?:-.+)?$/,
+  /^scroll-padding(?:-.+)?$/,
+  /^translate$/,
+  /^translate-[xyz]$/,
+  /^transform$/,
+];
+
+const DEFAULT_IGNORE_KEYWORDS = [
+  'auto',
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+];
+
+const TRANSLATE_FUNCTIONS = new Set([
+  'translate',
+  'translatex',
+  'translatey',
+  'translatez',
+  'translate3d',
+]);
+
+const MATH_FUNCTIONS = new Set(['calc', 'clamp', 'min', 'max']);
+
+module.exports = {
+  DEFAULT_IGNORE_KEYWORDS,
+  MATH_FUNCTIONS,
+  SPACING_PROPERTY_PATTERNS,
+  TRANSLATE_FUNCTIONS,
+};

package/src/utils/length.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const LENGTH_RE = /^(-?(?:\d+|\d*\.\d+))(px|rem|em|%)?$/i;
+const EPSILON = 0.0001;
+
+function parseLengthToken(rawValue) {
+  if (typeof rawValue !== 'string') {
+    return null;
+  }
+
+  const value = rawValue.trim();
+  const match = value.match(LENGTH_RE);
+
+  if (!match) {
+    return null;
+  }
+
+  const number = Number(match[1]);
+  const unit = (match[2] || '').toLowerCase();
+
+  if (!Number.isFinite(number)) {
+    return null;
+  }
+
+  return { number, raw: value, unit };
+}
+
+function toPx(number, unit, baseFontSize) {
+  if (unit === '' || unit === 'px') {
+    return number;
+  }
+
+  if (unit === 'rem' || unit === 'em') {
+    return number * baseFontSize;
+  }
+
+  return null;
+}
+
+function fromPx(pxValue, unit, baseFontSize) {
+  if (unit === '' || unit === 'px') {
+    return pxValue;
+  }
+
+  if (unit === 'rem' || unit === 'em') {
+    return pxValue / baseFontSize;
+  }
+
+  return null;
+}
+
+function formatNumber(value) {
+  if (Math.abs(value) < EPSILON) {
+    return '0';
+  }
+
+  const rounded = Math.round(value * 10000) / 10000;
+  return String(rounded).replace(/\.?0+$/, '');
+}
+
+function formatLength(number, unit) {
+  if (number === 0) {
+    if (unit === 'px') {
+      return '0px';
+    }
+
+    if (unit === 'rem' || unit === 'em' || unit === '') {
+      return '0';
+    }
+  }
+
+  return `${formatNumber(number)}${unit}`;
+}
+
+function numbersEqual(a, b) {
+  return Math.abs(a - b) < EPSILON;
+}
+
+function normalizeScale(scale, baseFontSize) {
+  const normalized = [];
+
+  for (const entry of scale) {
+    if (typeof entry === 'number') {
+      normalized.push(entry);
+      continue;
+    }
+
+    const parsed = parseLengthToken(String(entry));
+    if (!parsed) {
+      continue;
+    }
+
+    const px = toPx(parsed.number, parsed.unit, baseFontSize);
+    if (px !== null) {
+      normalized.push(px);
+    }
+  }
+
+  return [...new Set(normalized)].sort((a, b) => a - b);
+}
+
+function nearestScaleValues(targetPx, scalePx) {
+  if (scalePx.length === 0) {
+    return null;
+  }
+
+  let lower = scalePx[0];
+  let upper = scalePx[scalePx.length - 1];
+
+  for (const value of scalePx) {
+    if (value <= targetPx) {
+      lower = value;
+    }
+
+    if (value >= targetPx) {
+      upper = value;
+      break;
+    }
+  }
+
+  const nearest =
+    Math.abs(targetPx - lower) <= Math.abs(upper - targetPx) ? lower : upper;
+
+  return {
+    lower,
+    nearest,
+    upper,
+  };
+}
+
+module.exports = {
+  formatLength,
+  normalizeScale,
+  numbersEqual,
+  parseLengthToken,
+  toPx,
+  fromPx,
+  nearestScaleValues,
+};

package/src/utils/options.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const {
+  DEFAULT_IGNORE_KEYWORDS,
+  SPACING_PROPERTY_PATTERNS,
+} = require('./constants');
+const {
+  getScalePreset,
+  listScalePresetNames,
+  resolveScaleSelection,
+} = require('../presets/scales');
+
+const DEFAULT_SCALE = getScalePreset('rhythmic-4') || [0, 4, 8, 12, 16, 24, 32];
+
+function buildScaleOptions(rawOptions) {
+  const options = rawOptions || {};
+  const scaleSelection = resolveScaleSelection(options, DEFAULT_SCALE);
+
+  return {
+    allowNegative: options.allowNegative !== false,
+    allowPercentages: options.allowPercentages !== false,
+    baseFontSize:
+      typeof options.baseFontSize === 'number' &&
+      Number.isFinite(options.baseFontSize) &&
+      options.baseFontSize > 0
+        ? options.baseFontSize
+        : 16,
+    enforceInsideMathFunctions: options.enforceInsideMathFunctions === true,
+    fixToScale: options.fixToScale !== false,
+    ignoreValues: Array.isArray(options.ignoreValues)
+      ? options.ignoreValues.map((value) => String(value).toLowerCase())
+      : DEFAULT_IGNORE_KEYWORDS,
+    invalidPreset: scaleSelection.invalidPreset,
+    preset: scaleSelection.selectedPreset,
+    presetNames: listScalePresetNames(),
+    properties: Array.isArray(options.properties)
+      ? options.properties
+      : SPACING_PROPERTY_PATTERNS,
+    scale: scaleSelection.scale,
+    tokenFunctions: Array.isArray(options.tokenFunctions)
+      ? options.tokenFunctions.map((value) => String(value).toLowerCase())
+      : ['var', 'theme', 'token'],
+    tokenPattern:
+      typeof options.tokenPattern === 'string' && options.tokenPattern.length > 0
+        ? options.tokenPattern
+        : '^--space-',
+    units: Array.isArray(options.units)
+      ? options.units.map((unit) => String(unit).toLowerCase())
+      : ['px', 'rem', 'em'],
+  };
+}
+
+function buildTokenOptions(rawOptions) {
+  const options = rawOptions || {};
+  const scaleSelection = resolveScaleSelection(options, DEFAULT_SCALE);
+
+  return {
+    allowNumericScale: options.allowNumericScale === true,
+    baseFontSize:
+      typeof options.baseFontSize === 'number' &&
+      Number.isFinite(options.baseFontSize) &&
+      options.baseFontSize > 0
+        ? options.baseFontSize
+        : 16,
+    ignoreValues: Array.isArray(options.ignoreValues)
+      ? options.ignoreValues.map((value) => String(value).toLowerCase())
+      : DEFAULT_IGNORE_KEYWORDS,
+    invalidPreset: scaleSelection.invalidPreset,
+    preset: scaleSelection.selectedPreset,
+    presetNames: listScalePresetNames(),
+    properties: Array.isArray(options.properties)
+      ? options.properties
+      : SPACING_PROPERTY_PATTERNS,
+    scale: scaleSelection.scale,
+    tokenFunctions: Array.isArray(options.tokenFunctions)
+      ? options.tokenFunctions.map((value) => String(value).toLowerCase())
+      : ['var', 'theme', 'token'],
+    tokenMap:
+      options.tokenMap && typeof options.tokenMap === 'object'
+        ? options.tokenMap
+        : {},
+    tokenPattern:
+      typeof options.tokenPattern === 'string' && options.tokenPattern.length > 0
+        ? options.tokenPattern
+        : '^--space-',
+  };
+}
+
+module.exports = {
+  buildScaleOptions,
+  buildTokenOptions,
+};

package/src/utils/value-utils.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const valueParser = require('postcss-value-parser');
+const stylelint = require('stylelint');
+const {
+  MATH_FUNCTIONS,
+  TRANSLATE_FUNCTIONS,
+} = require('./constants');
+
+function propertyMatches(prop, patterns) {
+  const normalized = prop.toLowerCase();
+  return patterns.some((pattern) => {
+    if (pattern instanceof RegExp) {
+      return pattern.test(normalized);
+    }
+
+    return String(pattern).toLowerCase() === normalized;
+  });
+}
+
+function isKeyword(value, ignoreValues) {
+  return ignoreValues.includes(String(value).toLowerCase());
+}
+
+function createTokenRegex(tokenPattern, result, ruleName) {
+  try {
+    return new RegExp(tokenPattern);
+  } catch {
+    stylelint.utils.report({
+      message: `Invalid tokenPattern regex: ${tokenPattern}`,
+      result,
+      ruleName,
+    });
+
+    return /^--space-/;
+  }
+}
+
+function isTokenFunction(node, tokenFunctions, tokenRegex) {
+  if (node.type !== 'function') {
+    return false;
+  }
+
+  const fn = node.value.toLowerCase();
+  if (!tokenFunctions.includes(fn)) {
+    return false;
+  }
+
+  if (fn !== 'var') {
+    return true;
+  }
+
+  const firstArg = valueParser.stringify(node.nodes).split(',')[0].trim();
+  return tokenRegex.test(firstArg);
+}
+
+function walkRootValueNodes(parsed, walkNode, state) {
+  const walkNodes = (nodes, parentFunctionName) => {
+    for (const node of nodes) {
+      if (node.type === 'function') {
+        const fnName = node.value.toLowerCase();
+        const skipChildren = walkNode(node, parentFunctionName);
+
+        if (skipChildren) {
+          continue;
+        }
+
+        walkNodes(node.nodes, fnName);
+        continue;
+      }
+
+      walkNode(node, parentFunctionName);
+    }
+  };
+
+  walkNodes(parsed.nodes, state || null);
+}
+
+function walkTransformTranslateNodes(parsed, walkNode) {
+  for (const node of parsed.nodes) {
+    if (node.type !== 'function') {
+      continue;
+    }
+
+    if (!TRANSLATE_FUNCTIONS.has(node.value.toLowerCase())) {
+      continue;
+    }
+
+    for (const child of node.nodes) {
+      if (child.type === 'word') {
+        walkNode(child, node.value.toLowerCase());
+      }
+    }
+  }
+}
+
+function isMathFunction(functionName) {
+  if (!functionName) {
+    return false;
+  }
+
+  return MATH_FUNCTIONS.has(functionName.toLowerCase());
+}
+
+function declarationValueIndex(decl) {
+  const declarationText = decl.toString();
+  const idx = declarationText.indexOf(decl.value);
+  return idx === -1 ? 0 : idx;
+}
+
+module.exports = {
+  createTokenRegex,
+  declarationValueIndex,
+  isKeyword,
+  isMathFunction,
+  isTokenFunction,
+  propertyMatches,
+  walkRootValueNodes,
+  walkTransformTranslateNodes,
+};