Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

9.8 KB
Raw Blame
#!/usr/bin/env node
/**
 * ESLint ratchet (P2.7).
 *
 * Runs ESLint over src/ with `--format json`, counts warnings + errors per
 * rule and compares the counts with the committed `.lint-baseline.json`.
 * The build fails when any rule's count GREW — existing violations are
 * tolerated until someone fixes them, but nobody may add new ones.
 *
 *   node scripts/lint-ratchet.cjs            # compare against the baseline
 *   node scripts/lint-ratchet.cjs --update   # rewrite the baseline from a real
 *                                            # ESLint run (after a clean-up)
 *   node scripts/lint-ratchet.cjs --estimate # best-effort grep-based baseline
 *                                            # (no ESLint needed); marks it
 *                                            # "provisional" — refresh with
 *                                            # --update at the first real run
 *
 * Rules absent from the baseline count as 0 — a provisional baseline only
 * knows about the rules it could estimate, so the first real run fails on
 * everything else; that is the moment to `--update`.
 *
 * Exported for unit tests: countByRule, compareCounts, estimateCounts,
 * formatReport.
 */
const fs = require('node:fs');
const path = require('node:path');
const { spawnSync } = require('node:child_process');

const root = path.join(__dirname, '..');
const BASELINE_FILE = '.lint-baseline.json';
const LINT_TARGET = 'src';

/** Rule names used by the estimate; must match eslint.config.js. */
const RULE_CONSOLE = 'no-console';
const RULE_ANY = '@typescript-eslint/no-explicit-any';

/** Count ESLint JSON-formatter results per rule (errors + warnings). */
function countByRule(results) {
  const counts = {};
  for (const file of results) {
    for (const message of file.messages || []) {
      // `fatal` parse errors have no ruleId; keep them visible under one key.
      const rule = message.ruleId || (message.fatal ? '(fatal)' : '(unknown)');
      counts[rule] = (counts[rule] || 0) + 1;
    }
  }
  return sortCounts(counts);
}

function sortCounts(counts) {
  return Object.fromEntries(Object.keys(counts).sort().map((k) => [k, counts[k]]));
}

/**
 * Compare current counts with the baseline. Returns the per-rule deltas;
 * `regressions` is non-empty when any rule grew.
 */
function compareCounts(current, baseline) {
  const rules = new Set([...Object.keys(current), ...Object.keys(baseline)]);
  const rows = [];
  for (const rule of [...rules].sort()) {
    const was = baseline[rule] || 0;
    const now = current[rule] || 0;
    rows.push({ rule, was, now, delta: now - was });
  }
  return {
    rows,
    regressions: rows.filter((r) => r.delta > 0),
    improvements: rows.filter((r) => r.delta < 0),
  };
}

function formatReport({ rows, regressions, improvements }) {
  const lines = [];
  const width = Math.max(4, ...rows.map((r) => r.rule.length));
  lines.push(`${'rule'.padEnd(width)}  baseline  current  delta`);
  for (const r of rows) {
    const mark = r.delta > 0 ? '  ← grew' : r.delta < 0 ? '  ✓ improved' : '';
    lines.push(`${r.rule.padEnd(width)}  ${String(r.was).padStart(8)}  ${String(r.now).padStart(7)}  ${(r.delta >= 0 ? '+' : '') + r.delta}${mark}`);
  }
  lines.push('');
  if (regressions.length > 0) {
    lines.push(`ratchet: ${regressions.length} rule(s) grew — fix the new violations (or, after a deliberate decision, run \`npm run lint:ratchet -- --update\`).`);
  } else if (improvements.length > 0) {
    lines.push(`ratchet: OK. ${improvements.length} rule(s) improved — lock it in with \`npm run lint:ratchet -- --update\`.`);
  } else {
    lines.push('ratchet: OK (no change).');
  }
  return lines.join('\n');
}

// ─── ESLint run ──────────────────────────────────────────────────────────────

function findEslint() {
  const local = path.join(root, 'node_modules', 'eslint', 'bin', 'eslint.js');
  if (fs.existsSync(local)) return local;
  return null;
}

function runEslint() {
  const eslint = findEslint();
  if (!eslint) {
    console.error('lint-ratchet: eslint is not installed (node_modules/eslint missing). Run `npm ci` first.');
    process.exit(2);
  }
  const result = spawnSync(process.execPath, [eslint, LINT_TARGET, '--format', 'json'], {
    cwd: root,
    encoding: 'utf8',
    maxBuffer: 256 * 1024 * 1024,
  });
  // ESLint exits 1 when there are errors — that is expected here; anything
  // else (2 = config/usage error) is fatal.
  if (result.error) {
    console.error(`lint-ratchet: failed to run eslint: ${result.error.message}`);
    process.exit(2);
  }
  if (result.status !== 0 && result.status !== 1) {
    console.error(result.stderr || result.stdout);
    console.error(`lint-ratchet: eslint exited with status ${result.status}`);
    process.exit(2);
  }
  let parsed;
  try {
    parsed = JSON.parse(result.stdout);
  } catch (err) {
    console.error(result.stderr);
    console.error(`lint-ratchet: could not parse eslint JSON output: ${err.message}`);
    process.exit(2);
  }
  return parsed;
}

