docs.js

// @ts-check

import { ESLint } from 'eslint';
import fs from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { TEST_FILE_PATTERNS } from '../src/lib/patterns.js';
import {
  configNames,
  getAllEnabledRuleIds,
  importConfig,
  isConfigForTests,
} from './helpers/configs.js';
import { configRulesToMarkdown } from './helpers/format-config.js';
import { configsToMarkdown } from './helpers/format-readme.js';
import {
  findRuleEntry,
  getRulesMetadata,
  ruleLevelFromEntry,
} from './helpers/rules.js';

const currentDir = fileURLToPath(path.dirname(import.meta.url));
const readmePath = path.join(currentDir, '..', 'README.md');
const docsDir = path.join(currentDir, '..', 'docs');

await generateDocs();

async function generateDocs() {
  const configs = await loadConfigs(configNames);
  const peerDeps = await loadPeerDependencies(configs);

  await fs.mkdir(docsDir, { recursive: true });

  await Promise.all(
    configs.map(config => generateConfigDocs(config, configs, peerDeps)),
  );

  await generateReadmeDocs(configs, peerDeps);
}

/**
 * @param {import('./helpers/types.js').ConfigName[]} names
 * @returns {Promise<import('./helpers/types.js').ExportedConfig[]>}
 */
function loadConfigs(names) {
  return Promise.all(
    names.map(async name => ({
      name,
      flatConfig: await importConfig(name),
    })),
  );
}

/**
 * @param {import('./helpers/types.js').ExportedConfig[]} configs
 * @returns {Promise<import('./helpers/types.js').PeerDep[]>}
 */
async function loadPeerDependencies(configs) {
  const packageJson = await import('../package.json', {
    with: { type: 'json' },
  }).then(m => m.default);

  const pkgConfigs = configs.reduce(
    /** @param {Record<string, string[]>} acc */
    (acc, config) => {
      const plugins = config.flatConfig.flatMap(cfg =>
        Object.keys(cfg.plugins ?? {}),
      );
      const usedPackages = Object.keys(packageJson.peerDependencies).filter(
        pkg => {
          if (pkg === 'eslint') {
            return false;
          }
          const alias = pkg.replace(/eslint-plugin-?/, '').replace(/\/$/, '');
          return (
            plugins.includes(pkg) ||
            plugins.includes(alias) ||
            plugins.map(plugin => plugin.replace(/^@/, '')).includes(alias)
          );
        },
      );
      return {
        ...acc,
        ...Object.fromEntries(
          usedPackages.map(pkg => [pkg, [...(acc[pkg] ?? []), config.name]]),
        ),
      };
    },
    {},
  );

  /** @type {Record<string, {optional: boolean}>} */
  const peerDependenciesMeta = packageJson.peerDependenciesMeta;

  return Object.entries(packageJson.peerDependencies).map(([pkg, version]) => ({
    pkg,
    version,
    optional: peerDependenciesMeta[pkg]?.optional ?? false,
    usedByConfigs: pkgConfigs[pkg] ?? [],
  }));
}

/**
 * Update auto-generated part of README.md
 * @param {import('./helpers/types.js').ExportedConfig[]} configs Exported configs
 * @param {import('./helpers/types.js').PeerDep[]} peerDeps Peer dependencies
 */
async function generateReadmeDocs(configs, peerDeps) {
  const extended = Object.fromEntries(
    configs.map(config => [config.name, getExtendedConfigs(config)]),
  );

  const buffer = await fs.readFile(readmePath);
  const mdPrevious = buffer.toString('utf8');

  const startComment = '<!-- begin autogenerated -->';
  const endComment = '<!-- end autogenerated -->';

  const startIndex = mdPrevious.indexOf(startComment);
  const endIndex = mdPrevious.indexOf(
    endComment,
    startIndex + startComment.length,
  );

  const mdGenerated = configsToMarkdown(configNames, peerDeps, extended);
  const mdGeneratedBlock = [
    startComment,
    mdGenerated.replace(/\n$/, ''),
    endComment,
  ].join('\n\n');

  const mdUpdated =
    startIndex < 0
      ? [mdPrevious, mdGeneratedBlock].join('\n')
      : [
          mdPrevious.slice(0, startIndex),
          mdGeneratedBlock,
          mdPrevious.slice(endIndex + endComment.length),
        ].join('');

  await fs.writeFile(readmePath, mdUpdated);

  console.info(`Updated Markdown docs in ${readmePath}`);
}

