@tenphi/eslint-plugin-tasty 1.18.0 → 1.19.1

package/harness/dev.harnesspm/scripts/check.mjs

@@ -0,0 +1,254 @@
+/**
+ * tasty-lint:check — lints files with this plugin's Tasty rules only, as the
+ * project's own lint config sets them, with the project's tasty.config.* and
+ * ESLint.
+ */
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  NO_PARSER,
+  collectProblems,
+  createLinter,
+  formatProblems,
+  isLintable,
+  isTypeScript,
+  lintOptions,
+  loadESLint,
+  loadTypeScriptParser,
+  rulePage,
+  summarize,
+} from './lint.mjs';
+import { createConfigResolver, isOn } from './project-config.mjs';
+
+const USAGE = `Usage: npx harnesspm run tasty-lint:check <files or folders>... [--strict] [--json]
+
+Lints the files with the Tasty rules of @tenphi/eslint-plugin-tasty only, as
+the project's own lint runs them: each file gets the tasty/* rules, their
+options and settings.tasty (such as typeAwareJSX) from the nearest
+.oxlintrc.json, .oxlintrc.jsonc, oxlint.config.ts, oxlint.config.mts or ESLint
+flat config above it that loads the plugin, and the files that config ignores
+are skipped. Without such a config, it runs the recommended preset. The rules
+read the project's tasty.config.* too. Other plugins' rules do not run.
+
+Disable comments for the Tasty rules apply: // eslint-disable-next-line
+tasty/<rule> -- <reason>, and the oxlint-disable forms, unless the config is
+ESLint's.
+
+A path is read from the current folder, else from the project root. Each
+problem prints as file:line:col  tasty/<rule>  <severity>  message, with the
+file relative to the project root. The page of each rule reported follows. Exit code: 0
+without errors (warnings allowed), 1 with errors, 2 when nothing could be
+linted.
+
+--strict  also run the strict preset's rules that the config does not set
+--json    print the problems as JSON`;
+
+const PACKAGE_ROOT = realpathSync(
+  fileURLToPath(new URL('../../../', import.meta.url)),
+);
+const BUILD = join(PACKAGE_ROOT, 'dist/index.js');
+const cwd = process.cwd();
+const projectDir = process.env.HARNESSPM_PROJECT_DIR || cwd;
+
+function fail(message) {
+  console.error(`tasty-lint: ${message}`);
+  process.exit(2);
+}
+
+const errorText = (error) =>
+  error instanceof Error ? error.message : String(error);
+
+const options = { strict: false, json: false, help: false };
+const paths = [];
+for (const arg of process.argv.slice(2)) {
+  if (!arg.startsWith('--')) paths.push(arg);
+  else if (arg.slice(2) in options) options[arg.slice(2)] = true;
+  else fail(`unknown option ${arg}\n\n${USAGE}`);
+}
+if (options.help || paths.length === 0) {
+  console.log(USAGE);
+  process.exit(options.help ? 0 : 2);
+}
+
+// A path is read from the current folder, else from the project root: an
+// agent's shell can be elsewhere when it names a file of the project.
+const targets = paths.map((path) =>
+  [resolve(cwd, path), resolve(projectDir, path)].find((p) => existsSync(p)),
+);
+const missing = paths.filter((_, i) => !targets[i]);
+if (missing.length > 0) fail(`cannot find ${missing.join(', ')}`);
+if (!existsSync(BUILD)) {
+  fail(
+    `cannot find the plugin build at ${BUILD}. In the plugin's repository, run \`pnpm build\` first.`,
+  );
+}
+
+const {
+  default: plugin,
+  recommended,
+  strict,
+} = await import(pathToFileURL(BUILD).href);
+const preset = options.strict ? 'strict' : 'recommended';
+
+let ESLint;
+let espree;
+let parser;
+try {
+  ({ ESLint, espree } = await loadESLint([cwd, projectDir], PACKAGE_ROOT));
+  parser = await loadTypeScriptParser([cwd, projectDir]);
+} catch (error) {
+  fail(errorText(error));
+}
+
+const show = (file) => relative(projectDir, file) || file;
+
+/** The files in a folder that the tools lint, as ESLint skips node_modules. */
+function* walk(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+    a.name < b.name ? -1 : 1,
+  );
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules' && entry.name !== '.git') {
+        yield* walk(path);
+      }
+    } else if (isLintable(entry.name)) {
+      yield path;
+    }
+  }
+}
+
+// Each file gets the rules its config sets, so files are linted in groups of
+// the same rules and settings. A file named on the command line that is not
+// linted is reported; one found in a folder is skipped quietly, as ESLint does.
+const resolver = createConfigResolver({
+  ESLint,
+  plugin,
+  packageRoot: PACKAGE_ROOT,
+});
+const groups = new Map();
+const skipped = [];
+const configs = new Set();
+for (const target of targets) {
+  const named = !statSync(target).isDirectory();
+  for (const file of named ? [target] : walk(target)) {
+    if (!isLintable(file)) {
+      skipped.push({
+        file: show(file),
+        reason: 'not a JavaScript or TypeScript file.',
+      });
+      continue;
+    }
+    let project;
+    try {
+      project = await resolver.forFile(file);
+    } catch (error) {
+      fail(
+        `cannot read the lint config for ${show(file)}: ${errorText(error)}`,
+      );
+    }
+    const config = project.source && show(project.source.file);
+    const lint = lintOptions(project, {
+      recommended,
+      strict,
+      useStrict: options.strict,
+      projectDir,
+    });
+    if (project.ignored || !Object.values(lint.rules).some(isOn)) {
+      if (named) {
+        skipped.push({
+          file: show(file),
+          reason: project.ignored
+            ? `${config} does not lint it.`
+            : `${config} runs no tasty/* rule on it.`,
+        });
+      }
+      continue;
+    }
+    if (config) configs.add(config);
+    const key = JSON.stringify(lint);
+    if (!groups.has(key)) groups.set(key, { lint, files: [], config });
+    groups.get(key).files.push(file);
+  }
+}
+
+const results = [];
+for (const { lint, files } of groups.values()) {
+  const eslint = createLinter({ ESLint, plugin, parser, espree, ...lint });
+  try {
+    results.push(...(await eslint.lintFiles(files)));
+  } catch (error) {
+    fail(errorText(error));
+  }
+}
+results.sort((a, b) => (a.filePath < b.filePath ? -1 : 1));
+
+if (!parser && results.some((result) => isTypeScript(result.filePath))) {
+  fail(NO_PARSER);
+}
+
+// Paths print relative to the project root, as harnesspm runs from there.
+const collected = collectProblems(results, projectDir);
+const { problems } = collected;
+skipped.push(...collected.skipped);
+const pageOf = (name) =>
+  rulePage(name, { projectDir, packageRoot: PACKAGE_ROOT, cwd: projectDir });
+const errors = problems.filter((p) => p.severity === 'error').length;
+const linted = results.length - collected.skipped.length;
+
+// Which rules ran: a config's, with --strict also the strict preset's others,
+// and the preset for files without a config.
+const sources = [...new Set([...groups.values()].map((g) => g.config ?? null))];
+const ruleset = sources
+  .map((config) =>
+    config
+      ? `rules from ${config}${options.strict ? ' and the strict preset' : ''}`
+      : `${preset} rules`,
+  )
+  .join('; ');
+
+if (options.json) {
+  console.log(
+    JSON.stringify(
+      {
+        preset,
+        configs: [...configs],
+        files: results.map((r) => r.filePath),
+        linted,
+        problems: problems.map((p) => ({
+          ...p,
+          page: p.rule ? pageOf(p.rule.slice('tasty/'.length)) : null,
+        })),
+        skipped,
+      },
+      null,
+      2,
+    ),
+  );
+} else {
+  const out = [];
+  const count = `${linted} file${linted === 1 ? '' : 's'}`;
+  if (linted === 0) {
+    out.push(`Nothing linted in ${paths.join(', ')}.`);
+  } else if (problems.length === 0) {
+    out.push(`No tasty/* problems in ${count} (${ruleset}).`);
+  } else {
+    out.push(
+      formatProblems(problems, pageOf),
+      '',
+      `${summarize(problems)} in ${count} (${ruleset}).`,
+    );
+  }
+  for (const s of skipped) out.push(`Skipped ${s.file}: ${s.reason}`);
+  if (linted === 0 && skipped.length === 0) {
+    out.push(
+      'Pass .js, .jsx, .ts or .tsx files of the project, or folders with them.',
+    );
+  }
+  console.log(out.join('\n'));
+}
+
+// Nothing linted is not a pass.
+process.exit(errors > 0 ? 1 : linted === 0 ? 2 : 0);