// ─── Baseline file ───────────────────────────────────────────────────────────

function readBaseline(file = path.join(root, BASELINE_FILE)) {
  if (!fs.existsSync(file)) return null;
  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
  if (!data || typeof data !== 'object' || typeof data.rules !== 'object') {
    throw new Error(`${BASELINE_FILE}: expected { "rules": { "<rule>": <count> } }`);
  }
  return data;
}

function writeBaseline(counts, { provisional, file = path.join(root, BASELINE_FILE) }) {
  const data = {
    $comment: provisional
      ? 'PROVISIONAL baseline estimated with grep (scripts/lint-ratchet.cjs --estimate); refresh with `npm run lint:ratchet -- --update` at the first real ESLint run.'
      : 'ESLint ratchet baseline. Per-rule counts (errors + warnings) may only go down. Refresh with `npm run lint:ratchet -- --update` after a clean-up.',
    provisional: Boolean(provisional),
    generatedAt: new Date().toISOString(),
    target: LINT_TARGET,
    rules: sortCounts(counts),
  };
  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
  return data;
}

// ─── Grep-based estimate (no ESLint available) ───────────────────────────────

function walk(dir, out = []) {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const full = path.join(dir, entry.name);
    if (entry.isDirectory()) walk(full, out);
    else if (/\.(ts|tsx)$/.test(entry.name)) out.push(full);
  }
  return out;
}

/** Mirrors the no-console exemptions in eslint.config.js. */
function isConsoleAllowed(relPath) {
  const p = relPath.split(path.sep).join('/');
  return p.startsWith('src/cli/') || p === 'src/index.ts' || /\.test\.tsx?$/.test(p) || p.includes('/__tests__/');
}

/**
 * Best-effort counts for the two rules a grep can approximate. Everything
 * else (no-unused-vars, …) is unknown and therefore 0 — the point of the
 * provisional flag.
 */
function estimateCounts(srcDir = path.join(root, LINT_TARGET)) {
  let consoleCount = 0;
  let anyCount = 0;
  for (const file of walk(srcDir)) {
    const rel = path.relative(root, file);
    const text = fs.readFileSync(file, 'utf8');
    if (!isConsoleAllowed(rel)) {
      consoleCount += (text.match(/\bconsole\.(log|error|warn|info|debug|trace|table|dir|group|groupEnd|time|timeEnd)\s*\(/g) || []).length;
    }
    // Type positions where `any` is written out: `: any`, `<any`, `as any`,
    // `any[]`, `any>`, `any,`, `any)`, `any |`, `| any`.
    anyCount += (text.match(/(?<![\w$.])any(?![\w$])(?=\s*[\]>,)|&;=\n}]|\s*\[\])|(?<=:\s*|<\s*|as\s+|\|\s*|&\s*)any(?![\w$])/g) || []).length;
  }
  return sortCounts({ [RULE_CONSOLE]: consoleCount, [RULE_ANY]: anyCount });
}

// ─── CLI ─────────────────────────────────────────────────────────────────────

function main(argv) {
  const update = argv.includes('--update');
  const estimate = argv.includes('--estimate');
  const unknown = argv.filter((a) => !['--update', '--estimate'].includes(a));
  if (unknown.length > 0) {
    console.error(`lint-ratchet: unknown argument(s): ${unknown.join(', ')}`);
    return 2;
  }

  if (estimate) {
    const counts = estimateCounts();
    const data = writeBaseline(counts, { provisional: true });
    console.log(`lint-ratchet: wrote PROVISIONAL ${BASELINE_FILE} (grep estimate):`);
    for (const [rule, n] of Object.entries(data.rules)) console.log(`  ${rule.padEnd(40)} ${n}`);
    console.log('Refresh it with `npm run lint:ratchet -- --update` once ESLint runs for real.');
    return 0;
  }

  const current = countByRule(runEslint());

  if (update) {
    writeBaseline(current, { provisional: false });
    const total = Object.values(current).reduce((a, b) => a + b, 0);
    console.log(`lint-ratchet: wrote ${BASELINE_FILE} (${Object.keys(current).length} rule(s), ${total} finding(s)).`);
    return 0;
  }

  const baseline = readBaseline();
  if (!baseline) {
    console.error(`lint-ratchet: ${BASELINE_FILE} not found — create it with \`npm run lint:ratchet -- --update\`.`);
    return 2;
  }
  if (baseline.provisional) {
    console.log(`lint-ratchet: NOTE — ${BASELINE_FILE} is provisional (grep estimate). Refresh it with --update after this run.`);
  }
  const comparison = compareCounts(current, baseline.rules);
  console.log(formatReport(comparison));
  return comparison.regressions.length > 0 ? 1 : 0;
}

module.exports = { countByRule, compareCounts, estimateCounts, formatReport, readBaseline, writeBaseline, isConsoleAllowed };

if (require.main === module) {
  process.exit(main(process.argv.slice(2)));
}