stylelint-plugin-rhythmguard 3.12.0 → 3.13.0

package/src/audit/render-text.js

@@ -22,6 +22,7 @@ function renderText(report) {
     ...(report.scanned && report.scanned.scssFiles > 0 ? [`  SCSS files scanned       ${String(report.scanned.scssFiles - report.scanned.scssSkipped).padStart(4)}`] : []),
     ...(report.scanned && report.scanned.scssSkipped > 0 ? [`  SCSS files skipped       ${String(report.scanned.scssSkipped).padStart(4)}  (install postcss-scss to audit them)`] : []),
     ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`  Ignored by .stylelintignore ${String(report.scanned.stylelintIgnored).padStart(4)}  (not audited)`] : []),
+    ...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [`  Links not followed       ${String(report.scanned.linksOutsideRoot).padStart(4)}  (they point outside the scanned directory)`] : []),
     ...(parseErrors(report).length > 0 ? [`  Parse errors             ${String(parseErrors(report).length).padStart(4)}  (not audited)`] : []),
     `  Files with issues        ${String(report.filesWithIssues).padStart(4)}`,
     `  Scale cleanliness        ${scoreBar(report.scaleCleanliness)}  ${report.scaleCleanliness}%`,

package/src/audit/render-utils.js

@@ -20,8 +20,33 @@ function truncate(value, maxLength) {
   return `…${value.slice(value.length - maxLength + 1)}`;
 }
 
