@tenphi/eslint-plugin-tasty 1.17.1 → 1.19.0

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

@@ -0,0 +1,159 @@
+/**
+ * tasty-lint:check — lints files with this plugin's Tasty rules only, with the
+ * project's tasty.config.* and ESLint.
+ */
+import { existsSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  NO_PARSER,
+  collectProblems,
+  createLinter,
+  formatProblems,
+  isTypeScript,
+  loadESLint,
+  loadTypeScriptParser,
+  rulePage,
+  summarize,
+} from './lint.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: the
+recommended preset, or the strict one with --strict. The rules read the
+project's tasty.config.* as they do in the project's own lint.
+
+It does not read the project's ESLint or Oxlint config, so other plugins, rule
+options and settings such as typeAwareJSX do not apply. Disable comments such
+as // eslint-disable-next-line tasty/<rule> -- <reason> do.
+
+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 rules only the strict preset enables
+--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 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 parser;
+try {
+  ESLint = await loadESLint([cwd, projectDir], PACKAGE_ROOT);
+  parser = await loadTypeScriptParser([cwd, projectDir]);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}
+
+const eslint = createLinter({
+  ESLint,
+  plugin,
+  rules: options.strict ? strict : recommended,
+  parser,
+  cwd: projectDir,
+});
+
+let results;
+try {
+  results = await eslint.lintFiles(targets);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}
+
+if (!parser && results.some((result) => isTypeScript(result.filePath))) {
+  fail(NO_PARSER);
+}
+
+// Paths print relative to the project root, as harnesspm runs from there.
+const { problems, skipped } = collectProblems(results, projectDir);
+const pageOf = (name) =>
+  rulePage(name, { projectDir, packageRoot: PACKAGE_ROOT, cwd: projectDir });
+const errors = problems.filter((p) => p.severity === 'error').length;
+const linted = results.length - skipped.length;
+
+if (options.json) {
+  console.log(
+    JSON.stringify(
+      {
+        preset,
+        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} (${preset} rules).`);
+  } else {
+    out.push(
+      formatProblems(problems, pageOf),
+      '',
+      `${summarize(problems)} in ${count} (${preset} rules).`,
+    );
+  }
+  for (const s of skipped) out.push(`Skipped ${s.file}: ${s.reason}`);
+  if (results.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,236 @@
+/**
+ * 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';
+
+/** 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;
+}
+
+/**
+ * The ESLint flat config that runs only this plugin's rules. It does not read
+ * the project's linter config, so `settings.tasty` is empty: in particular
+ * `typeAwareJSX`, which builds a TypeScript program, stays off.
+ */
+export function lintConfig({ plugin, rules, parser }) {
+  const config = [
+    {
+      files: ['**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}'],
+      plugins: { tasty: plugin },
+      // Directives for other plugins' rules are not this tool's business.
+      linterOptions: { reportUnusedDisableDirectives: false },
+      languageOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        parserOptions: { ecmaFeatures: { jsx: true } },
+      },
+      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, parserOptions: { loggerFn: false } },
+    });
+  }
+  return config;
+}
+
+export function createLinter({ ESLint, plugin, rules, parser, cwd }) {
+  return new ESLint({
+    cwd,
+    overrideConfigFile: true,
+    overrideConfig: lintConfig({ plugin, rules, parser }),
+    errorOnUnmatchedPattern: false,
+  });
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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()`.
+ */
+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') {
+      return eslint.loadESLint({ useFlatConfig: true });
+    }
+    throw new Error(
+      `ESLint ${eslint.ESLint?.version ?? ''} at ${dirname(file)} is too old: the tool needs ESLint 8.57 or later.`,
+    );
+  }
+  throw new Error(
+    'cannot find eslint. Install it in the project: it is a peer dependency of @tenphi/eslint-plugin-tasty.',
+  );
+}
+
+/**
+ * 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`));
+}

package/harness/plugin.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "tasty-lint",
+  "description": "Lint Tasty styles: a rule to lint what you change, a page for every tasty/* rule, a tool that runs only the Tasty rules, and a hook that lints each edited file",
+  "homepage": "https://github.com/tenphi/eslint-plugin-tasty#readme",
+  "repository": "https://github.com/tenphi/eslint-plugin-tasty",
+  "keywords": ["tasty", "eslint", "oxlint", "lint", "styles"],
+  "extensions": {
+    "dev.harnesspm": {
+      "docs": "../docs",
+      "scripts": {
+        "check": {
+          "file": "./dev.harnesspm/scripts/check.mjs",
+          "description": "Lint files or folders with only the tasty/* rules (recommended, or --strict) and the project's tasty.config, and print each problem with its rule's page",
+          "allow": true
+        },
+        "check-edit": {
+          "file": "./dev.harnesspm/scripts/check-edit.mjs"
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/eslint-plugin-tasty",
-  "version": "1.17.1",
+  "version": "1.19.0",
   "description": "ESLint plugin for validating tasty() and tastyStatic() style objects",
   "type": "module",
   "exports": {
@@ -12,7 +12,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "harness"
   ],
   "sideEffects": false,
   "engines": {
@@ -53,7 +55,8 @@
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.31.1",
     "@eslint/js": "^10.0.1",
-    "@tenphi/tasty": "^3.17.1",
+    "@tenphi/harnesspm": "^0.2.0",
+    "@tenphi/tasty": "^3.19.0",
     "@types/node": "^22.0.0",
     "@types/semver": "^7.8.0",
     "@typescript-eslint/parser": "^8.56.1",
@@ -85,10 +88,11 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\"",
+    "lint": "eslint src harness",
+    "lint:fix": "eslint src harness --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"harness/**/*.mjs\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"harness/**/*.mjs\"",
+    "check:harness": "harnesspm check",
     "generate:css-properties": "node scripts/generate-css-properties.mjs",
     "changeset": "changeset",
     "version": "changeset version",