stylelint-plugin-rhythmguard 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-02-17
+
+### Added
+
+- Strict `secondaryOptions` validation for all three rules:
+  - `rhythmguard/use-scale`
+  - `rhythmguard/prefer-token`
+  - `rhythmguard/no-offscale-transform`
+- Invalid option names (for example `sevverity`) now fail with Stylelint invalid option warnings instead of silently being ignored.
+- Type/shape validation for option payloads (for example `properties` must be an array, `tokenMap` must be an object).
+- Regression tests for invalid secondary option names and option value shapes.
+
+### Changed
+
+- Added `known-css-properties` as a direct runtime dependency to guarantee `properties` option validation in consumer installs.
+- `properties` option validation now checks supported spacing property names against known CSS property metadata (plus `translate-x`, `translate-y`, `translate-z`).
+
 ## [1.2.1] - 2026-02-17
 
 ### Fixed
@@ -15,6 +32,7 @@ The format follows Keep a Changelog principles and semantic versioning.
 - `rhythmguard/prefer-token` now supports `enforceInsideMathFunctions` for optional math-function enforcement.
 - Hardened `var()` token argument detection to parse the first argument structurally (rather than comma string splitting).
 - npm README link integrity: docs links now resolve to absolute GitHub URLs from the npm package page.
+- Release workflow now detects missing `NPM_TOKEN` and skips publish cleanly with an explicit notice instead of failing.
 
 ### Added
 

package/README.md

@@ -14,6 +14,16 @@ High-precision spacing governance for CSS and design systems.
 
 `stylelint-plugin-rhythmguard` enforces spacing discipline across margin, padding, gap, inset, scroll spacing, and translate motion offsets.
 
+## 60-second Demo
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-campaign-60s.webm">
+    <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-campaign-60s.gif" width="100%" alt="Rhythmguard 60-second campaign demo" />
+  </a>
+</p>
+
+- Full video (WebM): [rhythmguard-campaign-60s.webm](https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-campaign-60s.webm)
+
 I built Rhythmguard after 20 years of watching teams ignore spacing scales and ship arbitrary pixel values everywhere.
 
 It is built for teams that want:
@@ -146,6 +156,24 @@ Scale resolution precedence:
 3. `preset`
 4. default `rhythmic-4` scale
 
+## Option Validation
+
+Rhythmguard validates `secondaryOptions` for each rule before linting declarations.
+
+- Unknown option names fail fast with Stylelint invalid option warnings.
+- Invalid option shapes fail fast (for example string vs array mismatches).
+- `properties` string entries are validated against supported CSS spacing property names, plus `translate-x`, `translate-y`, and `translate-z`.
+
+Example typo that now fails immediately:
+
+```json
+{
+  "rules": {
+    "rhythmguard/use-scale": [true, { "sevverity": "warning" }]
+  }
+}
+```
+
 ## Built-in Scale Presets
 
 | Preset | Pattern | Scale |
@@ -267,7 +295,7 @@ Options:
 | `allowPercentages` | `boolean` | `true` | Allows `%` values without scale checks |
 | `fixToScale` | `boolean` | `true` | Enables nearest-value autofix |
 | `enforceInsideMathFunctions` | `boolean` | `false` | Lints `calc()/clamp()/min()/max()` internals |
-| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set |
+| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set; string values must be supported spacing property names |
 
 ### `rhythmguard/prefer-token`
 
@@ -303,7 +331,7 @@ Options:
 | `enforceInsideMathFunctions` | `boolean` | `false` | Lints `calc()/clamp()/min()/max()` internals |
 | `tokenMap` | `Record<string,string>` | `{}` | Enables autofix from raw value to token |
 | `ignoreValues` | `string[]` | CSS global keywords + `auto` | Skips keyword literals |
-| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set |
+| `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set; string values must be supported spacing property names |
 
 ### `rhythmguard/no-offscale-transform`
 
@@ -325,7 +353,7 @@ Example:
 
 Options:
 
-`rhythmguard/no-offscale-transform` accepts the same scale options as `rhythmguard/use-scale`, but only for transform translation properties.
+`rhythmguard/no-offscale-transform` accepts the same scale options as `rhythmguard/use-scale`, but only for transform translation properties. Its secondary options are also validated for unknown keys and invalid value shapes.
 
 ## Tailwind CSS Integration
 
@@ -441,8 +469,9 @@ Detailed methodology and custom args are documented in [`docs/BENCHMARKING.md`](
 1. Create a GitHub release.
 2. `release.yml` runs the Node/Stylelint matrix validation.
 3. A tarball smoke test validates package exports and install behavior.
-4. The package is published to npm with provenance (`npm publish --provenance`).
-5. `post-publish-smoke.yml` verifies the published npm version can be installed and run in a clean project.
+4. If `NPM_TOKEN` is configured in repository secrets, the package is published to npm with provenance (`npm publish --provenance`).
+5. If `NPM_TOKEN` is not configured, publish is skipped with an explicit workflow notice.
+6. `post-publish-smoke.yml` verifies the published npm version can be installed and run in a clean project (and skips cleanly if the version is not on npm).
 
 ## Support and Bug Reports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Stylelint plugin for spacing scale and token enforcement",
   "keywords": [
     "stylelint",
@@ -61,6 +61,7 @@
     "stylelint": "^16.0.0"
   },
   "dependencies": {
+    "known-css-properties": "^0.37.0",
     "stylelint-config-tailwindcss": "^1.0.1"
   },
   "devDependencies": {

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

@@ -11,7 +11,10 @@ const {
   parseLengthToken,
   toPx,
 } = require('../../utils/length');
-const { buildScaleOptions } = require('../../utils/options');
+const {
+  buildScaleOptions,
+  validateNoOffscaleTransformSecondaryOptions,
+} = require('../../utils/options');
 const {
   declarationValueIndex,
   isMathFunction,
@@ -54,6 +57,15 @@ const ruleFunction = (primary, secondaryOptions) => {
       return;
     }
 
+    const validSecondaryOptions = validateNoOffscaleTransformSecondaryOptions(
+      result,
+      ruleName,
+      secondaryOptions,
+    );
+    if (!validSecondaryOptions) {
+      return;
+    }
+
     const options = buildScaleOptions(secondaryOptions);
     if (options.invalidPreset) {
       stylelint.utils.report({

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

@@ -8,7 +8,10 @@ const {
   parseLengthToken,
   toPx,
 } = require('../../utils/length');
-const { buildTokenOptions } = require('../../utils/options');
+const {
+  buildTokenOptions,
+  validatePreferTokenSecondaryOptions,
+} = require('../../utils/options');
 const {
   createTokenRegex,
   declarationValueIndex,
@@ -53,6 +56,15 @@ const ruleFunction = (primary, secondaryOptions) => {
       return;
     }
 
+    const validSecondaryOptions = validatePreferTokenSecondaryOptions(
+      result,
+      ruleName,
+      secondaryOptions,
+    );
+    if (!validSecondaryOptions) {
+      return;
+    }
+
     const options = buildTokenOptions(secondaryOptions);
     if (options.invalidPreset) {
       stylelint.utils.report({

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

@@ -11,7 +11,10 @@ const {
   parseLengthToken,
   toPx,
 } = require('../../utils/length');
-const { buildScaleOptions } = require('../../utils/options');
+const {
+  buildScaleOptions,
+  validateUseScaleSecondaryOptions,
+} = require('../../utils/options');
 const {
   createTokenRegex,
   declarationValueIndex,
@@ -122,6 +125,15 @@ const ruleFunction = (primary, secondaryOptions) => {
       return;
     }
 
+    const validSecondaryOptions = validateUseScaleSecondaryOptions(
+      result,
+      ruleName,
+      secondaryOptions,
+    );
+    if (!validSecondaryOptions) {
+      return;
+    }
+
     const options = buildScaleOptions(secondaryOptions);
     if (options.invalidPreset) {
       stylelint.utils.report({

package/src/utils/options.js

@@ -1,9 +1,12 @@
 'use strict';
 
+const stylelint = require('stylelint');
+const { all: knownCssProperties = [] } = require('known-css-properties');
 const {
   DEFAULT_IGNORE_KEYWORDS,
   SPACING_PROPERTY_PATTERNS,
 } = require('./constants');
+const { parseLengthToken } = require('./length');
 const {
   getScalePreset,
   listScalePresetNames,
@@ -11,6 +14,270 @@ const {
 } = require('../presets/scales');
 
 const DEFAULT_SCALE = getScalePreset('rhythmic-4') || [0, 4, 8, 12, 16, 24, 32];
+const VALID_UNITS = new Set(['px', 'rem', 'em']);
+const VALIDATE_ALWAYS = () => true;
+
+const supportedSpacingProperties = new Set(
+  knownCssProperties.filter((property) =>
+    SPACING_PROPERTY_PATTERNS.some((pattern) => pattern.test(property)),
+  ),
+);
+supportedSpacingProperties.add('translate-x');
+supportedSpacingProperties.add('translate-y');
+supportedSpacingProperties.add('translate-z');
+
+function isPlainObject(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value)
+  );
+}
+
+function isBoolean(value) {
+  return typeof value === 'boolean';
+}
+
+function isFinitePositiveNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isSupportedUnit(value) {
+  if (!isNonEmptyString(value)) {
+    return false;
+  }
+
+  return VALID_UNITS.has(value.trim().toLowerCase());
+}
+
+function isScaleEntry(value) {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value >= 0;
+  }
+
+  if (!isNonEmptyString(value)) {
+    return false;
+  }
+
+  const parsed = parseLengthToken(value);
+  if (!parsed || parsed.number < 0) {
+    return false;
+  }
+
+  return parsed.unit === '' || VALID_UNITS.has(parsed.unit);
+}
+
+function isPropertyPatternEntry(value) {
+  if (value instanceof RegExp) {
+    return true;
+  }
+
+  if (!isNonEmptyString(value)) {
+    return false;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  return supportedSpacingProperties.has(normalized);
+}
+
+function isTokenMap(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+
+  return Object.values(value).every((tokenValue) => isNonEmptyString(tokenValue));
+}
+
+function validateSecondaryOptionShapes(result, ruleName, secondaryOptions, schema) {
+  if (secondaryOptions === undefined || secondaryOptions === null) {
+    return true;
+  }
+
+  if (!isPlainObject(secondaryOptions)) {
+    return true;
+  }
+
+  let valid = true;
+
+  for (const [optionName, descriptor] of Object.entries(schema)) {
+    const optionValue = secondaryOptions[optionName];
+    if (optionValue === undefined) {
+      continue;
+    }
+
+    if (descriptor.expectsArray && !Array.isArray(optionValue)) {
+      valid = false;
+      result.warn(
+        `Invalid value ${stringifyOptionValue(optionValue)} for option "${optionName}" of rule "${ruleName}"`,
+        { stylelintType: 'invalidOption' },
+      );
+      result.stylelint.stylelintError = true;
+      continue;
+    }
+
+    if (descriptor.expectsObject && !isPlainObject(optionValue)) {
+      valid = false;
+      result.warn(
+        `Invalid value ${stringifyOptionValue(optionValue)} for option "${optionName}" of rule "${ruleName}"`,
+        { stylelintType: 'invalidOption' },
+      );
+      result.stylelint.stylelintError = true;
+    }
+  }
+
+  return valid;
+}
+
+function stringifyOptionValue(value) {
+  if (typeof value === 'string') {
+    return `"${value}"`;
+  }
+
+  return `"${JSON.stringify(value)}"`;
+}
+
+function buildPossibleOptionMap(schema) {
+  return Object.fromEntries(
+    Object.entries(schema).map(([optionName, descriptor]) => [
+      optionName,
+      [descriptor.entryValidator || VALIDATE_ALWAYS],
+    ]),
+  );
+}
+
+function validateSecondaryOptions({
+  result,
+  ruleName,
+  secondaryOptions,
+  schema,
+  possibleOptionMap,
+}) {
+  const validOptions = stylelint.utils.validateOptions(result, ruleName, {
+    actual: secondaryOptions,
+    optional: true,
+    possible: possibleOptionMap,
+  });
+  const validShapes = validateSecondaryOptionShapes(
+    result,
+    ruleName,
+    secondaryOptions,
+    schema,
+  );
+
+  return validOptions && validShapes;
+}
+
+const SCALE_VALIDATION_SCHEMA = Object.freeze({
+  allowNegative: Object.freeze({
+    entryValidator: isBoolean,
+  }),
+  allowPercentages: Object.freeze({
+    entryValidator: isBoolean,
+  }),
+  baseFontSize: Object.freeze({
+    entryValidator: isFinitePositiveNumber,
+  }),
+  customScale: Object.freeze({
+    entryValidator: isScaleEntry,
+    expectsArray: true,
+  }),
+  enforceInsideMathFunctions: Object.freeze({
+    entryValidator: isBoolean,
+  }),
+  fixToScale: Object.freeze({
+    entryValidator: isBoolean,
+  }),
+  preset: Object.freeze({
+    entryValidator: isNonEmptyString,
+  }),
+  scale: Object.freeze({
+    entryValidator: isScaleEntry,
+    expectsArray: true,
+  }),
+  units: Object.freeze({
+    entryValidator: isSupportedUnit,
+    expectsArray: true,
+  }),
+});
+
+const USE_SCALE_VALIDATION_SCHEMA = Object.freeze({
+  ...SCALE_VALIDATION_SCHEMA,
+  ignoreValues: Object.freeze({
+    entryValidator: isNonEmptyString,
+    expectsArray: true,
+  }),
+  properties: Object.freeze({
+    entryValidator: isPropertyPatternEntry,
+    expectsArray: true,
+  }),
+  tokenFunctions: Object.freeze({
+    entryValidator: isNonEmptyString,
+    expectsArray: true,
+  }),
+  tokenPattern: Object.freeze({
+    entryValidator: isNonEmptyString,
+  }),
+});
+
+const NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA = Object.freeze({
+  ...SCALE_VALIDATION_SCHEMA,
+});
+
+const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
+  allowNumericScale: Object.freeze({
+    entryValidator: isBoolean,
+  }),
+  baseFontSize: Object.freeze({
+    entryValidator: isFinitePositiveNumber,
+  }),
+  customScale: Object.freeze({
+    entryValidator: isScaleEntry,
+    expectsArray: true,
+  }),
+  enforceInsideMathFunctions: Object.freeze({
+    entryValidator: isBoolean,
+  }),
+  ignoreValues: Object.freeze({
+    entryValidator: isNonEmptyString,
+    expectsArray: true,
+  }),
+  preset: Object.freeze({
+    entryValidator: isNonEmptyString,
+  }),
+  properties: Object.freeze({
+    entryValidator: isPropertyPatternEntry,
+    expectsArray: true,
+  }),
+  scale: Object.freeze({
+    entryValidator: isScaleEntry,
+    expectsArray: true,
+  }),
+  tokenFunctions: Object.freeze({
+    entryValidator: isNonEmptyString,
+    expectsArray: true,
+  }),
+  tokenMap: Object.freeze({
+    entryValidator: isTokenMap,
+    expectsObject: true,
+  }),
+  tokenPattern: Object.freeze({
+    entryValidator: isNonEmptyString,
+  }),
+});
+
+const USE_SCALE_POSSIBLE_OPTIONS = Object.freeze(
+  buildPossibleOptionMap(USE_SCALE_VALIDATION_SCHEMA),
+);
+const NO_OFFSCALE_TRANSFORM_POSSIBLE_OPTIONS = Object.freeze(
+  buildPossibleOptionMap(NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA),
+);
+const PREFER_TOKEN_POSSIBLE_OPTIONS = Object.freeze(
+  buildPossibleOptionMap(PREFER_TOKEN_VALIDATION_SCHEMA),
+);
 
 function buildScaleOptions(rawOptions) {
   const options = rawOptions || {};
@@ -87,7 +354,40 @@ function buildTokenOptions(rawOptions) {
   };
 }
 
+function validateUseScaleSecondaryOptions(result, ruleName, secondaryOptions) {
+  return validateSecondaryOptions({
+    result,
+    ruleName,
+    secondaryOptions,
+    schema: USE_SCALE_VALIDATION_SCHEMA,
+    possibleOptionMap: USE_SCALE_POSSIBLE_OPTIONS,
+  });
+}
+
+function validateNoOffscaleTransformSecondaryOptions(result, ruleName, secondaryOptions) {
+  return validateSecondaryOptions({
+    result,
+    ruleName,
+    secondaryOptions,
+    schema: NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA,
+    possibleOptionMap: NO_OFFSCALE_TRANSFORM_POSSIBLE_OPTIONS,
+  });
+}
+
+function validatePreferTokenSecondaryOptions(result, ruleName, secondaryOptions) {
+  return validateSecondaryOptions({
+    result,
+    ruleName,
+    secondaryOptions,
+    schema: PREFER_TOKEN_VALIDATION_SCHEMA,
+    possibleOptionMap: PREFER_TOKEN_POSSIBLE_OPTIONS,
+  });
+}
+
 module.exports = {
   buildScaleOptions,
   buildTokenOptions,
+  validateNoOffscaleTransformSecondaryOptions,
+  validatePreferTokenSecondaryOptions,
+  validateUseScaleSecondaryOptions,
 };