+/** Plain Markdown text, safe in a table cell: pipes and backticks escaped, one line. */
 function escapeMarkdown(value) {
-  return String(value).replace(/\|/g, '\\|').replace(/`/g, '\\`');
+  return String(value).replace(/\r?\n/g, ' ').replace(/\|/g, '\\|').replace(/`/g, '\\`');
+}
+
+/**
+ * A Markdown code span holding `value` verbatim. A backslash does not escape
+ * anything inside a code span, so a backtick in the value is kept by a fence
+ * one backtick longer than the longest run in it, padded with a space when the
+ * value starts or ends with a backtick (CommonMark strips one space from each
+ * side). In a table cell a pipe is still escaped, as GFM reads `\|` before it
+ * finds code spans (#285).
+ */
+function markdownCode(value, { table = false } = {}) {
+  let text = String(value).replace(/\r?\n/g, ' ');
+  if (table) {
+    text = text.replace(/\|/g, '\\|');
+  }
+  const longestRun = Math.max(0, ...(text.match(/`+/g) || []).map((run) => run.length));
+  const fence = '`'.repeat(longestRun + 1);
+  const pad = /^`|`$/.test(text) || (/^ /.test(text) && / $/.test(text) && text.trim() !== '') ? ' ' : '';
+  return `${fence}${pad}${text}${pad}${fence}`;
+}
+
+/** markdownCode for a table cell. */
+function tableCode(value) {
+  return markdownCode(value, { table: true });
 }
 
 function escapeHtml(value) {
@@ -36,6 +61,8 @@ module.exports = {
   escapeHtml,
   escapeMarkdown,
   histBar,
+  markdownCode,
+  tableCode,
   scoreBar,
   truncate,
 };

package/src/audit/report.js

@@ -24,6 +24,7 @@ const {
   inferScaleFromDefinitions,
   scaleFromDefinitions,
 } = require('../core/scale-inference');
+const { buildGroupScales } = require('../core/options');
 const { applyDecisions, buildDecisionPlan } = require('./decisions');
 const { collectDeclarations, resolveTokenChains, toChainsContract } = require('./token-chains');
 const { resolveTokenLadders, toLaddersContract } = require('./token-ladders');
@@ -53,11 +54,15 @@ async function createAuditReport(options) {
     ? tokenSourceResult
     : parseTokenSources({ baseFontSize: parsed.baseFontSize, sources: parsed.tokenSources, tokenKind: 'spacing' });
 
+  // A spacing scale in audit.scales is the one use-scale checks spacing
+  // against, so it is the scale the report names and prefer-token reads (#283).
+  const groupScales = buildGroupScales(parsed.scales);
+  const spacingOverride = groupScales.spacing && Array.isArray(groupScales.spacing.scale) ? groupScales.spacing.scale : null;
   const scale = resolveAuditScale({
     baseFontSize: parsed.baseFontSize,
     cssFiles,
     readSource,
-    requested: parsed.scale,
+    requested: spacingOverride || parsed.scale,
     tokenSourceResult: spacingSourceResult,
   });
 
@@ -96,6 +101,7 @@ async function createAuditReport(options) {
     dir: parsed.dir,
     externalTokenDefinitions: tokenSourceResult.definitions,
     includeMotion: parsed.includeMotion,
+    linksOutsideRoot: scanFiles.linksOutsideRoot || [],
     motionFindings,
     parseErrorFindings,
     readSource,
@@ -133,6 +139,7 @@ async function createAuditReport(options) {
   report.decisionPlan = buildDecisionPlan({
     baseFontSize: parsed.baseFontSize,
     decisions: parsed.decisions || [],
+    groupScales,
     offScaleFindings: [
       ...stylelintFindings.filter((finding) => finding.type === 'off-scale'),
       ...collectTailwindFindings(templateFiles, lintOptions),
@@ -269,7 +276,12 @@ function resolveAuditScale({ baseFontSize, cssFiles, readSource = readSourceFrom
   return { files: [], ...(rejected ? { rejected } : {}), source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
 }
 
-function normalizeCreateAuditOptions(options = {}) {
+function normalizeCreateAuditOptions(rawOptions) {
+  // A key set to undefined is an omitted key: it neither replaces a default nor
+  // counts as given, so the config file still applies to it (#284).
+  const options = Object.fromEntries(
+    Object.entries(rawOptions || {}).filter(([, value]) => value !== undefined),
+  );
   const parsed = {
     ...createDefaultAuditOptions(),
     ...options,

package/src/audit/scan/files.js

@@ -30,37 +30,101 @@ function assertDirectory(dir) {
   return resolvedDir;
 }
 
+/**
+ * Every stylesheet and template under `rootDir`. Symbolic links are followed
+ * when they resolve inside `rootDir`: a linked directory is walked unless it
+ * is one of the directories being walked already (a cycle), and a file
+ * reached by more than one path is scanned once, under its own path when the
+ * walk reaches it directly, else under the first linked path in sorted order
+ * (#289). A link that resolves outside `rootDir` is never followed, so the
+ * audit cannot read, and `rhythmguard fix` cannot rewrite, files outside the
+ * directory it was given; such links are returned in `linksOutsideRoot`
+ * (root-relative). A broken link is skipped.
+ */
 function walkFiles(rootDir, ignorePatterns = []) {
-  const cssFiles = [];
-  const templateFiles = [];
   const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
+  const realRoot = realPathOf(rootDir) || rootDir;
+  const found = [];
+  const linksOutsideRoot = [];
 
-  function walk(currentDir) {
+  // `realDir` is where `currentDir` really is. Below a plain directory that is
+  // its real path plus the entry name, so only a link costs a realpath call.
+  function walk(currentDir, realDir, ancestors, viaLink) {
     for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
       const fullPath = path.join(currentDir, entry.name);
       const relativePath = toPosixRelativePath(rootDir, fullPath);
+      const link = entry.isSymbolicLink();
+      let kind = entry;
+      if (link) {
+        try {
+          kind = fs.statSync(fullPath);
+        } catch {
+          continue;
+        }
+      }
 
-      if (shouldIgnorePath(relativePath, entry, ignoreMatchers)) {
+      if (shouldIgnorePath(relativePath, { isDirectory: () => kind.isDirectory(), name: entry.name }, ignoreMatchers)) {
         continue;
       }
 
-      if (entry.isDirectory()) {
-        walk(fullPath);
+      const realPath = link ? realPathOf(fullPath) : path.join(realDir, entry.name);
+      if (!realPath) {
+        continue;
+      }
+      if (link && !isPathInside(realRoot, realPath)) {
+        if (kind.isDirectory() || isCssFile(fullPath) || isTemplateFile(fullPath)) {
+          linksOutsideRoot.push(relativePath);
+        }
         continue;
       }
 
-      if (entry.isFile()) {
-        if (isCssFile(fullPath)) {
-          cssFiles.push(fullPath);
-        } else if (isTemplateFile(fullPath)) {
-          templateFiles.push(fullPath);
+      if (kind.isDirectory()) {
+        if (!ancestors.has(realPath)) {
+          walk(fullPath, realPath, new Set([...ancestors, realPath]), viaLink || link);
         }
+        continue;
+      }
+
+      if (kind.isFile() && (isCssFile(fullPath) || isTemplateFile(fullPath))) {
+        found.push({ fullPath, realPath, viaLink: viaLink || link });
       }
     }
   }
 
-  walk(rootDir);
-  return { cssFiles, templateFiles };
+  walk(rootDir, realRoot, new Set([realRoot]), false);
+
+  const chosen = new Map();
+  for (const file of found) {
+    const current = chosen.get(file.realPath);
+    if (!current || preferPath(file, current)) {
+      chosen.set(file.realPath, file);
+    }
+  }
+  const cssFiles = [];
+  const templateFiles = [];
+  for (const file of found) {
+    if (chosen.get(file.realPath) !== file) {
+      continue;
+    }
+    (isCssFile(file.fullPath) ? cssFiles : templateFiles).push(file.fullPath);
+  }
+  return { cssFiles, linksOutsideRoot: linksOutsideRoot.sort(), templateFiles };
+}
+
+// A direct path beats a linked one; between two of a kind, the first in sorted order.
+function preferPath(candidate, current) {
+  if (candidate.viaLink !== current.viaLink) {
+    return !candidate.viaLink;
+  }
+  return candidate.fullPath < current.fullPath;
+}
+
+function realPathOf(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
 }
 
 function getScanFiles(rootDir, ignorePatterns, parsed) {
@@ -87,11 +151,10 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
   // git reports the top level with symlinks resolved (/private/var on macOS);
   // compare in that form, then name files under the directory as it was given.
   const realRootDir = fs.realpathSync(rootDir);
-  const cssFiles = [];
-  const templateFiles = [];
   const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
   const seen = new Set();
-  const stagedBlobs = new Map();
+  const found = [];
+  const linksOutsideRoot = [];
 
   for (const entry of changed) {
     const realPath = path.resolve(topLevel, entry.path);
@@ -103,13 +166,18 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
       continue;
     }
 
-    if (parsed.staged) {
-      // The index entry is what gets committed: a regular file blob, whatever
-      // the working tree holds now, or whether the file is still there at all.
-      if (!REGULAR_FILE_MODES.has(entry.mode)) {
-        continue;
-      }
-    } else if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) {
+    // A staged regular file is read from its index blob: that is what gets
+    // committed, whatever the working tree holds now, or whether the file is
+    // still there at all. A staged symbolic link is followed on disk, as a
+    // changed one is in a --since run (#289).
+    const link = entry.mode === SYMLINK_MODE;
+    if (parsed.staged && !REGULAR_FILE_MODES.has(entry.mode) && !link) {
+      continue;
+    }
+    if ((!parsed.staged || link) && !isFileOnDisk(fullPath)) {
+      continue;
+    }
+    if (!isCssFile(fullPath) && !isTemplateFile(fullPath)) {
       continue;
     }
 
@@ -119,20 +187,44 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
     }
 
     seen.add(fullPath);
-    if (isCssFile(fullPath)) {
-      cssFiles.push(fullPath);
-    } else if (isTemplateFile(fullPath)) {
-      templateFiles.push(fullPath);
-    } else {
+    const fileRealPath = realPathOf(fullPath) || fullPath;
+    // A link that resolves outside the scanned directory is not followed (#289).
+    if (!isPathInside(realRootDir, fileRealPath)) {
+      linksOutsideRoot.push(relativePath);
       continue;
     }
-    if (parsed.staged) {
-      stagedBlobs.set(fullPath, entry.blob);
+    found.push({
+      blob: parsed.staged && !link ? entry.blob : null,
+      fullPath,
+      realPath: fileRealPath,
+      viaLink: link || isSymbolicLink(fullPath),
+    });
+  }
+
+  // A file changed under two paths (itself and a link to it) is scanned once.
+  const chosen = new Map();
+  for (const file of found) {
+    const current = chosen.get(file.realPath);
+    if (!current || preferPath(file, current)) {
+      chosen.set(file.realPath, file);
+    }
+  }
+  const cssFiles = [];
+  const templateFiles = [];
+  const stagedBlobs = new Map();
+  for (const file of found) {
+    if (chosen.get(file.realPath) !== file) {
+      continue;
+    }
+    (isCssFile(file.fullPath) ? cssFiles : templateFiles).push(file.fullPath);
+    if (file.blob) {
+      stagedBlobs.set(file.fullPath, file.blob);
     }
   }
 
   const result = {
     cssFiles,
+    linksOutsideRoot: linksOutsideRoot.sort(),
     scanScope: {
       changedFiles: changed.length,
       mode: parsed.staged ? 'staged' : 'since',
@@ -149,6 +241,23 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
 }
 
 const REGULAR_FILE_MODES = new Set(['100644', '100755']);
+const SYMLINK_MODE = '120000';
+
+function isFileOnDisk(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isSymbolicLink(filePath) {
+  try {
+    return fs.lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
 
 // -z prints names raw and NUL-separated: no quoting of spaces or non-ASCII
 // bytes. diff.relative is pinned off so every name is relative to the

package/src/audit/token-chains.js

@@ -28,8 +28,11 @@ const SPACING_TOKEN_NAME = /^--size(?:-|$)|(?:^--|-)(?<!letter-)(?<!word-)(?:spa
 const VAR_REFERENCE = /^var\(\s*(--[\w-]+)\s*(?:,\s*([\s\S]+))?\)$/;
 const OUTCOMES = ['on-scale', 'off-scale', 'unresolved', 'ambiguous', 'computed', 'non-length'];
 
+// Shadows are never spacing, even when `inset` is in the name (Tailwind v4 `--inset-shadow-sm`, issue #295).
+const SHADOW_TOKEN_NAME = /shadow/i;
+
 function isSpacingTokenName(token) {
-  return token.startsWith('--') && SPACING_TOKEN_NAME.test(token);
+  return token.startsWith('--') && SPACING_TOKEN_NAME.test(token) && !SHADOW_TOKEN_NAME.test(token);
 }
 
 /** Every custom property declaration the audit can see: scanned stylesheets plus external token definitions. */

package/src/audit/token-ladders.js

@@ -129,6 +129,26 @@ function sameEnd(a, b) {
   return (a === null && b === null) || (a !== null && b !== null && numbersEqual(a, b));
 }
 
+/**
+ * The ranges adjacent steps are compared on. A ladder whose every step is
+ * negative (`--space-negative-1: -4px` to `-3: -16px`) grows in magnitude, so
+ * it is compared by magnitude, its `min` end being the smaller magnitude
+ * (issue #294). A ladder that crosses zero keeps its signed order.
+ */
+function comparableSteps(steps) {
+  const negative = steps.every((step) => {
+    const ends = [step.min, step.max].filter((end) => end !== null);
+    return ends.length > 0 && ends.every((end) => end < 0);
+  });
+  if (!negative) {
+    return steps;
+  }
+  return steps.map((step) => ({
+    max: step.min === null ? null : -step.min,
+    min: step.max === null ? null : -step.max,
+  }));
+}
+
 function compareEnds(lower, upper, end, minStepPx) {
   const a = lower[end];
   const b = upper[end];
@@ -191,11 +211,12 @@ function resolveTokenLadders({ baseFontSize = 16, declarations, minStepPx = DEFA
   for (const ladder of eligible) {
     if (aliases.has(ladder)) continue;
     const steps = ladder.steps.sort((a, b) => a.rank - b.rank);
+    const compared = comparableSteps(steps);
     const problems = [];
     for (let index = 0; index < steps.length - 1; index += 1) {
       const tokens = [steps[index].token, steps[index + 1].token];
-      const atMin = compareEnds(steps[index], steps[index + 1], 'min', minStepPx);
-      const atMax = compareEnds(steps[index], steps[index + 1], 'max', minStepPx);
+      const atMin = compareEnds(compared[index], compared[index + 1], 'min', minStepPx);
+      const atMax = compareEnds(compared[index], compared[index + 1], 'max', minStepPx);
       // The same problem at both ends (always, for static steps) is one problem.
       if (atMin && atMax && atMin.type === atMax.type && atMin.difference === atMax.difference) {
         problems.push({ end: 'both', tokens, ...atMin });

package/src/cli/doctor.js

@@ -5,8 +5,19 @@ const path = require('node:path');
 const { applyAuditConfig, loadAuditConfig, resolveIgnorePatterns } = require('../audit/config');
 const { createDefaultAuditOptions } = require('../audit/shared');
 const { normalizeDecisions } = require('../core/decisions');
+const { readJsonFile } = require('../core/json');
 const { normalizeTokenSourceFormat } = require('../core/token-sources');
 
+const HELP = `Usage: rhythmguard doctor
+
+Validate the Rhythmguard setup in the current directory: Stylelint, its config,
+the rules it references, .rhythmguardrc.json, token sources and the baseline.
+Exits 1 when a check fails.
+
+Options:
+  --help        Show this help message
+`;
+
 const cwd = process.cwd();
 let issues = 0;
 
@@ -218,7 +229,7 @@ function checkRhythmguardConfig() {
 
   let parsed;
   try {
-    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    parsed = readJsonFile(configPath);
   } catch {
     fail('.rhythmguardrc.json is not valid JSON', 'Fix or remove .rhythmguardrc.json');
     return;
@@ -329,7 +340,7 @@ function checkRhythmguardBaseline(audit) {
   }
 
   try {
-    const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    const baseline = readJsonFile(baselinePath);
     if (!Array.isArray(baseline.findings)) {
       fail('baseline file does not include findings array', 'Regenerate it with rhythmguard audit --write-baseline');
       return;
@@ -341,6 +352,16 @@ function checkRhythmguardBaseline(audit) {
 }
 
 function run() {
+  // Doctor takes no arguments; --help prints the usage, anything else is refused (#286).
+  for (const arg of process.argv.slice(3)) {
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(HELP);
+      return;
+    }
+    process.stderr.write(`Unknown option: ${arg}\n\n${HELP}`);
+    process.exit(1);
+  }
+
   process.stdout.write('\nRhythmguard Doctor\n\n');
 
   const stylelintOk = checkStylelint();
@@ -364,4 +385,8 @@ function run() {
   process.exit(stylelintOk && issues === 0 ? 0 : 1);
 }
 
-run();
+module.exports = { HELP, run };
+
+if (require.main === module) {
+  run();
+}

package/src/cli/fix.js

@@ -2,10 +2,11 @@
 
 const { loadRcDecisions } = require('../core/decisions');
 const { parseLengthToken, toPx } = require('../core/length');
-const { OPTIONS: AUDIT_OPTIONS } = require('../audit/args');
+const { OPTIONS: AUDIT_OPTIONS, parseBaseFontSize } = require('../audit/args');
 const { runCodemod } = require('../audit/codemod');
 const { resolveIgnorePatterns } = require('../audit/config');
 const { normalizeCreateAuditOptions } = require('../audit/report');
+const { assertDirectory } = require('../audit/scan/files');
 const { DEFAULT_IGNORE_PATH } = require('../audit/shared');
 
 // --ignore and --ignore-path are the audit's own flags, parsed by the audit's table.
@@ -62,14 +63,11 @@ function parseArgs(argv) {
     else if (arg.startsWith('--to=')) parsed.replacement = arg.slice('--to='.length);
     else if (arg === '--properties') parsed.properties = splitList(next());
     else if (arg.startsWith('--properties=')) parsed.properties = splitList(arg.slice('--properties='.length));
-    else if (arg === '--base-font-size') parsed.baseFontSize = Number(next());
-    else if (arg.startsWith('--base-font-size=')) parsed.baseFontSize = Number(arg.slice('--base-font-size='.length));
+    else if (arg === '--base-font-size') parsed.baseFontSize = parseBaseFontSize(next());
+    else if (arg.startsWith('--base-font-size=')) parsed.baseFontSize = parseBaseFontSize(arg.slice('--base-font-size='.length));
     else if (!arg.startsWith('-') && !parsed.dir) parsed.dir = arg;
     else throw new Error(`Unknown option: ${arg}`);
   }
-  if (!Number.isFinite(parsed.baseFontSize) || parsed.baseFontSize <= 0) {
-    throw new Error('--base-font-size must be a positive number.');
-  }
   return parsed;
 }
 
@@ -138,6 +136,9 @@ function run() {
   let plan;
   let ignorePatterns;
   try {
+    // The same check, and the same message, as the audit: a missing path or a
+    // file reads "Directory not found" or "Not a directory", not a stack trace (#288).
+    assertDirectory(parsed.dir);
     plan = plannedReplacements(parsed);
     ignorePatterns = auditIgnorePatterns(parsed);
   } catch (error) {

package/src/cli/index.js

@@ -15,7 +15,7 @@ Commands:
   doctor        Validate your Rhythmguard setup
 
 Options:
-  --help        Show this help message
+  --help        Show this help message; after a command, that command's help
 
 Examples:
   npx rhythmguard
@@ -45,7 +45,7 @@ function main() {
   } else if (command === 'init') {
     require('./init').run();
   } else if (command === 'doctor') {
-    require('./doctor');
+    require('./doctor').run();
   } else {
     process.stderr.write(`Unknown command: ${command}\n\n`);
     process.stdout.write(HELP);

package/src/cli/init.js

@@ -200,14 +200,39 @@ const AGENT_TARGETS = {
 const AGENT_BLOCK_START = '<!-- rhythmguard:agents:start -->';
 const AGENT_BLOCK_END = '<!-- rhythmguard:agents:end -->';
 
+const HELP = `Usage: rhythmguard init [options]
+
+Scaffold a Rhythmguard Stylelint config for the project in the current
+directory. Detects Tailwind and Next.js, picks a profile and asks before it
+writes. When Stylelint loads a config init cannot rewrite (package.json, YAML,
+JS or TS), it prints what to add and writes nothing.
+
+Options:
+  --agents [claude|cursor|copilot|all]  Install the agent instruction packs instead (default: all)
+  --help                                Show this help message
+`;
+
+/**
+ * Init writes files, so anything it does not know stops it: `init --help`
+ * and a typo such as `--agnets` used to fall through to the interactive
+ * init and write a config (#286).
+ */
 function parseInitArgs(argv) {
-  const parsed = { agents: null };
+  const parsed = { agents: null, help: false };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === '--agents') {
-      parsed.agents = String(argv[++index] || 'all').toLowerCase();
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else if (arg === '--agents') {
+      const next = argv[index + 1];
+      parsed.agents = next !== undefined && !next.startsWith('-') ? argv[++index].toLowerCase() : 'all';
     } else if (arg.startsWith('--agents=')) {
       parsed.agents = arg.slice('--agents='.length).toLowerCase();
+      if (!parsed.agents) {
+        throw new Error('Missing value for --agents.');
+      }
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
     }
   }
   return parsed;
@@ -252,7 +277,18 @@ function installAgents(selection, cwd = process.cwd()) {
 }
 
 async function run() {
-  const args = parseInitArgs(process.argv.slice(3));
+  let args;
+  try {
+    args = parseInitArgs(process.argv.slice(3));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\n${HELP}`);
+    process.exit(1);
+  }
+
+  if (args.help) {
+    process.stdout.write(HELP);
+    return;
+  }
 
   if (args.agents) {
     let written;
@@ -342,7 +378,7 @@ async function run() {
   }
 }
 
-module.exports = { AGENT_TARGETS, detect, findActiveStylelintConfig, installAgents, run, selectProfile };
+module.exports = { AGENT_TARGETS, HELP, detect, findActiveStylelintConfig, installAgents, parseInitArgs, run, selectProfile };
 
 if (require.main === module) {
   run();