stylelint-plugin-rhythmguard 2.0.1 → 2.2.0

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,255 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseLengthToken, toPx } = require('./length');
+const { buildEffectiveTokenMap } = require('./token-map');
+const { 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();
+
+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),
+    };
+  }
+
+  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}|${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' });
+  const keys = [];
+  for (const definition of parsed.definitions.values()) {
+    keys.push(...definition.normalizedValues);
+  }
+
+  const scale = pxValuesFromKeys(keys, baseFontSize);
+  const outcome = scale.length >= MIN_INFERRED_SCALE_LENGTH
+    ? {
+      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);
+}
+
+function scaleFromTokenMap(map, baseFontSize) {
+  const keys = [];
+  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);
+    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: [] };
+    }
+  }
+
+  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,
+  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-sources.js

@@ -31,7 +31,8 @@ const TOKEN_KIND_PATTERNS = Object.freeze({
   radius: /^--radius-/,
   motion: /^--(?:motion|duration|delay|ease|easing)-/,
   size: /^--(?:size|width|height|container)-/,
-  spacing: /^--(?:space|spacing)-/,
+  // Anchored or prefixed (--spacing-4, --lb-spacing-md, bare Tailwind v4 --spacing), never letter-/word-spacing.
+  spacing: /(?:^--|-)(?<!letter-)(?<!word-)(?:space|spacing)(?:-|$)/,
   typography: /^--(?:font|font-size|line-height|leading|tracking|typography)-/,
 });
 