package/harness/dev.harnesspm/scripts/lint.mjs

@@ -0,0 +1,318 @@
+/**
+ * What `tasty-lint:check` and the `check-edit` hook compute. The functions
+ * that lint take ESLint's class, the plugin and the parser as arguments: the
+ * tools pass the project's ESLint and this package's `dist/` build, and
+ * `src/harness.test.ts` passes the source, so most tests need no build.
+ */
+import { existsSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SOURCES } from './project-config.mjs';
+
+/** Files the tools lint: JavaScript and TypeScript, with or without JSX. */
+const LINTABLE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+const TYPESCRIPT = /\.(?:[cm]?ts|tsx)$/;
+const DECLARATION = /\.d\.[cm]?ts$/;
+
+/** Tasty's own modules, which every import source list includes. */
+const TASTY = '@tenphi/tasty';
+
+export function isLintable(file) {
+  return LINTABLE.test(file) && !DECLARATION.test(file);
+}
+
+export function isTypeScript(file) {
+  return TYPESCRIPT.test(file);
+}
+
+/**
+ * Whether the text imports from Tasty or one of `sources`, subpaths included:
+ * a text test that runs before anything is parsed.
+ */
+export function importsFrom(text, sources = []) {
+  for (const source of new Set([TASTY, ...sources])) {
+    const escaped = source.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+    if (new RegExp(`(['"\`])${escaped}(?:/[^'"\`]*)?\\1`).test(text)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Oxlint reads `oxlint-disable`, `oxlint-disable-next-line`,
+ * `oxlint-disable-line` and `oxlint-enable` comments as ESLint reads the
+ * `eslint-` ones, and also takes `eslint-disable` and `eslint-enable` in line
+ * comments, which ESLint skips. ESLint reads directives from each comment's
+ * `value`, so the parser below rewrites the value of those comments after
+ * parsing. The source text is not touched, so strings, code, lines and
+ * columns stay as they are.
+ */
+const OXLINT_DIRECTIVE =
+  /^(\s*)oxlint-(disable(?:-next-line|-line)?|enable)(?=\s|$)/;
+const BLOCK_DIRECTIVE = /^\s*eslint-(?:disable|enable)(?=\s|$)/;
+
+export function readOxlintComments(comment) {
+  comment.value = comment.value.replace(OXLINT_DIRECTIVE, '$1eslint-$2');
+  if (comment.type === 'Line' && BLOCK_DIRECTIVE.test(comment.value)) {
+    comment.type = 'Block';
+  }
+}
+
+/** The parser with Oxlint's disable comments read as ESLint's. */
+export function withOxlintComments(parser) {
+  return {
+    meta: { name: 'tasty-lint/oxlint-comments' },
+    parseForESLint(text, options) {
+      const result =
+        typeof parser.parseForESLint === 'function'
+          ? parser.parseForESLint(text, options)
+          : { ast: parser.parse(text, options) };
+      for (const comment of result.ast.comments ?? []) {
+        readOxlintComments(comment);
+      }
+      return result;
+    },
+  };
+}
+
+/**
+ * The ESLint flat config that runs only this plugin's rules: `rules` and
+ * `settings` (`settings.tasty`) come from the project's lint config, or the
+ * rules from a preset. `espree` is ESLint's own parser, for JavaScript, and
+ * `parser` the TypeScript one. With `oxlintComments`, Oxlint's disable
+ * comments count too.
+ */
+export function lintConfig({
+  plugin,
+  rules,
+  settings = {},
+  parser,
+  espree,
+  oxlintComments = true,
+}) {
+  const read = (p) => (oxlintComments ? withOxlintComments(p) : p);
+  const config = [
+    {
+      files: [SOURCES],
+      plugins: { tasty: plugin },
+      // Directives for other plugins' rules are not this tool's business.
+      linterOptions: { reportUnusedDisableDirectives: false },
+      languageOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        ...(espree ? { parser: read(espree) } : {}),
+        parserOptions: { ecmaFeatures: { jsx: true } },
+      },
+      settings: { tasty: settings },
+      rules,
+    },
+  ];
+  if (parser) {
+    config.push({
+      files: ['**/*.{ts,tsx,mts,cts}'],
+      // The parser prints its TypeScript version warning on stdout, which
+      // would break --json. The project's own lint still shows it.
+      languageOptions: {
+        parser: read(parser),
+        parserOptions: { loggerFn: false },
+      },
+    });
+  }
+  return config;
+}
+
+export function createLinter({ ESLint, cwd, ...options }) {
+  return new ESLint({
+    cwd,
+    overrideConfigFile: true,
+    overrideConfig: lintConfig(options),
+    errorOnUnmatchedPattern: false,
+  });
+}
+
+/**
+ * What to lint a file with, from what `createConfigResolver().forFile()` found:
+ * the project's rules and settings, or the recommended preset when no config
+ * loads the plugin. `useStrict` adds the strict preset's rules that the config
+ * does not set. Rules and patterns resolve from the config's folder.
+ */
+export function lintOptions(
+  project,
+  { recommended, strict, useStrict = false, projectDir },
+) {
+  let rules = useStrict ? strict : recommended;
+  if (project.rules) {
+    rules = useStrict ? { ...strict, ...project.rules } : project.rules;
+  }
+  return {
+    rules,
+    settings: project.settings,
+    oxlintComments: project.source?.linter !== 'eslint',
+    cwd: project.source?.dir ?? projectDir,
+  };
+}
+
+/**
+ * The problems in ESLint's results: this plugin's rules and parse errors. A
+ * message with no rule that is not fatal says that ESLint skipped the file.
+ */
+export function collectProblems(results, cwd) {
+  const problems = [];
+  const skipped = [];
+  for (const result of results) {
+    const file = relative(cwd, result.filePath) || result.filePath;
+    for (const message of result.messages) {
+      if (message.ruleId === null && !message.fatal) {
+        skipped.push({ file, reason: message.message });
+        continue;
+      }
+      if (!message.fatal && !message.ruleId?.startsWith('tasty/')) continue;
+      problems.push({
+        file,
+        line: message.line ?? 0,
+        column: message.column ?? 0,
+        rule: message.fatal ? null : message.ruleId,
+        severity: message.severity === 2 ? 'error' : 'warning',
+        message: message.message,
+      });
+    }
+  }
+  return { problems, skipped };
+}
+
+/**
+ * The problems in `after` that `before` does not have. Two problems match by
+ * rule, message and the text of their line, so lines that moved still match.
+ */
+export function newProblems(after, afterText, before, beforeText) {
+  const afterLines = afterText.split('\n');
+  const beforeLines = beforeText.split('\n');
+  const key = (problem, lines) =>
+    [problem.rule, problem.message, lines[problem.line - 1]?.trim()].join('\0');
+  const left = new Map();
+  for (const problem of before) {
+    const k = key(problem, beforeLines);
+    left.set(k, (left.get(k) ?? 0) + 1);
+  }
+  return after.filter((problem) => {
+    const k = key(problem, afterLines);
+    const count = left.get(k) ?? 0;
+    if (count === 0) return true;
+    left.set(k, count - 1);
+    return false;
+  });
+}
+
+/** The rule name without the `tasty/` prefix. */
+export function ruleName(rule) {
+  return rule.slice('tasty/'.length);
+}
+
+/**
+ * One line per problem, `file:line:col  tasty/<rule>  <severity>  message`,
+ * then the page of each rule reported. Without the severity, an agent in the
+ * end-to-end run guessed it, and wrongly. `pageOf` turns a rule name into the
+ * path to show.
+ */
+export function formatProblems(problems, pageOf) {
+  const lines = problems.map((p) =>
+    p.rule
+      ? `${p.file}:${p.line}:${p.column}  ${p.rule}  ${p.severity}  ${p.message}`
+      : `${p.file}:${p.line}:${p.column}  parse error  ${p.message}`,
+  );
+  const rules = [...new Set(problems.map((p) => p.rule).filter(Boolean))];
+  if (rules.length > 0) {
+    lines.push('', 'Rule pages:');
+    for (const rule of rules)
+      lines.push(`  ${rule}  ${pageOf(ruleName(rule))}`);
+  }
+  return lines.join('\n');
+}
+
+export function summarize(problems) {
+  const errors = problems.filter((p) => p.severity === 'error').length;
+  const warnings = problems.length - errors;
+  const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+  return `${count(problems.length, 'problem')} (${count(errors, 'error')}, ${count(warnings, 'warning')})`;
+}
+
+/** The path of a module as `dir` resolves it, or undefined. */
+function resolveFrom(dir, specifier) {
+  try {
+    return createRequire(join(dir, 'noop.js')).resolve(specifier);
+  } catch {
+    return undefined;
+  }
+}
+
+async function importFile(file) {
+  const mod = await import(pathToFileURL(file).href);
+  return mod.default ?? mod;
+}
+
+export const NO_ESLINT =
+  'cannot find eslint. Install it in the project as a dev dependency: it is a peer dependency of @tenphi/eslint-plugin-tasty, and the tool runs the Tasty rules through ESLint even in a project that lints with Oxlint.';
+
+/**
+ * ESLint as the project installs it, else the copy this package resolves: the
+ * flat config class (ESLint 9 and later, or 8.57 through `loadESLint()`), and
+ * espree, its JavaScript parser. Without ESLint, the error's `code` is
+ * `NO_ESLINT`.
+ */
+export async function loadESLint(dirs, packageRoot) {
+  for (const dir of [...dirs, packageRoot]) {
+    const file = resolveFrom(dir, 'eslint');
+    if (!file) continue;
+    const eslint = await importFile(file);
+    if (typeof eslint.loadESLint !== 'function') {
+      throw new Error(
+        `ESLint ${eslint.ESLint?.version ?? ''} at ${dirname(file)} is too old: the tool needs ESLint 8.57 or later.`,
+      );
+    }
+    const espree = resolveFrom(dirname(file), 'espree');
+    return {
+      ESLint: await eslint.loadESLint({ useFlatConfig: true }),
+      espree: espree ? await importFile(espree) : undefined,
+    };
+  }
+  throw Object.assign(new Error(NO_ESLINT), { code: 'NO_ESLINT' });
+}
+
+/**
+ * The TypeScript parser the project installs: `@typescript-eslint/parser`, or
+ * the one `typescript-eslint` depends on. Undefined when there is none.
+ */
+export async function loadTypeScriptParser(dirs) {
+  for (const dir of dirs) {
+    let file = resolveFrom(dir, '@typescript-eslint/parser');
+    if (!file) {
+      const manifest = resolveFrom(dir, 'typescript-eslint/package.json');
+      if (manifest) {
+        file = resolveFrom(
+          dirname(realpathSync(manifest)),
+          '@typescript-eslint/parser',
+        );
+      }
+    }
+    if (file) return importFile(file);
+  }
+  return undefined;
+}
+
+export const NO_PARSER =
+  'Linting TypeScript needs a TypeScript parser, and this project has none. Install typescript-eslint (or @typescript-eslint/parser) as a dev dependency.';
+
+/**
+ * The path to show for a rule's page: through the stable link harnesspm keeps
+ * in the project when it exists, else in this package.
+ */
+export function rulePage(name, { projectDir, packageRoot, cwd }) {
+  const stable = join(
+    projectDir,
+    'node_modules/.harnesspm/pkgs/@tenphi/eslint-plugin-tasty',
+  );
+  const root = existsSync(stable) ? stable : packageRoot;
+  return relative(cwd, join(root, 'docs/rules', `${name}.md`));
+}