stylelint-plugin-rhythmguard 0.1.0

package/src/configs/recommended.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = {
+  plugins: ['stylelint-plugin-rhythmguard'],
+  rules: {
+    'rhythmguard/use-scale': [
+      true,
+      {
+        scale: [0, 4, 8, 12, 16, 24, 32, 40, 48, 64],
+      },
+    ],
+  },
+};

package/src/configs/strict.js

@@ -0,0 +1,25 @@
+'use strict';
+
+module.exports = {
+  plugins: ['stylelint-plugin-rhythmguard'],
+  rules: {
+    'rhythmguard/use-scale': [
+      true,
+      {
+        scale: [0, 4, 8, 12, 16, 24, 32, 40, 48, 64],
+      },
+    ],
+    'rhythmguard/no-offscale-transform': [
+      true,
+      {
+        scale: [0, 4, 8, 12, 16, 24, 32],
+      },
+    ],
+    'rhythmguard/prefer-token': [
+      true,
+      {
+        tokenPattern: '^--space-',
+      },
+    ],
+  },
+};

package/src/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const useScale = require('./rules/use-scale');
+const preferToken = require('./rules/prefer-token');
+const noOffscaleTransform = require('./rules/no-offscale-transform');
+
+const rules = [useScale, preferToken, noOffscaleTransform];
+
+module.exports = rules;
+module.exports.rules = {
+  [useScale.ruleName]: useScale,
+  [preferToken.ruleName]: preferToken,
+  [noOffscaleTransform.ruleName]: noOffscaleTransform,
+};
+module.exports.configs = {
+  recommended: require('./configs/recommended'),
+  strict: require('./configs/strict'),
+};
+module.exports.presets = require('./presets');

package/src/presets/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const {
+  SCALE_PRESETS,
+  getScalePreset,
+  listScalePresetNames,
+} = require('./scales');
+
+module.exports = {
+  scales: SCALE_PRESETS,
+  getScalePreset,
+  listScalePresetNames,
+};

package/src/presets/scales.js

@@ -0,0 +1,122 @@
+'use strict';
+
+function createModularScale({ base, ratio, steps }) {
+  const values = [0];
+  let current = base;
+
+  for (let i = 0; i < steps; i += 1) {
+    values.push(Math.round(current));
+    current *= ratio;
+  }
+
+  return [...new Set(values)].sort((a, b) => a - b);
+}
+
+const SCALE_PRESETS = Object.freeze({
+  'rhythmic-4': Object.freeze([0, 4, 8, 12, 16, 24, 32, 40, 48, 64]),
+  'rhythmic-8': Object.freeze([0, 8, 16, 24, 32, 40, 48, 64, 80, 96]),
+  'product-material-8dp': Object.freeze([0, 4, 8, 12, 16, 24, 32, 40, 48, 56, 64, 72, 80]),
+  'product-atlassian-8px': Object.freeze([0, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80]),
+  'product-carbon-2x': Object.freeze([0, 2, 4, 8, 12, 16, 24, 32, 40, 48, 64, 80]),
+  'editorial-baseline-4': Object.freeze([0, 4, 8, 12, 16, 20, 24, 28, 32, 40, 48, 56, 64]),
+  'editorial-baseline-6': Object.freeze([0, 6, 12, 18, 24, 30, 36, 48, 60, 72]),
+  compact: Object.freeze([0, 2, 4, 6, 8, 12, 16, 20, 24, 32]),
+  fibonacci: Object.freeze([0, 2, 3, 5, 8, 13, 21, 34, 55, 89]),
+  'powers-of-two': Object.freeze([0, 2, 4, 8, 16, 32, 64, 128]),
+  'golden-ratio': Object.freeze(createModularScale({ base: 4, ratio: 1.61803398875, steps: 10 })),
+  'modular-major-second': Object.freeze(createModularScale({ base: 8, ratio: 1.125, steps: 12 })),
+  'modular-minor-third': Object.freeze(createModularScale({ base: 4, ratio: 1.2, steps: 12 })),
+  'modular-major-third': Object.freeze(createModularScale({ base: 4, ratio: 1.25, steps: 12 })),
+  'modular-augmented-fourth': Object.freeze(createModularScale({ base: 4, ratio: 1.41421356237, steps: 12 })),
+  'modular-perfect-fourth': Object.freeze(createModularScale({ base: 4, ratio: 4 / 3, steps: 12 })),
+  'modular-perfect-fifth': Object.freeze(createModularScale({ base: 4, ratio: 1.5, steps: 12 })),
+});
+
+const PRESET_ALIASES = Object.freeze({
+  '4pt': 'rhythmic-4',
+  '8pt': 'rhythmic-8',
+  'atlassian-8': 'product-atlassian-8px',
+  carbon: 'product-carbon-2x',
+  material: 'product-material-8dp',
+  'baseline-4': 'editorial-baseline-4',
+  'baseline-6': 'editorial-baseline-6',
+  golden: 'golden-ratio',
+  'major-second': 'modular-major-second',
+  'major-third': 'modular-major-third',
+  'minor-third': 'modular-minor-third',
+  'augmented-fourth': 'modular-augmented-fourth',
+  'perfect-fifth': 'modular-perfect-fifth',
+  'perfect-fourth': 'modular-perfect-fourth',
+});
+
+function normalizePresetName(name) {
+  return String(name).trim().toLowerCase();
+}
+
+function resolvePresetName(name) {
+  if (typeof name !== 'string' || name.trim().length === 0) {
+    return null;
+  }
+
+  const normalized = normalizePresetName(name);
+  return PRESET_ALIASES[normalized] || normalized;
+}
+
+function getScalePreset(name) {
+  const resolvedName = resolvePresetName(name);
+  if (!resolvedName) {
+    return null;
+  }
+
+  return SCALE_PRESETS[resolvedName] || null;
+}
+
+function listScalePresetNames() {
+  return Object.keys(SCALE_PRESETS);
+}
+
+function resolveScaleSelection(options, defaultScale) {
+  const hasScale = Array.isArray(options.scale);
+  const hasCustomScale = Array.isArray(options.customScale);
+  const presetName = resolvePresetName(options.preset);
+
+  let invalidPreset = null;
+  let selectedPreset = null;
+  let scale = defaultScale;
+
+  if (presetName) {
+    const presetScale = getScalePreset(presetName);
+
+    if (presetScale) {
+      selectedPreset = presetName;
+      scale = presetScale;
+    } else {
+      invalidPreset = String(options.preset);
+    }
+  }
+
+  if (hasScale) {
+    scale = options.scale;
+    selectedPreset = null;
+    invalidPreset = null;
+  }
+
+  if (hasCustomScale) {
+    scale = options.customScale;
+    selectedPreset = null;
+    invalidPreset = null;
+  }
+
+  return {
+    invalidPreset,
+    scale,
+    selectedPreset,
+  };
+}
+
+module.exports = {
+  SCALE_PRESETS,
+  getScalePreset,
+  listScalePresetNames,
+  resolveScaleSelection,
+};

