stylelint-plugin-rhythmguard 2.0.1 → 2.2.0

package/src/audit/config.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  normalizeTokenKind,
+  normalizeTokenSourceFormat,
+} = require('../utils/token-sources');
+const {
+  parseBaseFontSize,
+  parseNonNegativeInteger,
+  parsePathOption,
+  parsePercentage,
+  parsePositiveInteger,
+  parseScale,
+} = require('./args');
+const {
+  DEFAULT_IGNORE_PATH,
+  createDefaultAuditOptions,
+  formatPath,
+  normalizeIgnorePattern,
+} = require('./shared');
+
+
+function loadAuditConfig(parsed) {
+  parsed = {
+    ...createDefaultAuditOptions(),
+    ...parsed,
+  };
+
+  if (parsed.noConfig) {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(process.cwd(), parsed.configPath);
+  if (!fs.existsSync(resolvedPath)) {
+    if (parsed.configExplicit) {
+      throw new Error(`Config file not found: ${parsed.configPath}`);
+    }
+    return null;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: ${err.message}`);
+  }
+
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: expected an object.`);
+  }
+
+  const audit = config.audit || {};
+  if (!audit || typeof audit !== 'object' || Array.isArray(audit)) {
+    throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: "audit" must be an object.`);
+  }
+
+  return {
+    audit,
+    file: formatPath(resolvedPath),
+    rootDir: path.dirname(resolvedPath),
+  };
+}
+
+function applyAuditConfig(parsed, configResult) {
+  const cliOptions = parsed.cliOptions;
+  const next = {
+    ...parsed,
+    config: configResult
+      ? {
+        file: configResult.file,
+      }
+      : null,
+  };
+
+  if (!configResult) {
+    next.tokenSources = normalizeCliTokenSources(parsed.tokenSources, parsed.tokenSourceFormat);
+    delete next.cliOptions;
+    return next;
+  }
+
+  const audit = configResult.audit;
+
+  if (Array.isArray(audit.ignore)) {
+    next.ignorePatterns = [
+      ...audit.ignore.map((pattern) => normalizeIgnorePattern(pattern)).filter(Boolean),
+      ...parsed.ignorePatterns,
+    ];
+  }
+
+  const configuredTokenSources = normalizeConfigTokenSources(
+    audit.tokenSources,
+    configResult.rootDir,
+  );
+  next.tokenSources = [
+    ...configuredTokenSources,
+    ...normalizeCliTokenSources(parsed.tokenSources, parsed.tokenSourceFormat),
+  ];
+
+  applyConfigScalar(next, audit, cliOptions, 'ignorePath', 'ignorePath', parsePathOption);
+  applyConfigScalar(next, audit, cliOptions, 'baselinePath', 'baseline', parsePathOption);
+  applyConfigScalar(next, audit, cliOptions, 'maxFindings', 'maxFindings', parseNonNegativeInteger);
+  applyConfigScalar(next, audit, cliOptions, 'minCleanliness', 'minCleanliness', parsePercentage);
+  applyConfigScalar(next, audit, cliOptions, 'tokenCandidateMinCount', 'tokenCandidateMinCount', parsePositiveInteger);
+  applyConfigScalar(next, audit, cliOptions, 'tokenKind', 'tokenKind', normalizeTokenKind);
+  applyConfigScalar(next, audit, cliOptions, 'baseFontSize', 'baseFontSize', parseBaseFontSize);
+  applyConfigScalar(next, audit, cliOptions, 'includeMotion', 'includeMotion', parseBooleanOption);
+  applyConfigScalar(next, audit, cliOptions, 'scale', 'scale', (value) => {
+    if (Array.isArray(value)) {
+      return value;
+    }
+    return parseScale(String(value));
+  });
+
+  delete next.cliOptions;
+  return next;
+}
+
+function applyConfigScalar(target, audit, cliOptions, targetKey, configKey, parser) {
+  if (cliOptions.has(targetKey) || audit[configKey] === undefined) {
+    return;
+  }
+
+  target[targetKey] = parser(audit[configKey], configKey);
+}
+
+function parseBooleanOption(value, optionName) {
+  if (typeof value !== 'boolean') {
+    throw new Error(`${optionName} must be a boolean.`);
+  }
+
+  return value;
+}
+
+function normalizeCliTokenSources(sources, format) {
+  return sources.map((source) => {
+    // The programmatic API may pass typed { path | file, format?, baseDir? } entries.
+    if (source && typeof source === 'object') {
+      return {
+        baseDir: source.baseDir || process.cwd(),
+        format: source.format || format,
+        path: source.path || source.file,
+      };
+    }
+    return {
+      baseDir: process.cwd(),
+      format,
+      path: source,
+    };
+  });
+}
+
+function normalizeConfigTokenSources(sources, baseDir) {
+  if (sources === undefined) {
+    return [];
+  }
+
+  if (!Array.isArray(sources)) {
+    throw new Error('Invalid Rhythmguard config: audit.tokenSources must be an array.');
+  }
+
+  return sources.map((source) => {
+    if (typeof source === 'string') {
+      return {
+        baseDir,
+        format: 'auto',
+        path: source,
+      };
+    }
+
+    if (!source || typeof source !== 'object' || Array.isArray(source)) {
+      throw new Error('Invalid Rhythmguard config: audit.tokenSources entries must be strings or objects.');
+    }
+
+    if (typeof source.path !== 'string' || source.path.trim().length === 0) {
+      throw new Error('Invalid Rhythmguard config: token source objects must include a path.');
+    }
+
+    return {
+      baseDir,
+      format: normalizeTokenSourceFormat(source.format || 'auto'),
+      path: source.path,
+    };
+  });
+}
+
+function loadIgnorePatterns(ignorePath) {
+  if (!ignorePath) {
+    return [];
+  }
+
+  const resolvedPath = path.resolve(process.cwd(), ignorePath);
+  if (!fs.existsSync(resolvedPath)) {
+    if (ignorePath === DEFAULT_IGNORE_PATH) {
+      return [];
+    }
+    throw new Error(`Ignore file not found: ${ignorePath}`);
+  }
+
+  return fs.readFileSync(resolvedPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'))
+    .map((line) => normalizeIgnorePattern(line))
+    .filter(Boolean);
+}
+
+module.exports = {
+  applyAuditConfig,
+  applyConfigScalar,
+  loadAuditConfig,
+  loadIgnorePatterns,
+  normalizeCliTokenSources,
+  normalizeConfigTokenSources,
+  parseBooleanOption,
+};

package/src/audit/contract.js

@@ -0,0 +1,422 @@
+'use strict';
+
+const fs = require('node:fs');
+const {
+  addDefinition,
+  createTokenKindMatcher,
+  getNormalizedValueKeys,
+} = require('../utils/token-sources');
+const { formatPath } = require('./shared');
+
+function collectTokenContract({
+  baseFontSize,
+  cssFiles,
+  cssFindings,
+  externalTokenDefinitions,
+  minCandidateCount,
+  tailwindFindings,
+  tokenKind,
+  tokenSourceReports,
+}) {
+  const definitions = new Map();
+  const uses = new Map();
+  const rawValues = new Map();
+  const rawValueLocations = new Set();
+  const matchesKind = createTokenKindMatcher(tokenKind);
+
+  for (const filePath of cssFiles) {
+    let source = '';
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const file = formatPath(filePath);
+    collectTokenDefinitions(source, file, definitions, matchesKind, baseFontSize);
+    collectTokenUses(source, file, uses, matchesKind);
+  }
+
+  for (const entry of externalTokenDefinitions.values()) {
+    for (const value of entry.values || []) {
+      addDefinition(definitions, {
+        baseFontSize,
+        file: Array.from(entry.files)[0] || 'external-token-source',
+        source: Array.from(entry.sources)[0] || Array.from(entry.files)[0] || 'external-token-source',
+        token: entry.token,
+        value,
+      });
+    }
+  }
+
+  for (const finding of cssFindings) {
+    addRawValue(rawValues, rawValueLocations, finding.value, finding);
+  }
+
+  for (const finding of tailwindFindings) {
+    addRawValue(rawValues, rawValueLocations, finding.rawValue, finding);
+  }
+
+  const definedTokens = mapTokenEntries(definitions);
+  const usedTokens = mapTokenEntries(uses);
+  const missingTokens = usedTokens.filter(({ token }) => !definitions.has(token));
+  const unusedTokens = definedTokens.filter(({ token }) => !uses.has(token));
+  const rawValueMatches = collectRawValueMatches(rawValues, definitions, baseFontSize);
+  const conflictingTokens = collectConflictingTokens(definitions);
+  const rawValueCandidates = Array.from(rawValues.entries())
+    .map(([value, entry]) => ({
+      count: entry.count,
+      files: Array.from(entry.files).sort(),
+      value,
+    }))
+    .filter(({ count }) => count >= minCandidateCount)
+    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+
+  return {
+    definedTokens,
+    conflictingTokens,
+    missingTokens,
+    rawValueMatches,
+    rawValueCandidates,
+    sources: tokenSourceReports,
+    summary: {
+      conflictingTokens: conflictingTokens.length,
+      definedTokens: definedTokens.length,
+      missingTokens: missingTokens.length,
+      rawValueMatches: rawValueMatches.length,
+      rawValueCandidates: rawValueCandidates.length,
+      tokenSources: tokenSourceReports.length,
+      unusedTokens: unusedTokens.length,
+      usedTokens: usedTokens.length,
+    },
+    unusedTokens,
+    usedTokens,
+  };
+}
+
+function collectTokenDefinitions(source, file, definitions, matchesKind, baseFontSize) {
+  const declarationPattern = /(--[\w-]+)\s*:\s*([^;{}]+)/g;
+  let match;
+
+  while ((match = declarationPattern.exec(source)) !== null) {
+    const token = match[1];
+    if (!matchesKind(token)) {
+      continue;
+    }
+
+    addDefinition(definitions, {
+      baseFontSize,
+      file,
+      source: file,
+      token,
+      value: match[2].trim(),
+    });
+  }
+}
+
+function collectTokenUses(source, file, uses, matchesKind) {
+  const varPattern = /var\(\s*(--[\w-]+)/g;
+  let match;
+
+  while ((match = varPattern.exec(source)) !== null) {
+    const token = match[1];
+    if (!matchesKind(token)) {
+      continue;
+    }
+
+    const entry = uses.get(token) || {
+      files: new Set(),
+      token,
+    };
+    entry.files.add(file);
+    uses.set(token, entry);
+  }
+}
+
+function addRawValue(rawValues, rawValueLocations, value, finding) {
+  if (!value) {
+    return;
+  }
+
+  const locationKey = [
+    finding.file || '',
+    finding.line || '',
+    finding.column || '',
+    value,
+  ].join('\u001f');
+  if (rawValueLocations.has(locationKey)) {
+    return;
+  }
+  rawValueLocations.add(locationKey);
+
+  const entry = rawValues.get(value) || {
+    count: 0,
+    files: new Set(),
+  };
+  entry.count += 1;
+  if (finding.file) {
+    entry.files.add(finding.file);
+  }
+  rawValues.set(value, entry);
+}
+
+function mapTokenEntries(entries) {
+  return Array.from(entries.values())
+    .map((entry) => ({
+      files: Array.from(entry.files).sort(),
+      normalizedValues: entry.normalizedValues
+        ? Array.from(entry.normalizedValues).sort()
+        : undefined,
+      sources: entry.sources ? Array.from(entry.sources).sort() : undefined,
+      token: entry.token,
+      values: entry.values ? Array.from(entry.values).sort() : undefined,
+    }))
+    .sort((a, b) => a.token.localeCompare(b.token));
+}
+
+function collectRawValueMatches(rawValues, definitions, baseFontSize) {
+  const valueToTokens = createValueToTokensMap(definitions);
+  const matches = [];
+
+  for (const [value, entry] of rawValues.entries()) {
+    const tokens = new Set();
+    for (const key of getNormalizedValueKeys(value, baseFontSize)) {
+      for (const token of valueToTokens.get(key) || []) {
+        tokens.add(token);
+      }
+    }
+
+    if (tokens.size === 0) {
+      continue;
+    }
+
+    matches.push({
+      count: entry.count,
+      files: Array.from(entry.files).sort(),
+      tokens: Array.from(tokens).sort(),
+      value,
+    });
+  }
+
+  return matches.sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+}
+
+function collectConflictingTokens(definitions) {
+  const valueToTokens = createValueToTokensMap(definitions);
+  const conflicts = [];
+
+  for (const [value, tokens] of valueToTokens.entries()) {
+    const uniqueTokens = Array.from(tokens).sort();
+    if (uniqueTokens.length < 2) {
+      continue;
+    }
+
+    conflicts.push({
+      tokens: uniqueTokens,
+      value,
+    });
+  }
+
+  return conflicts.sort((a, b) => a.value.localeCompare(b.value));
+}
+
+function createValueToTokensMap(definitions) {
+  const valueToTokens = new Map();
+
+  for (const entry of definitions.values()) {
+    for (const value of entry.normalizedValues || []) {
+      const tokens = valueToTokens.get(value) || new Set();
+      tokens.add(entry.token);
+      valueToTokens.set(value, tokens);
+    }
+  }
+
+  return valueToTokens;
+}
+
+function buildReport({
+  baseFontSize,
+  config,
+  cssFiles,
+  cssFindings,
+  dir,
+  externalTokenDefinitions,
+  includeMotion,
+  motionFindings,
+  scale,
+  scanScope,
+  templateFiles,
+  tailwindFindings,
+  tokenCandidateMinCount,
+  tokenKind,
+  tokenSourceReports,
+  tokenSourceWarnings,
+}) {
+  const offScaleValues = countByValue(cssFindings
+    .filter((finding) => finding.type === 'off-scale' && finding.value)
+    .map((finding) => finding.value));
+  const tokenOpportunities = countByValue(cssFindings
+    .filter((finding) => finding.type === 'token-opportunity' && finding.value)
+    .map((finding) => finding.value));
+  const tailwindArbitraryValues = countByValue(tailwindFindings
+    .map((finding) => finding.rawValue));
+  const motionValues = countByValue(motionFindings
+    .map((finding) => finding.value || finding.rawValue));
+  const issueFiles = new Set([
+    ...cssFindings.map((finding) => finding.file),
+    ...motionFindings.map((finding) => finding.file),
+    ...tailwindFindings.map((finding) => finding.file),
+  ]);
+  const topAffectedFiles = sortCountMap(countByValue([
+    ...cssFindings.map((finding) => finding.file),
+    ...motionFindings.map((finding) => finding.file),
+    ...tailwindFindings.map((finding) => finding.file),
+  ])).slice(0, 10);
+
+  const totalFiles = cssFiles.length + templateFiles.length;
+  const totalWarnings = cssFindings.length + motionFindings.length + tailwindFindings.length;
+  const filesWithIssues = issueFiles.size;
+  const scaleCleanliness = totalFiles > 0
+    ? Math.max(0, Math.round(((totalFiles - filesWithIssues) / totalFiles) * 100))
+    : 100;
+  const tokenContract = collectTokenContract({
+    baseFontSize,
+    cssFiles,
+    cssFindings,
+    externalTokenDefinitions,
+    minCandidateCount: tokenCandidateMinCount,
+    tailwindFindings,
+    tokenKind,
+    tokenSourceReports,
+  });
+
+  return {
+    config,
+    cssFilesScanned: cssFiles.length,
+    directory: dir,
+    filesWithIssues,
+    findings: {
+      css: cssFindings,
+      motion: motionFindings,
+      tailwind: tailwindFindings,
+    },
+    formatVersion: 5,
+    motion: {
+      enabled: includeMotion,
+      findings: motionFindings.length,
+      values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
+    },
+    offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
+    scale: scale || null,
+    scaleCleanliness,
+    scanScope,
+    scanned: {
+      cssFiles: cssFiles.length,
+      templateFiles: templateFiles.length,
+      totalFiles,
+    },
+    summary: {
+      cssWarnings: cssFindings.length,
+      filesWithIssues,
+      motionFindings: motionFindings.length,
+      rawValueMatches: tokenContract.summary.rawValueMatches,
+      missingTokens: tokenContract.summary.missingTokens,
+      rawValueCandidates: tokenContract.summary.rawValueCandidates,
+      scaleCleanliness,
+      tailwindArbitrarySpacing: tailwindFindings.length,
+      tokenOpportunities: sumCounts(tokenOpportunities),
+      tokenSources: tokenContract.summary.tokenSources,
+      totalFindings: totalWarnings,
+      unusedTokens: tokenContract.summary.unusedTokens,
+    },
+    tailwindArbitraryValues: Object.fromEntries(sortCountMap(tailwindArbitraryValues).slice(0, 10)),
+    templateFilesScanned: templateFiles.length,
+    tokenContract,
+    tokenSourceWarnings,
+    tokenOpportunities: Object.fromEntries(sortCountMap(tokenOpportunities).slice(0, 10)),
+    topAffectedFiles: topAffectedFiles.map(([file, count]) => ({ count, file })),
+    totalFiles,
+    totalWarnings,
+  };
+}
+
+function countByValue(values) {
+  const counts = {};
+
+  for (const value of values) {
+    if (value) {
+      counts[value] = (counts[value] || 0) + 1;
+    }
+  }
+
+  return counts;
+}
+
+function sortCountMap(counts) {
+  return Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
+
+function sumCounts(counts) {
+  return Object.values(counts).reduce((total, count) => total + count, 0);
+}
+
+function toAuditContractReport(report) {
+  return {
+    baseline: report.baseline || null,
+    command: {
+      config: report.config,
+      directory: report.directory,
+      scanScope: report.scanScope.mode,
+    },
+    contracts: {
+      motion: report.motion,
+      scale: {
+        cleanliness: report.scaleCleanliness,
+        files: report.scale ? report.scale.files : [],
+        offScaleValues: report.offScaleValues,
+        source: report.scale ? report.scale.source : 'default',
+        tokenOpportunities: report.tokenOpportunities,
+        values: report.scale ? report.scale.values : null,
+      },
+      tokens: report.tokenContract,
+    },
+    findings: report.findings,
+    scanned: report.scanned,
+    schemaVersion: '2.0',
+    summary: report.summary,
+  };
+}
+
+const AUDIT_JSON_SCHEMA = Object.freeze({
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  additionalProperties: true,
+  properties: {
+    baseline: { type: ['object', 'null'] },
+    command: { type: 'object' },
+    contracts: { type: 'object' },
+    findings: { type: 'object' },
+    scanned: { type: 'object' },
+    schemaVersion: { const: '2.0' },
+    summary: { type: 'object' },
+  },
+  required: ['schemaVersion', 'command', 'summary', 'scanned', 'contracts', 'findings'],
+  title: 'Rhythmguard Audit Report',
+  type: 'object',
+});
+
+module.exports = {
+  AUDIT_JSON_SCHEMA,
+  addRawValue,
+  buildReport,
+  collectConflictingTokens,
+  collectRawValueMatches,
+  collectTokenContract,
+  collectTokenDefinitions,
+  collectTokenUses,
+  countByValue,
+  createValueToTokensMap,
+  mapTokenEntries,
+  sortCountMap,
+  sumCounts,
+  toAuditContractReport,
+};

package/src/audit/render-github.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const { getAllFindings } = require('./baseline');
+
+function renderGithub(report) {
+  const findings = getAllFindings(report);
+  const lines = findings.map((finding) =>
+    `::warning file=${escapeGithubProperty(finding.file)},line=${finding.line || 1},col=${finding.column || 1},title=${escapeGithubProperty(finding.rule || 'rhythmguard')}::${escapeGithubData(finding.text || '')}`,
+  );
+  const findingWord = findings.length === 1 ? 'finding' : 'findings';
+  const fileWord = report.filesWithIssues === 1 ? 'file' : 'files';
+  lines.push(
+    `::notice title=Rhythmguard audit::${escapeGithubData(
+      `${findings.length} ${findingWord} across ${report.filesWithIssues} ${fileWord}, ${report.scaleCleanliness}% scale cleanliness`,
+    )}`,
+  );
+  return `${lines.join('\n')}\n`;
+}
+
+// Escaping rules from GitHub's actions/toolkit (packages/core/src/command.ts).
+
+function escapeGithubData(value) {
+  return String(value)
+    .replace(/%/g, '%25')
+    .replace(/\r/g, '%0D')
+    .replace(/\n/g, '%0A');
+}
+
+function escapeGithubProperty(value) {
+  return escapeGithubData(value)
+    .replace(/:/g, '%3A')
+    .replace(/,/g, '%2C');
+}
+
+module.exports = {
+  escapeGithubData,
+  escapeGithubProperty,
+  renderGithub,
+};