stylelint-plugin-rhythmguard 2.0.0 → 2.1.0

package/src/cli/init.js

@@ -4,17 +4,39 @@ const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline');
 
-function ask(question) {
+function createPrompter() {
+  if (!process.stdin.isTTY) {
+    const answers = fs.readFileSync(0, 'utf8').split(/\r?\n/);
+    let answerIndex = 0;
+
+    return {
+      ask(question) {
+        process.stdout.write(question);
+        const answer = answers[answerIndex] || '';
+        answerIndex += 1;
+        return Promise.resolve(answer.trim().toLowerCase());
+      },
+      close() {},
+    };
+  }
+
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
   });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
+
+  return {
+    ask(question) {
+      return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+          resolve(answer.trim().toLowerCase());
+        });
+      });
+    },
+    close() {
       rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
+    },
+  };
 }
 
 function detect() {
@@ -80,49 +102,55 @@ function selectProfile(stack) {
 }
 
 async function run() {
-  process.stdout.write('\nRhythmguard Init\n\n');
-
-  const stack = detect();
-
-  // Report detection
-  const detected = [];
-  if (stack.tailwind) detected.push('Tailwind CSS');
-  if (stack.nextjs) detected.push('Next.js');
-  if (detected.length > 0) {
-    process.stdout.write(`Detected: ${detected.join(', ')}\n`);
-  } else {
-    process.stdout.write('Detected: plain CSS project\n');
-  }
+  const prompter = createPrompter();
+
+  try {
+    process.stdout.write('\nRhythmguard Init\n\n');
+
+    const stack = detect();
+
+    // Report detection
+    const detected = [];
+    if (stack.tailwind) detected.push('Tailwind CSS');
+    if (stack.nextjs) detected.push('Next.js');
+    if (detected.length > 0) {
+      process.stdout.write(`Detected: ${detected.join(', ')}\n`);
+    } else {
+      process.stdout.write('Detected: plain CSS project\n');
+    }
 
-  // Warn about existing config
-  if (stack.hasExistingConfig) {
-    process.stdout.write('\n⚠ Existing Stylelint config found.\n');
-    const answer = await ask('Overwrite? (y/n) ');
+    // Warn about existing config
+    if (stack.hasExistingConfig) {
+      process.stdout.write('\n⚠ Existing Stylelint config found.\n');
+      const answer = await prompter.ask('Overwrite? (y/n) ');
+      if (answer !== 'y' && answer !== 'yes') {
+        process.stdout.write('Aborted.\n');
+        process.exit(0);
+      }
+    }
+
+    const profile = selectProfile(stack);
+    process.stdout.write(`\nProfile: ${profile}\n`);
+
+    const answer = await prompter.ask('Write .stylelintrc.json? (y/n) ');
     if (answer !== 'y' && answer !== 'yes') {
       process.stdout.write('Aborted.\n');
       process.exit(0);
     }
-  }
 
-  const profile = selectProfile(stack);
-  process.stdout.write(`\nProfile: ${profile}\n`);
+    const config = {
+      extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+    };
 
-  const answer = await ask('Write .stylelintrc.json? (y/n) ');
-  if (answer !== 'y' && answer !== 'yes') {
-    process.stdout.write('Aborted.\n');
-    process.exit(0);
-  }
+    const configPath = path.join(process.cwd(), '.stylelintrc.json');
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 
-  const config = {
-    extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
-  };
-
-  const configPath = path.join(process.cwd(), '.stylelintrc.json');
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
-
-  process.stdout.write(`\n✓ Wrote ${configPath}\n`);
-  process.stdout.write(`\nNext steps:\n`);
-  process.stdout.write(`  npx stylelint "src/**/*.css"\n\n`);
+    process.stdout.write(`\n✓ Wrote ${configPath}\n`);
+    process.stdout.write(`\nNext steps:\n`);
+    process.stdout.write(`  npx stylelint "src/**/*.css"\n\n`);
+  } finally {
+    prompter.close();
+  }
 }
 
 run();

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

@@ -76,6 +76,7 @@ function buildMessage(analysis, segment, lower, upper) {
 module.exports = {
   meta: {
     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',
     },
     fixable: 'code',

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

@@ -67,6 +67,7 @@ function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
 module.exports = {
   meta: {
     docs: {
+      url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/tailwind-class-use-scale.md',
       description: 'Enforce spacing scale for Tailwind arbitrary spacing utilities in class strings',
     },
     fixable: 'code',

package/src/index.js

@@ -22,6 +22,7 @@ module.exports.configs = {
   logical: require('./configs/logical'),
   migration: require('./configs/migration'),
   motion: require('./configs/motion'),
+  'react-tailwind': require('./configs/react-tailwind'),
 };
 module.exports.eslint = require('./eslint');
 module.exports.presets = require('./presets');

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

@@ -269,7 +269,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguardno-offscale-transform',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/no-offscale-transform.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

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

@@ -288,7 +288,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguardprefer-token',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/prefer-token.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

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

@@ -236,7 +236,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguarduse-motion-scale',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/use-motion-scale.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

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

@@ -332,7 +332,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguarduse-scale',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/use-scale.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

package/types/__checks__/consumer.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 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,
+  recommended,
+  reactTailwind,
+];
+
+const ruleOptions: RhythmguardRuleOptions = {
+  preset: 'rhythmic-4',
+  scale: [0, 4, 8, 12, 16],
+  tokenMap: { '4px': 'var(--space-1)' },
+  tokenMapFromCssCustomProperties: true,
+};
+
+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 fixable;
+void docUrl;
+void name;
+void presetNames;
+void preset;
+void presetsAgain;
+void eslintRule;
+void eslintRuleAgain;
+void runAudit;

package/types/audit.d.ts

@@ -0,0 +1,162 @@
+export type AuditTokenKind =
+  | "all"
+  | "motion"
+  | "radius"
+  | "size"
+  | "spacing"
+  | "typography";
+
+export type AuditTokenSourceFormat =
+  | "auto"
+  | "css"
+  | "dtcg"
+  | "flat-json"
+  | "style-dictionary";
+
+export interface AuditTokenSource {
+  baseDir?: string;
+  file?: string;
+  format?: AuditTokenSourceFormat;
+  path?: string;
+}
+
+export interface AuditOptions {
+  baseFontSize?: number;
+  baselinePath?: 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" | "github";
+  ignorePath?: string;
+  ignorePatterns?: string[];
+  includeMotion?: boolean;
+  maxFindings?: number;
+  minCleanliness?: number;
+  /** Skip config discovery entirely (equivalent to `--no-config`). */
+  noConfig?: boolean;
+  /** Write rendered output to this file instead of stdout (equivalent to `--output`). */
+  outputPath?: string;
+  scale?: Array<number | string>;
+  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;
+}
+
+export interface AuditSummary {
+  cleanliness: number;
+  filesWithFindings: number;
+  findingCount: number;
+  motionFindingCount?: number;
+  tokenOpportunityCount?: number;
+  [key: string]: unknown;
+}
+
+export interface AuditScanned {
+  cssFiles: number;
+  templateFiles: number;
+  totalFiles?: number;
+  [key: string]: unknown;
+}
+
+export interface AuditFinding {
+  column?: number;
+  file: string;
+  key?: string;
+  line?: number;
+  message: string;
+  property?: string;
+  rule?: string;
+  type: string;
+  value?: string;
+  [key: string]: unknown;
+}
+
+export interface AuditBaselineComparison {
+  baselineFindings: number;
+  newFindings: AuditFinding[];
+  newFindingsCount: number;
+  resolvedFindings: AuditFinding[];
+  resolvedFindingsCount: number;
+  [key: string]: unknown;
+}
+
+export interface AuditReport {
+  baseline?: AuditBaselineComparison | null;
+  config?: string | null;
+  directory: string;
+  findings: {
+    css: AuditFinding[];
+    motion: AuditFinding[];
+    tailwind: AuditFinding[];
+  };
+  scanned: AuditScanned;
+  summary: AuditSummary;
+  [key: string]: unknown;
+}
+
+export interface AuditContractReport {
+  baseline: AuditBaselineComparison | null;
+  command: {
+    config?: string | null;
+    directory: string;
+    scanScope: string;
+  };
+  contracts: {
+    motion?: unknown;
+    scale: {
+      cleanliness?: unknown;
+      offScaleValues?: unknown;
+      tokenOpportunities?: unknown;
+    };
+    tokens?: unknown;
+  };
+  findings: unknown;
+  scanned: AuditScanned;
+  schemaVersion: "2.0";
+  summary: AuditSummary;
+}
+
+export interface TokenSourceReport {
+  file: string;
+  format: AuditTokenSourceFormat;
+  requestedFormat: AuditTokenSourceFormat;
+  tokenCount: number;
+  warnings: string[];
+}
+
+export interface ParsedTokenSources {
+  definitions: Map<string, unknown>;
+  sources: TokenSourceReport[];
+  warnings: string[];
+}
+
+export const AUDIT_JSON_SCHEMA: Readonly<Record<string, unknown>>;
+
+export function createAuditReport(options?: AuditOptions): Promise<AuditReport>;
+
+export function loadAuditConfig(options?: AuditOptions): Record<string, unknown>;
+
+export function parseTokenSources(options?: {
+  baseFontSize?: number;
+  sources?: AuditTokenSource[];
+  tokenKind?: AuditTokenKind;
+}): ParsedTokenSources;
+
+export function toAuditContractReport(report: AuditReport): AuditContractReport;
+
+declare const audit: {
+  AUDIT_JSON_SCHEMA: typeof AUDIT_JSON_SCHEMA;
+  createAuditReport: typeof createAuditReport;
+  loadAuditConfig: typeof loadAuditConfig;
+  parseTokenSources: typeof parseTokenSources;
+  toAuditContractReport: typeof toAuditContractReport;
+};
+
+export default audit;

package/types/config.d.ts

@@ -0,0 +1,5 @@
+import type { RhythmguardStylelintConfig } from "./shared";
+
+declare const config: RhythmguardStylelintConfig;
+
+export default config;

package/types/eslint.d.ts

@@ -0,0 +1,10 @@
+import type { RhythmguardEslintPlugin } from "./shared";
+
+export type { EslintRuleModule, RhythmguardEslintPlugin } from "./shared";
+
+export const configs: RhythmguardEslintPlugin["configs"];
+export const rules: RhythmguardEslintPlugin["rules"];
+
+declare const plugin: RhythmguardEslintPlugin;
+
+export default plugin;

package/types/index.d.ts

@@ -0,0 +1,66 @@
+import type {
+  RhythmguardEslintPlugin,
+  RhythmguardPresets,
+  RhythmguardStylelintConfig,
+} from "./shared";
+import type * as auditApi from "./audit";
+import type { StylelintRuleModule } from "./rule";
+
+export type {
+  EslintRuleModule,
+  RhythmguardEslintPlugin,
+  RhythmguardPresets,
+  RhythmguardRuleConfig,
+  RhythmguardRuleOptions,
+  RhythmguardStylelintConfig,
+  ScalePresetMetadata,
+  ScaleValue,
+} from "./shared";
+export type {
+  AuditBaselineComparison,
+  AuditContractReport,
+  AuditFinding,
+  AuditOptions,
+  AuditReport,
+  AuditScanned,
+  AuditSummary,
+  AuditTokenKind,
+  AuditTokenSource,
+  AuditTokenSourceFormat,
+  ParsedTokenSources,
+  TokenSourceReport,
+} from "./audit";
+export type { StylelintRuleModule } from "./rule";
+
+export interface RhythmguardPlugin extends Array<StylelintRuleModule> {
+  audit: typeof auditApi;
+  configs: {
+    expanded: RhythmguardStylelintConfig;
+    logical: RhythmguardStylelintConfig;
+    migration: RhythmguardStylelintConfig;
+    motion: RhythmguardStylelintConfig;
+    "react-tailwind": RhythmguardStylelintConfig;
+    recommended: RhythmguardStylelintConfig;
+    strict: RhythmguardStylelintConfig;
+    tailwind: RhythmguardStylelintConfig;
+    [configName: string]: RhythmguardStylelintConfig;
+  };
+  eslint: RhythmguardEslintPlugin;
+  presets: RhythmguardPresets;
+  rules: {
+    "rhythmguard/no-offscale-transform": StylelintRuleModule;
+    "rhythmguard/prefer-token": StylelintRuleModule;
+    "rhythmguard/use-motion-scale": StylelintRuleModule;
+    "rhythmguard/use-scale": StylelintRuleModule;
+    [ruleName: string]: StylelintRuleModule;
+  };
+}
+
+declare const plugin: RhythmguardPlugin;
+
+export const audit: typeof auditApi;
+export const configs: RhythmguardPlugin["configs"];
+export const eslint: RhythmguardEslintPlugin;
+export const presets: RhythmguardPresets;
+export const rules: RhythmguardPlugin["rules"];
+export default plugin;

package/types/presets.d.ts

@@ -0,0 +1,14 @@
+import type { RhythmguardPresets } from "./shared";
+
+export type { RhythmguardPresets, ScalePresetMetadata } from "./shared";
+
+export const communityScaleMetadata: RhythmguardPresets["communityScaleMetadata"];
+export const getCommunityScaleMetadata: RhythmguardPresets["getCommunityScaleMetadata"];
+export const getScalePreset: RhythmguardPresets["getScalePreset"];
+export const listCommunityScalePresetNames: RhythmguardPresets["listCommunityScalePresetNames"];
+export const listScalePresetNames: RhythmguardPresets["listScalePresetNames"];
+export const scales: RhythmguardPresets["scales"];
+
+declare const presets: RhythmguardPresets;
+
+export default presets;

package/types/rule.d.ts

@@ -0,0 +1,20 @@
+import type { RhythmguardRuleOptions } from "./shared";
+
+export interface StylelintRuleModule {
+  messages: Record<string, unknown>;
+  meta: {
+    fixable?: boolean;
+    url?: string;
+    [key: string]: unknown;
+  };
+  ruleName: string;
+  [key: string]: unknown;
+}
+
+declare const rule: StylelintRuleModule;
+
+export const messages: StylelintRuleModule["messages"];
+export const meta: StylelintRuleModule["meta"];
+export const ruleName: string;
+export type { RhythmguardRuleOptions };
+export default rule;

package/types/shared.d.ts

@@ -0,0 +1,66 @@
+export type ScaleValue = number | string;
+
+export type RuleSeverity = boolean | "always" | "never";
+
+export interface RhythmguardRuleOptions {
+  baseFontSize?: number;
+  customScale?: ScaleValue[];
+  includeMathFunctions?: boolean;
+  preset?: string;
+  properties?: Array<string | RegExp>;
+  scale?: ScaleValue[];
+  tokenMap?: Record<string, string>;
+  tokenMapFile?: string;
+  tokenMapFromCssCustomProperties?: boolean;
+  tokenMapFromTailwindSpacing?: boolean;
+  tokenPattern?: string;
+}
+
+export type RhythmguardRuleConfig =
+  | null
+  | RuleSeverity
+  | [RuleSeverity, RhythmguardRuleOptions];
+
+export interface RhythmguardStylelintConfig {
+  customSyntax?: string;
+  extends?: string | string[];
+  ignoreFiles?: string | string[];
+  plugins?: string[];
+  rules?: Record<string, RhythmguardRuleConfig>;
+}
+
+export interface ScalePresetMetadata {
+  aliases?: string[];
+  base?: number;
+  description?: string;
+  name?: string;
+  values?: number[];
+  [key: string]: unknown;
+}
+
+export interface RhythmguardPresets {
+  communityScaleMetadata: Record<string, ScalePresetMetadata>;
+  getCommunityScaleMetadata(name: string): ScalePresetMetadata | undefined;
+  getScalePreset(name: string): readonly number[] | undefined;
+  listCommunityScalePresetNames(): string[];
+  listScalePresetNames(): string[];
+  scales: Record<string, readonly number[]>;
+}
+
+export interface EslintRuleModule {
+  meta: Record<string, unknown>;
+  create(context: unknown): Record<string, unknown>;
+}
+
+export interface RhythmguardEslintPlugin {
+  configs: {
+    recommended: {
+      rules: Record<string, "off" | "warn" | "error" | number>;
+    };
+  };
+  rules: {
+    "tailwind-class-use-motion-scale": EslintRuleModule;
+    "tailwind-class-use-scale": EslintRuleModule;
+    [ruleName: string]: EslintRuleModule;
+  };
+}