package/src/rules/no-offscale-transform/index.js

@@ -0,0 +1,169 @@
+'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 {
+  declarationValueIndex,
+  walkTransformTranslateNodes,
+} = require('../../utils/value-utils');
+
+const ruleName = 'rhythmguard/no-offscale-transform';
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  invalidPreset: (presetName, presetNames) =>
+    `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
+  rejected: (value, lower, upper) =>
+    `Unexpected transform translation value "${value}". Use 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);
+}
+
+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 scalePx = normalizeScale(options.scale, options.baseFontSize);
+
+    root.walkDecls((decl) => {
+      const prop = decl.prop.toLowerCase();
+      if (prop !== 'transform' && prop !== 'translate' && !prop.startsWith('translate-')) {
+        return;
+      }
+
+      const parsed = valueParser(decl.value);
+      let changed = false;
+
+      const report = (node, nearest, fixedValue = null) => {
+        const index = declarationValueIndex(decl) + node.sourceIndex;
+        const endIndex = index + node.value.length;
+
+        const payload = {
+          endIndex,
+          index,
+          message: messages.rejected(
+            node.value,
+            formatLength(nearest.lower, 'px'),
+            formatLength(nearest.upper, 'px'),
+          ),
+          node: decl,
+          result,
+          ruleName,
+        };
+
+        if (fixedValue) {
+          payload.fix = () => {
+            node.value = fixedValue;
+            return true;
+          };
+        }
+
+        stylelint.utils.report(payload);
+      };
+
+      const checkNode = (node) => {
+        const parsedLength = parseLengthToken(node.value);
+        if (!parsedLength || parsedLength.number === 0) {
+          return;
+        }
+
+        if (parsedLength.unit === '%' && options.allowPercentages) {
+          return;
+        }
+
+        if (!options.allowNegative && parsedLength.number < 0) {
+          return;
+        }
+
+        const pxValue = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
+        if (pxValue === null) {
+          return;
+        }
+
+        const isOnScale = scalePx.some((entry) => numbersEqual(entry, pxValue));
+        if (isOnScale) {
+          return;
+        }
+
+        const nearest = nearestScaleValues(pxValue, scalePx);
+        if (!nearest) {
+          return;
+        }
+
+        const fixedValue = options.fixToScale
+          ? getFixedNodeValue(parsedLength, nearest.nearest, options)
+          : null;
+
+        report(node, nearest, fixedValue);
+        changed = true;
+      };
+
+      if (prop === 'transform') {
+        walkTransformTranslateNodes(parsed, (node) => {
+          checkNode(node);
+        });
+      } else {
+        for (const node of parsed.nodes) {
+          if (node.type === 'word') {
+            checkNode(node);
+          }
+        }
+      }
+
+      if (changed) {
+        decl.value = parsed.toString();
+      }
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+ruleFunction.meta = {
+  fixable: true,
+  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguardno-offscale-transform',
+};
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);
+module.exports.ruleName = ruleName;
+module.exports.messages = messages;
+module.exports.meta = ruleFunction.meta;

package/src/rules/prefer-token/index.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const stylelint = require('stylelint');
+const valueParser = require('postcss-value-parser');
+const {
+  normalizeScale,
+  numbersEqual,
+  parseLengthToken,
+  toPx,
+} = require('../../utils/length');
+const { buildTokenOptions } = require('../../utils/options');
+const {
+  createTokenRegex,
+  declarationValueIndex,
+  isKeyword,
+  isMathFunction,
+  isTokenFunction,
+  propertyMatches,
+  walkRootValueNodes,
+  walkTransformTranslateNodes,
+} = require('../../utils/value-utils');
+
+const ruleName = 'rhythmguard/prefer-token';
+
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  invalidPreset: (presetName, presetNames) =>
+    `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
+  rejected: (value) =>
+    `Unexpected raw spacing value "${value}". Use design tokens for spacing decisions.`,
+});
+
+function resolveTokenReplacement(tokenMap, raw, normalizedPx) {
+  if (Object.prototype.hasOwnProperty.call(tokenMap, raw)) {
+    return tokenMap[raw];
+  }
+
+  const pxKey = `${normalizedPx}px`;
+  if (Object.prototype.hasOwnProperty.call(tokenMap, pxKey)) {
+    return tokenMap[pxKey];
+  }
+
+  return null;
+}
+
+const ruleFunction = (primary, secondaryOptions) => {
+  return (root, result) => {
+    const valid = stylelint.utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    });
+
+    if (!valid) {
+      return;
+    }
+
+    const options = buildTokenOptions(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);
+
+    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;
+
+      const reportNode = (node, replacement = null) => {
+        const index = declarationValueIndex(decl) + node.sourceIndex;
+        const endIndex = index + node.value.length;
+
+        const payload = {
+          endIndex,
+          index,
+          message: messages.rejected(node.value),
+          node: decl,
+          result,
+          ruleName,
+        };
+
+        if (replacement) {
+          payload.fix = () => {
+            node.value = replacement;
+            return true;
+          };
+        }
+
+        stylelint.utils.report(payload);
+      };
+
+      const checkWordNode = (node, parentFunctionName) => {
+        if (isKeyword(node.value, options.ignoreValues)) {
+          return false;
+        }
+
+        if (
+          parentFunctionName &&
+          isMathFunction(parentFunctionName)
+        ) {
+          return false;
+        }
+
+        const parsedLength = parseLengthToken(node.value);
+        if (!parsedLength) {
+          return false;
+        }
+
+        if (parsedLength.number === 0) {
+          return false;
+        }
+
+        const absPx = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
+        if (absPx === null) {
+          return false;
+        }
+
+        if (options.allowNumericScale) {
+          const onScale = scalePx.some((entry) => numbersEqual(entry, absPx));
+          if (onScale) {
+            return false;
+          }
+        }
+
+        const replacement = resolveTokenReplacement(options.tokenMap, node.value, absPx);
+
+        reportNode(node, replacement);
+        return true;
+      };
+
+      if (prop === 'transform') {
+        walkTransformTranslateNodes(parsed, (node) => {
+          changed = checkWordNode(node) || changed;
+        });
+      } else {
+        walkRootValueNodes(parsed, (node, parentFunctionName) => {
+          if (node.type === 'function') {
+            if (isTokenFunction(node, options.tokenFunctions, tokenRegex)) {
+              return true;
+            }
+
+            if (isMathFunction(node.value)) {
+              return true;
+            }
+
+            return false;
+          }
+
+          if (node.type !== 'word') {
+            return false;
+          }
+
+          changed = checkWordNode(node, parentFunctionName) || 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#rhythmguardprefer-token',
+};
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);
+module.exports.ruleName = ruleName;
+module.exports.messages = messages;
+module.exports.meta = ruleFunction.meta;