@@ -377,6 +378,34 @@ function addDefinition(definitions, {
   definitions.set(token, entry);
 }
 
+const CALC_LENGTH_TIMES_VAR = /^calc\(\s*(-?[\d.]+(?:px|rem|em)?)\s*\*\s*var\([^()]*\)\s*\)$/i;
+const CALC_VAR_TIMES_LENGTH = /^calc\(\s*var\([^()]*\)\s*\*\s*(-?[\d.]+(?:px|rem|em)?)\s*\)$/i;
+
+/**
+ * Parse the length a token value carries. Accepts plain lengths and the
+ * `calc(<length> * var(--factor))` form design systems use for scaling
+ * (Radix Themes: `--space-1: calc(4px * var(--scaling))`).
+ */
+function parseTokenValueLength(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  const direct = parseLengthToken(trimmed);
+  if (direct) {
+    return direct;
+  }
+
+  const match = trimmed.match(CALC_LENGTH_TIMES_VAR) || trimmed.match(CALC_VAR_TIMES_LENGTH);
+  if (!match) {
+    return null;
+  }
+
+  const inner = parseLengthToken(match[1]);
+  return inner ? { ...inner, raw: trimmed } : null;
+}
+
 function getNormalizedValueKeys(value, baseFontSize = 16) {
   if (value === null || value === undefined) {
     return [];
@@ -388,7 +417,7 @@ function getNormalizedValueKeys(value, baseFontSize = 16) {
   }
 
   const keys = new Set([raw]);
-  const parsed = parseLengthToken(raw);
+  const parsed = parseTokenValueLength(raw);
   if (!parsed) {
     return Array.from(keys);
   }
@@ -417,4 +446,5 @@ module.exports = {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
   parseTokenSources,
+  parseTokenValueLength,
 };

package/types/__checks__/consumer.ts

@@ -0,0 +1,80 @@
+/**
+ * Compile-time consumer of the public declarations.
+ * `npm run typecheck` fails if any published export or type drifts.
+ * Nothing here runs; it only has to type-check.
+ */
+import plugin, { audit, configs, eslint, presets, rules } from 'stylelint-plugin-rhythmguard';
+import type {
+  AuditContractReport,
+  AuditReport,
+  RhythmguardRuleOptions,
+  RhythmguardStylelintConfig,
+} from 'stylelint-plugin-rhythmguard';
+import { createAuditReport, toAuditContractReport } from 'stylelint-plugin-rhythmguard/audit';
+import eslintPlugin from 'stylelint-plugin-rhythmguard/eslint';
+import { getScalePreset, listScalePresetNames } from 'stylelint-plugin-rhythmguard/presets';
+import recommended from 'stylelint-plugin-rhythmguard/configs/recommended';
+import embed from 'stylelint-plugin-rhythmguard/configs/embed';
+import reactTailwind from 'stylelint-plugin-rhythmguard/configs/react-tailwind';
+import useScale, { ruleName as useScaleName } from 'stylelint-plugin-rhythmguard/rules/use-scale';
+
+const pluginConfigs: readonly RhythmguardStylelintConfig[] = [
+  plugin.configs.recommended,
+  plugin.configs.strict,
+  plugin.configs.tailwind,
+  plugin.configs.expanded,
+  plugin.configs.logical,
+  plugin.configs.migration,
+  plugin.configs.motion,
+  plugin.configs['react-tailwind'],
+  configs.recommended,
+  plugin.configs.embed,
+  embed,
+  recommended,
+  reactTailwind,
+];
+
+const ruleOptions: RhythmguardRuleOptions = {
+  preset: 'rhythmic-4',
+  scale: [0, 4, 8, 12, 16],
+  tokenMap: { '4px': 'var(--space-1)' },
+  tokenMapFromCssCustomProperties: true,
+};
+
+const autoScaleOptions: RhythmguardRuleOptions = {
+  scale: 'auto',
+  scaleSources: ['./tokens.json', { path: './theme.css', format: 'css' }],
+  tailwindConfigPath: './tailwind.config.mjs',
+};
+
+const useScaleRule = rules['rhythmguard/use-scale'];
+const fixable: boolean | undefined = useScaleRule.meta.fixable;
+const docUrl: string | undefined = useScale.meta.url;
+const name: string = useScaleName;
+
+const presetNames: string[] = listScalePresetNames();
+const preset = getScalePreset('rhythmic-4');
+const presetsAgain: string[] = presets.listScalePresetNames();
+
+const eslintRule = eslint.rules['tailwind-class-use-scale'];
+const eslintRuleAgain = eslintPlugin.rules['tailwind-class-use-motion-scale'];
+
+async function runAudit(): Promise<AuditContractReport> {
+  const report: AuditReport = await createAuditReport({ dir: './src', noConfig: true });
+  const viaPlugin: AuditReport = await audit.createAuditReport({ dir: './src' });
+  void viaPlugin;
+  return toAuditContractReport(report);
+}
+
+void pluginConfigs;
+void ruleOptions;
+void autoScaleOptions;
+void fixable;
+void docUrl;
+void name;
+void presetNames;
+void preset;
+void presetsAgain;
+void eslintRule;
+void eslintRuleAgain;
+void runAudit;

package/types/audit.d.ts

@@ -23,22 +23,29 @@ export interface AuditTokenSource {
 export interface AuditOptions {
   baseFontSize?: number;
   baselinePath?: string;
-  config?: string;
+  /** Path to a `.rhythmguardrc.json`-style config. Defaults to `.rhythmguardrc.json` in `cwd`. */
+  configPath?: string;
   dir?: string;
   failOnNewDrift?: boolean;
-  format?: "json" | "json-v1" | "markdown" | "text" | "html";
+  format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github";
   ignorePath?: string;
   ignorePatterns?: string[];
   includeMotion?: boolean;
   maxFindings?: number;
   minCleanliness?: number;
-  output?: string;
-  scale?: Array<number | string>;
+  /** Skip config discovery entirely (equivalent to `--no-config`). */
+  noConfig?: boolean;
+  /** Write rendered output to this file instead of stdout (equivalent to `--output`). */
+  outputPath?: string;
+  /** Explicit scale values, or `"auto"` to infer from token sources, then scanned CSS, then the default. */
+  scale?: Array<number | string> | "auto";
   since?: string;
   sinceBaseline?: boolean;
   staged?: boolean;
   tokenCandidateMinCount?: number;
   tokenKind?: AuditTokenKind;
+  /** Format applied to `tokenSources` entries that do not declare their own. */
+  tokenSourceFormat?: AuditTokenSourceFormat | "auto";
   tokenSources?: AuditTokenSource[];
   writeBaseline?: boolean;
 }
@@ -81,8 +88,19 @@ export interface AuditBaselineComparison {
   [key: string]: unknown;
 }
 
+export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-sources";
+
+export interface AuditScale {
+  /** Files the scale was derived from (token sources or scanned stylesheets). Empty for explicit, default and fallback. */
+  files: string[];
+  source: AuditScaleSource;
+  tokenCount: number;
+  values: Array<number | string>;
+}
+
 export interface AuditReport {
   baseline?: AuditBaselineComparison | null;
+  scale?: AuditScale | null;
   config?: string | null;
   directory: string;
   findings: {
@@ -106,8 +124,11 @@ export interface AuditContractReport {
     motion?: unknown;
     scale: {
       cleanliness?: unknown;
+      files: string[];
       offScaleValues?: unknown;
+      source: AuditScaleSource;
       tokenOpportunities?: unknown;
+      values: Array<number | string> | null;
     };
     tokens?: unknown;
   };

package/types/index.d.ts

@@ -14,6 +14,7 @@ export type {
   RhythmguardRuleOptions,
   RhythmguardStylelintConfig,
   ScalePresetMetadata,
+  ScaleSource,
   ScaleValue,
 } from "./shared";
 export type {
@@ -22,6 +23,8 @@ export type {
   AuditFinding,
   AuditOptions,
   AuditReport,
+  AuditScale,
+  AuditScaleSource,
   AuditScanned,
   AuditSummary,
   AuditTokenKind,
@@ -35,10 +38,12 @@ export type { StylelintRuleModule } from "./rule";
 export interface RhythmguardPlugin extends Array<StylelintRuleModule> {
   audit: typeof auditApi;
   configs: {
+    embed: RhythmguardStylelintConfig;
     expanded: RhythmguardStylelintConfig;
     logical: RhythmguardStylelintConfig;
     migration: RhythmguardStylelintConfig;
     motion: RhythmguardStylelintConfig;
+    "react-tailwind": RhythmguardStylelintConfig;
     recommended: RhythmguardStylelintConfig;
     strict: RhythmguardStylelintConfig;
     tailwind: RhythmguardStylelintConfig;

package/types/shared.d.ts

@@ -2,13 +2,34 @@ export type ScaleValue = number | string;
 
 export type RuleSeverity = boolean | "always" | "never";
 
+export interface ScaleSource {
+  /** Directory that a relative `path` resolves from. Defaults to the working directory. */
+  baseDir?: string;
+  /** Alias for `path`. */
+  file?: string;
+  /** `auto` (default), `css`, `flat-json`, `style-dictionary`, or `dtcg`. */
+  format?: string;
+  path?: string;
+}
+
 export interface RhythmguardRuleOptions {
+  /** Exempt non-zero lengths of one CSS pixel or less (1px, -1px, 0.5px, 0.0625rem). Default true. */
+  allowHairlines?: boolean;
   baseFontSize?: number;
   customScale?: ScaleValue[];
   includeMathFunctions?: boolean;
   preset?: string;
   properties?: Array<string | RegExp>;
-  scale?: ScaleValue[];
+  /**
+   * Allowed values, or `"auto"` to infer the scale from spacing tokens: `scaleSources`,
+   * then `.rhythmguardrc.json` audit token sources, then the linted stylesheet's custom
+   * properties, then `tailwindConfigPath`, falling back to the `rhythmic-4` preset.
+   */
+  scale?: ScaleValue[] | "auto";
+  /** Token files consulted first when `scale` is `"auto"`. */
+  scaleSources?: Array<string | ScaleSource>;
+  /** Tailwind v3 config whose `theme.spacing` feeds `scale: "auto"` and `tokenMapFromTailwindSpacing`. */
+  tailwindConfigPath?: string;
   tokenMap?: Record<string, string>;
   tokenMapFile?: string;
   tokenMapFromCssCustomProperties?: boolean;