stylelint-plugin-rhythmguard 3.12.0 → 3.13.0

package/src/cli/quickstart.js

@@ -16,6 +16,16 @@ const { createAuditReport } = require('../audit/report');
 const { detect } = require('./init');
 const { discoverTokenPackages } = require('../core/scale-inference');
 
+const HELP = `Usage: rhythmguard [quickstart]
+
+Zero-config first run. Detects the stack and token files, infers the spacing
+scale, audits the current directory, prints a config to paste and the audit
+commands that reproduce its result. Never fails on findings; this is a report.
+
+Options:
+  --help        Show this help message
+`;
+
 const TOKEN_FILE_PATTERN = /(^|[.-])tokens?\.json$/i;
 const TOKEN_DIRS = ['tokens', 'design-tokens', path.join('src', 'tokens'), path.join('dist', 'tokens')];
 const MAX_LISTED = 5;
@@ -116,6 +126,26 @@ function eslintSnippet(scaleValues) {
   ].join('\n');
 }
 
+function shellQuote(value) {
+  return /^[\w./@%+=:,-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * The commands to run next. The audit commands pass what quickstart passed,
+ * `--scale auto` and the token files it read, so they report the same scale
+ * and the same findings; `audit .` alone would use the default scale (#287).
+ */
+function nextCommands(tokenSources) {
+  const audit = ['npx rhythmguard audit .', '--scale auto', ...tokenSources.map((file) => `--token-source ${shellQuote(toPosix(file))}`)].join(' ');
+  // Each note on its own line above its command, so a long command copies whole.
+  return [
+    ['Lint with the config above:', 'npx stylelint "**/*.css"'],
+    ['PR-ready report:', `${audit} --format markdown`],
+    ['Then gate only new drift in CI, with the same flags:', `${audit} --write-baseline`],
+    ['Check the setup:', 'npx rhythmguard doctor'],
+  ].flatMap(([note, command]) => [note, `  ${command}`]);
+}
+
 function describeScale(scale) {
   if (!scale) {
     return 'default';
@@ -125,6 +155,17 @@ function describeScale(scale) {
 }
 
 async function run() {
+  // `rhythmguard` alone has no arguments; `rhythmguard quickstart` may have --help (#286).
+  for (const arg of process.argv[2] === 'quickstart' ? process.argv.slice(3) : []) {
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(HELP);
+      return;
+    }
+    process.stderr.write(`Unknown option: ${arg}\n\n${HELP}`);
+    process.exitCode = 1;
+    return;
+  }
+
   const cwd = process.cwd();
   const pkg = readPackage(cwd);
   const stack = detect();
@@ -144,14 +185,14 @@ async function run() {
   out.push(`    .rhythmguardrc  ${rcPresent ? 'present (its token sources are used)' : 'none'}`);
   out.push('');
 
+  // With an rc file its token sources are used; otherwise the token files found here.
+  const auditTokenSources = rcPresent ? [] : tokenFiles;
   let report;
   try {
     report = await createAuditReport({
       dir: '.',
       scale: 'auto',
-      ...(tokenFiles.length > 0 && !rcPresent
-        ? { tokenSources: tokenFiles }
-        : {}),
+      ...(auditTokenSources.length > 0 ? { tokenSources: auditTokenSources } : {}),
     });
   } catch (error) {
     process.stderr.write(`Quickstart could not audit ${cwd}: ${error.message}\n`);
@@ -228,13 +269,10 @@ async function run() {
   }
 
   out.push('  Next');
-  out.push('    npx stylelint "**/*.css"                      lint with the config above');
-  out.push('    npx rhythmguard audit . --format markdown     PR-ready report');
-  out.push('    npx rhythmguard audit . --write-baseline      then gate only new drift in CI');
-  out.push('    npx rhythmguard doctor                        check the setup');
+  out.push(...nextCommands(auditTokenSources).map((line) => `    ${line}`));
   out.push('');
 
   process.stdout.write(`${out.join('\n')}\n`);
 }
 
-module.exports = { eslintSnippet, findTokenFiles, run, suggestedStylelintConfig, tailwindMajor };
+module.exports = { HELP, eslintSnippet, findTokenFiles, nextCommands, run, suggestedStylelintConfig, tailwindMajor };

package/src/configs/embed.js

@@ -9,6 +9,8 @@
  * No `extends`, no dependency beyond this plugin, and the shape is frozen for
  * the life of a major version so a config that embeds it never changes
  * behaviour on a minor bump.
+ *
+ * @type {import('../../types/shared').RhythmguardStylelintConfig}
  */
 module.exports = {
   plugins: ['stylelint-plugin-rhythmguard'],

package/src/configs/motion.js

@@ -1,5 +1,6 @@
 'use strict';
 
+/** @type {import('../../types/shared').RhythmguardStylelintConfig} */
 module.exports = {
   plugins: ['stylelint-plugin-rhythmguard'],
   rules: {

package/src/configs/recommended.js

@@ -1,5 +1,6 @@
 'use strict';
 
+/** @type {import('../../types/shared').RhythmguardStylelintConfig} */
 module.exports = {
   plugins: ['stylelint-plugin-rhythmguard'],
   rules: {

package/src/configs/strict.js

@@ -1,5 +1,6 @@
 'use strict';
 
+/** @type {import('../../types/shared').RhythmguardStylelintConfig} */
 module.exports = {
   plugins: ['stylelint-plugin-rhythmguard'],
   rules: {

package/src/configs/tailwind.js

@@ -1,5 +1,6 @@
 'use strict';
 
+/** @type {import('../../types/shared').RhythmguardStylelintConfig} */
 module.exports = {
   extends: [
     'stylelint-config-tailwindcss',

package/src/core/decisions.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { cachedByFiles } = require('./fs-cache');
+const { readJsonFile } = require('./json');
 const { numbersEqual, parseLengthToken, toPx } = require('./length');
 
 /**
@@ -105,7 +106,7 @@ function loadRcDecisions(cwd = process.cwd(), { baseFontSize = 16 } = {}) {
     }
     let config;
     try {
-      config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
+      config = readJsonFile(rcPath);
     } catch {
       return [];
     }

package/src/core/json.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const BYTE_ORDER_MARK = /^\uFEFF/;
+
+/** Text without a leading UTF-8 byte order mark, which some Windows editors write and JSON.parse rejects (issue #291). */
+function stripBom(text) {
+  return String(text).replace(BYTE_ORDER_MARK, '');
+}
+
+/** JSON.parse for files people edit: a leading byte order mark is tolerated. */
+function parseJson(text) {
+  return JSON.parse(stripBom(text));
+}
+
+function readJsonFile(file) {
+  return parseJson(fs.readFileSync(file, 'utf8'));
+}
+
+module.exports = {
+  parseJson,
+  readJsonFile,
+  stripBom,
+};

package/src/core/length.js

@@ -224,6 +224,16 @@ function fixedLengthValue(parsedLength, nearestPx, { baseFontSize, unitStrategy,
   return converted === null ? null : formatLength(converted, unit);
 }
 
+/** " (16.8px)" after a bound written in rem or em, so the reader sees what was compared. */
+function pxAside(value, baseFontSize) {
+  const parsed = parseLengthToken(value);
+  if (!parsed || !parsed.unit || parsed.unit === 'px' || parsed.unit === '%') {
+    return '';
+  }
+  const px = toPx(Math.abs(parsed.number), parsed.unit, baseFontSize);
+  return px === null ? '' : ` (${formatLength(parsed.number < 0 ? -px : px, 'px')})`;
+}
+
 module.exports = {
   nearestText,
   fixedLengthValue,
@@ -236,6 +246,7 @@ module.exports = {
   normalizeScaleByUnit,
   numbersEqual,
   parseLengthToken,
+  pxAside,
   pxOnScale,
   toPx,
 };

package/src/core/options.js

@@ -92,8 +92,14 @@ function isAutoScaleLiteral(value) {
   return value === 'auto';
 }
 
-function isScaleEntryOrAuto(value) {
-  return isAutoScaleLiteral(value) || isScaleEntry(value);
+/** A list of scale values. An empty list checks nothing, so it is not a scale (issue #273). */
+function isScaleList(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((entry) => isScaleEntry(entry));
+}
+
+/** A name `getScalePreset` knows, built-in or community, aliases included. */
+function isKnownPresetName(value) {
+  return typeof value === 'string' && Boolean(getScalePreset(value));
 }
 
 function isScaleSourceEntry(value) {
@@ -213,9 +219,18 @@ function isMathFunctionArgumentMap(value) {
   });
 }
 
+/**
+ * A scale given as values, a preset name, or a { preset | scale | customScale }
+ * object. An empty list or an unknown preset would leave the scale empty or
+ * fall back to the default without a word, so neither is valid (issue #273).
+ */
 function isScaleOverrideEntry(value) {
   if (Array.isArray(value)) {
-    return value.every((entry) => isScaleEntry(entry));
+    return isScaleList(value);
+  }
+
+  if (typeof value === 'string') {
+    return isKnownPresetName(value);
   }
 
   if (!isPlainObject(value)) {
@@ -230,18 +245,15 @@ function isScaleOverrideEntry(value) {
     return false;
   }
 
-  if (hasPreset && !isNonEmptyString(value.preset)) {
+  if (hasPreset && !isKnownPresetName(value.preset)) {
     return false;
   }
 
-  if (hasScale && (!Array.isArray(value.scale) || !value.scale.every((entry) => isScaleEntry(entry)))) {
+  if (hasScale && !isScaleList(value.scale)) {
     return false;
   }
 
-  if (
-    hasCustomScale &&
-    (!Array.isArray(value.customScale) || !value.customScale.every((entry) => isScaleEntry(entry)))
-  ) {
+  if (hasCustomScale && !isScaleList(value.customScale)) {
     return false;
   }
 
@@ -267,13 +279,7 @@ const SCALED_GROUPS = Object.freeze(['spacing', 'radius', 'size', 'typography'])
 
 /** One group's scale: values, a preset name, "auto", or a { preset | scale | customScale } object. */
 function isGroupScaleEntry(value) {
-  if (isAutoScaleLiteral(value)) {
-    return true;
-  }
-  if (typeof value === 'string') {
-    return Boolean(getScalePreset(value));
-  }
-  return isScaleOverrideEntry(value);
+  return isAutoScaleLiteral(value) || isScaleOverrideEntry(value);
 }
 
 function isGroupScalesMap(value) {
@@ -293,7 +299,7 @@ function buildGroupScales(scales) {
     if (isAutoScaleLiteral(entry)) {
       return [group, { auto: true, scale: null }];
     }
-    const scale = typeof entry === 'string' ? getScalePreset(entry) : resolveScaleOverride(entry);
+    const scale = resolveScaleOverride(entry);
     return [group, { auto: false, scale: Array.isArray(scale) ? [...scale] : null }];
   }));
 }
@@ -302,7 +308,9 @@ function buildPossibleOptionMap(schema) {
   return Object.fromEntries(
     Object.entries(schema).map(([optionName, descriptor]) => [
       optionName,
-      [descriptor.entryValidator || VALIDATE_ALWAYS],
+      // A literal such as "auto" stands for the whole option; validateSecondaryOptionShapes
+      // rejects it inside an array (issue #273).
+      [...(descriptor.allowLiterals || []), descriptor.entryValidator || VALIDATE_ALWAYS],
     ]),
   );
 }
@@ -359,6 +367,12 @@ function resolveScaleOverride(override) {
     return override;
   }
 
+  // A preset name, as `propertyScales: { padding: "rhythmic-8" }` (issue #273).
+  if (typeof override === 'string') {
+    const preset = getScalePreset(override);
+    return preset ? [...preset] : null;
+  }
+
   if (!isPlainObject(override)) {
     return null;
   }
@@ -438,6 +452,7 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
   customScale: Object.freeze({
     entryValidator: isScaleEntry,
     expectsArray: true,
+    nonEmpty: true,
   }),
   checkMathBounds: Object.freeze({
     entryValidator: isBoolean,
@@ -467,8 +482,9 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
   }),
   scale: Object.freeze({
     allowLiterals: ['auto'],
-    entryValidator: isScaleEntryOrAuto,
+    entryValidator: isScaleEntry,
     expectsArray: true,
+    nonEmpty: true,
   }),
   scaleSources: Object.freeze({
     entryValidator: isScaleSourceEntry,
@@ -536,6 +552,7 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
   customScale: Object.freeze({
     entryValidator: isScaleEntry,
     expectsArray: true,
+    nonEmpty: true,
   }),
   checkMathBounds: Object.freeze({
     entryValidator: isBoolean,
@@ -579,8 +596,9 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
   }),
   scale: Object.freeze({
     allowLiterals: ['auto'],
-    entryValidator: isScaleEntryOrAuto,
+    entryValidator: isScaleEntry,
     expectsArray: true,
+    nonEmpty: true,
   }),
   scaleSources: Object.freeze({
     entryValidator: isScaleSourceEntry,
@@ -809,6 +827,7 @@ module.exports = {
   PREFER_TOKEN_VALIDATION_SCHEMA,
   USE_SCALE_POSSIBLE_OPTIONS,
   USE_SCALE_VALIDATION_SCHEMA,
+  buildGroupScales,
   buildScaleOptions,
   buildTokenOptions,
   SCALED_GROUPS,

package/src/core/scale-inference.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { readJsonFile } = require('./json');
 const { parseLengthToken, toPx } = require('./length');
 const { buildEffectiveTokenMap } = require('./token-map');
 const {
@@ -18,7 +19,14 @@ 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|spacer)(-|$)';
 // Tailwind v4 defines one base (`--spacing: 0.25rem`) and derives utilities by multiplying it.
-const TAILWIND_BASE_TOKENS = new Set(['--spacing', '--space']);
+// A bare `--space` is not Tailwind's; it is one token like any other (issue #293).
+const TAILWIND_BASE_TOKENS = new Set(['--spacing']);
+// A bare `--space` is a base only when the other spacing tokens do not form a
+// scale on their own. Discourse declares `--space: 0.25rem` and writes every
+// step as `calc(var(--space) * N)`, so its scale is the multiples; a ladder of
+// plain lengths (`--space-s`, `--space-m`) next to `--space` is the scale, and
+// `--space` is one more step on it (issue #293).
+const CONDITIONAL_BASE_TOKENS = new Set(['--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,
 ];
@@ -38,7 +46,7 @@ const TOKEN_PACKAGES = require('./token-packages.json').packages;
  */
 function readDirectDependencies(dir) {
   try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const pkg = readJsonFile(path.join(dir, 'package.json'));
     return new Set([
       ...Object.keys(pkg.dependencies || {}),
       ...Object.keys(pkg.devDependencies || {}),
@@ -171,13 +179,38 @@ function parseSourcesCached(sources, baseFontSize) {
   return warnings.length > 0 ? { ...parsed, warnings: [...warnings, ...parsed.warnings] } : parsed;
 }
 
+/**
+ * Token sources read for the spacing names and, when a rule sets its own
+ * `tokenPattern` (`^--space-|^--radius-`), for that pattern too, on top of the
+ * spacing names, unless a source sets its own. Fixes and scale inference read
+ * the same tokens through this (issue #296).
+ */
+function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null) {
+  const plain = parseSourcesCached(sources, baseFontSize);
+  if (!tokenPattern || !plain) {
+    return plain;
+  }
+  const withPattern = parseSourcesCached(
+    sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source })),
+    baseFontSize,
+  );
+  const definitions = new Map(plain.definitions);
+  for (const [token, definition] of withPattern ? withPattern.definitions : []) {
+    if (!definitions.has(token)) {
+      definitions.set(token, definition);
+    }
+  }
+  const warnings = Array.from(new Set([...plain.warnings, ...(withPattern ? withPattern.warnings : [])]));
+  return { definitions, sources: plain.sources, warnings };
+}
+
 /**
  * The scale a list of token sources defines, or null. Warnings from sources
  * that are missing or do not parse go into `warnings` either way, so a
  * fallback can say which source failed (issue #270).
  */
-function scaleFromSources(sources, baseFontSize, warnings = []) {
-  const parsed = parseSourcesCached(sources, baseFontSize);
+function scaleFromSources(sources, baseFontSize, warnings = [], tokenPattern = null) {
+  const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern);
   if (!parsed) {
     return null;
   }
@@ -203,16 +236,10 @@ function scaleFromSources(sources, baseFontSize, warnings = []) {
 function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenPattern = null, tokenRegex }) {
   const definitions = root ? stylesheetDefinitions(root, tokenRegex, baseFontSize) : new Map();
   const sources = [...scaleSources, ...rcTokenSources(process.cwd()).sources, ...discoverTokenPackages(process.cwd())];
-  // A rule's own tokenPattern (`^--space-|^--radius-`) also applies to the
-  // files it reads, on top of the spacing names, unless a source sets its own.
-  const withPattern = tokenPattern
-    ? sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source }))
-    : [];
-  for (const parsed of [parseSourcesCached(sources, baseFontSize), parseSourcesCached(withPattern, baseFontSize)]) {
-    for (const [token, definition] of parsed ? parsed.definitions : []) {
-      if (!definitions.has(token)) {
-        definitions.set(token, definition);
-      }
+  const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern);
+  for (const [token, definition] of parsed ? parsed.definitions : []) {
+    if (!definitions.has(token)) {
+      definitions.set(token, definition);
     }
   }
   return definitions;
@@ -252,17 +279,36 @@ function scaleFromDefinitions(definitions, baseFontSize = 16) {
 function scaleFromAllDefinitions(definitions, baseFontSize) {
   const keys = [];
   const baseKeys = [];
+  const conditionalKeys = [];
   for (const definition of definitions.values()) {
     if (TAILWIND_BASE_TOKENS.has(definition.token)) {
       baseKeys.push(...definition.normalizedValues);
       continue;
     }
+    if (CONDITIONAL_BASE_TOKENS.has(definition.token)) {
+      conditionalKeys.push(...definition.normalizedValues);
+      continue;
+    }
     keys.push(...definition.normalizedValues);
   }
-  const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
+  const scale = scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys });
   return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
 }
 
+/**
+ * The scale from plain token values, expanded by a base multiplier where one
+ * applies: `--spacing` always, a bare `--space` only when the plain values do
+ * not already form a scale (see CONDITIONAL_BASE_TOKENS).
+ */
+function scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys }) {
+  const plain = pxValuesFromKeys(keys, baseFontSize);
+  if (baseKeys.length > 0 || plain.length >= MIN_INFERRED_SCALE_LENGTH || conditionalKeys.length === 0) {
+    const withConditional = conditionalKeys.length > 0 ? pxValuesFromKeys([...keys, ...conditionalKeys], baseFontSize) : plain;
+    return expandTailwindBase(withConditional, baseKeys, baseFontSize);
+  }
+  return expandTailwindBase(plain, conditionalKeys, baseFontSize);
+}
+
 /** The scope of a declaration node: the AST-side twin of customPropertyDeclarations. */
 function scopeOfNode(decl) {
   for (let node = decl.parent; node; node = node.parent) {
@@ -302,8 +348,8 @@ function stylesheetDefinitions(root, tokenRegex, baseFontSize) {
 }
 
 /**
- * Merge Tailwind-style base multiples into a scale when a bare --spacing/--space
- * base is defined. Only the first base found is expanded: a project that ships
+ * Merge Tailwind-style base multiples into a scale when a bare --spacing base
+ * is defined. Only the first base found is expanded: a project that ships
  * several theme files with different bases (shadcn/ui) has one active base at a
  * time, and a union of ladders is a scale nobody designed (issue #89).
  */
@@ -354,7 +400,7 @@ function rcTokenSourcesUncached(rcPath) {
 
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
+    config = readJsonFile(rcPath);
   } catch (err) {
     return { sources: [], warnings: [`${RC_FILE} could not be read: ${err.message}`] };
   }
@@ -400,39 +446,47 @@ function sassTokensFromRoot(root) {
 function scaleFromTokenMap(map, baseFontSize, extraKeys = []) {
   const keys = [...extraKeys];
   const baseKeys = [];
+  const conditionalKeys = [];
   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 if (name && CONDITIONAL_BASE_TOKENS.has(name[1])) {
+      conditionalKeys.push(key);
     } else {
       keys.push(key);
     }
   }
-  const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
+  const scale = scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys });
   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.
+ * the provenance is a single file list or the stylesheet. The order, which
+ * docs/rules/use-scale.md documents: `scaleSources`, `.rhythmguardrc.json`
+ * token sources, the linted stylesheet, `tailwindConfigPath`, installed token
+ * packages, the fallback preset. `sourceTokenPattern` is the rule's own
+ * explicit `tokenPattern`, applied to the token files as fixes apply it.
  */
 function resolveAutoScale({
   baseFontSize = 16,
   root,
   scaleSources = [],
+  sourceTokenPattern = null,
   tailwindConfigPath = null,
   tokenPattern = DEFAULT_AUTO_TOKEN_PATTERN,
 } = {}) {
   // Warnings from every source tried, for the fallback note when none yields a scale.
   const warnings = [];
-  const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings);
+  const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings, sourceTokenPattern);
   if (fromOption) {
     return { source: 'scaleSources', ...fromOption };
   }
 
   const rc = rcTokenSources(process.cwd());
   warnings.push(...rc.warnings);
-  const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings);
+  const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings, sourceTokenPattern);
   if (fromRc) {
     return { source: 'rhythmguardrc', ...fromRc };
   }
@@ -473,7 +527,7 @@ function resolveAutoScale({
     }
   }
 
-  const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize, warnings);
+  const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize, warnings, sourceTokenPattern);
   if (fromPackages) {
     return { source: 'token-package', ...fromPackages };
   }
@@ -546,6 +600,7 @@ function withResolvedScale(options, root) {
       baseFontSize: options.baseFontSize,
       root,
       scaleSources: options.scaleSources,
+      sourceTokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
       tailwindConfigPath: options.tailwindConfigPath,
       tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
     });

package/src/core/tailwind-class-analysis.js

@@ -172,8 +172,9 @@ function analyzeClassToken(token, options, scalePx) {
     return null;
   }
 
-  // `-m-[16px]` and `m-[-16px]` are both negative margins (#241).
-  const negative = match.groups.utility.startsWith('-') || parsedLength.number < 0;
+  // `-m-[16px]` and `m-[-16px]` are both negative margins (#241); in
+  // `-m-[-16px]` the two signs cancel and Tailwind writes a positive margin (#277).
+  const negative = match.groups.utility.startsWith('-') !== parsedLength.number < 0;
 
   if (!options.allowNegative && negative) {
     return {

package/src/core/token-map.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { readJsonFile } = require('./json');
 const { parseTokenValueLength } = require('./token-sources');
 
 const { spawnSync } = require('node:child_process');
@@ -140,7 +141,7 @@ function mergeTokenMapFromFile({
 
   let parsed;
   try {
-    parsed = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+    parsed = readJsonFile(resolvedPath);
   } catch {
     return currentMap;
   }

package/src/core/token-sources.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { stripBom } = require('./json');
 const {
   formatLength,
   parseLengthToken,
@@ -116,7 +117,7 @@ function parseTokenSources({
 
     let text;
     try {
-      text = fs.readFileSync(normalizedSource.resolvedPath, 'utf8');
+      text = stripBom(fs.readFileSync(normalizedSource.resolvedPath, 'utf8'));
     } catch (err) {
       const warning = `Unable to read token source ${normalizedSource.displayPath}: ${err.message}`;
       sourceReport.warnings.push(warning);

package/src/eslint/index.js

@@ -3,17 +3,23 @@
 const tailwindClassUseScale = require('./rules/tailwind-class-use-scale');
 const tailwindClassUseMotionScale = require('./rules/tailwind-class-use-motion-scale');
 
-module.exports = {
+const plugin = {
   rules: {
     'tailwind-class-use-scale': tailwindClassUseScale,
     'tailwind-class-use-motion-scale': tailwindClassUseMotionScale,
   },
-  configs: {
-    recommended: {
-      rules: {
-        'rhythmguard-tailwind/tailwind-class-use-scale': 'warn',
-        'rhythmguard-tailwind/tailwind-class-use-motion-scale': 'off',
-      },
-    },
+  configs: {},
+};
+
+// A flat config that works on its own (`export default [rhythmguard.configs.recommended]`),
+// so it registers the plugin under the prefix its rules use (#279). Spreading
+// `configs.recommended.rules` into a block that registers the plugin itself still works.
+plugin.configs.recommended = {
+  plugins: { 'rhythmguard-tailwind': plugin },
+  rules: {
+    'rhythmguard-tailwind/tailwind-class-use-scale': 'warn',
+    'rhythmguard-tailwind/tailwind-class-use-motion-scale': 'off',
   },
 };
+
+module.exports = plugin;

package/src/eslint/rules/tailwind-class-use-motion-scale.js

@@ -54,6 +54,7 @@ function buildMessage(analysis, segment, lower, upper) {
 
 module.exports = {
   meta: {
+    type: 'suggestion',
     docs: {
       url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/tailwind-class-use-motion-scale.md',
       description: 'Enforce duration scale for Tailwind arbitrary motion utilities in class strings',