/**
 * Generate Markdown file for specified ESLint config.
 * @param {import('./helpers/types.js').ExportedConfig} config Exported config
 * @param {import('./helpers/types.js').ExportedConfig[]} allConfigs All exported configs
 * @param {import('./helpers/types.js').PeerDep[]} peerDeps Peer dependencies
 */
async function generateConfigDocs(config, allConfigs, peerDeps) {
  const extendedConfigs = Object.fromEntries(
    getExtendedConfigs(config).map(otherName => {
      const otherConfig = allConfigs.find(({ name }) => name === otherName);
      const otherRuleIds = getAllEnabledRuleIds(otherConfig?.flatConfig ?? []);
      return [otherName, otherRuleIds];
    }),
  );
  const extendedRuleIds = new Set(Object.values(extendedConfigs).flat());

  const ruleIds = getAllEnabledRuleIds(config.flatConfig).filter(
    ruleId => !extendedRuleIds.has(ruleId),
  );

  const eslint = new ESLint();
  const dummyFile = 'eslint.config.js';
  await eslint.lintFiles(dummyFile);

  const rulesMeta = getRulesMetadata(
    config.flatConfig,
    ruleIds,
    eslint,
    dummyFile,
  );

  const markdown = configRulesToMarkdown(
    config.name,
    ruleIds.map(id => findRuleData(id, config, rulesMeta)),
    Object.entries(extendedConfigs).map(([alias, rules]) => ({
      alias,
      rulesCount: rules.length,
    })),
    peerDeps,
    {
      hideOverrides: isConfigForTests(config.name),
    },
  );

  const filePath = path.join(docsDir, `${config.name}.md`);
  await fs.writeFile(filePath, markdown);

  console.info(`Generated Markdown docs in ${filePath}`);
}

/**
 * Look up rule's metadata, level, custom options and overrides for given config.
 * @param {string} id Rule ID
 * @param {import('./helpers/types.js').ExportedConfig} config Configuration
 * @param {Record<string, import('eslint').Rule.RuleMetaData>} rules Rules metadata
 * @returns {import('./helpers/types.js').RuleData} Rule data
 */
function findRuleData(id, config, rules) {
  const meta = rules[id];
  if (!meta) {
    throw new Error(`Can't find metadata for rule ${id}`);
  }

  const entry =
    findRuleEntry(
      config.flatConfig.filter(
        ({ name }) =>
          name?.startsWith('code-pushup/') &&
          (name.endsWith('/customized') || name.endsWith('/additional')),
      ),
      id,
    ) ??
    findRuleEntry(
      config.flatConfig.filter(({ files }) => files !== TEST_FILE_PATTERNS),
      id,
    );
  if (entry == null) {
    throw new Error(
      `Internal logic error - no entry found for rule ${id} in ${config.name} config`,
    );
  }
  const level = ruleLevelFromEntry(entry);
  if (level === 'off') {
    throw new Error(
      `Internal logic error - rule ${id} turned off in ${config.name} config`,
    );
  }

  const testEntry = findRuleEntry(
    config.flatConfig.filter(({ files }) => files === TEST_FILE_PATTERNS),
    id,
  );
  const testLevel = testEntry == null ? null : ruleLevelFromEntry(testEntry);

  return {
    id,
    meta,
    level,
    ...(Array.isArray(entry) &&
      entry.length > 1 && {
        options: entry.slice(1),
      }),
    ...(testLevel &&
      testLevel !== level && {
        testOverride: {
          level: testLevel,
        },
      }),
  };
}

/**
 * Get all extended code-pushup configs from flat config.
 * @param {import('./helpers/types.js').ExportedConfig} config Exported config
 */
function getExtendedConfigs(config) {
  const allExtended = [
    ...new Set(
      config.flatConfig
        .map(cfg => cfg.name)
        .filter(name => name?.startsWith('code-pushup/'))
        .map(name => name?.split('/')[1])
        .filter(name => name != null),
    ),
  ];
  return allExtended.filter(name => name !== config.name).slice(-1);
}