slop-police 0.2.0 → 0.3.0

package/README.md

@@ -1,19 +1,24 @@
-# slop-police
+<h1 align="center">slop-police</h1>
 
-A fast, type-aware linter for TypeScript that catches the dead code and needless indirection AI coding agents tend to leave behind: methods nobody calls, object keys nobody reads, getters, aliases and wrappers that only rename or forward something, helpers copied instead of reused, comments that only promise future work, and errors swallowed or flattened into strings.
+<p align="center"><b>Stop LLM crimes in your codebase</b></p>
 
-It runs the TypeScript 7 compiler in-process, so rules resolve symbols the same way `tsc` does, across all of your tsconfig projects at once.
+<p align="center">
+A type-aware TypeScript linter for the dead code and needless indirection AI agents leave behind.
+</p>
 
-```sh
-npm i -D slop-police
-npx slop-police
-```
+| | pnpm | npm |
+| --- | --- | --- |
+| Add to the project | `pnpm add -D slop-police` | `npm i -D slop-police` |
+| Run | `pnpm exec slop-police` | `npx slop-police` |
+| Run once, no install | `pnpm dlx slop-police` | `npx slop-police` |
+
+Example output:
 
 ```
 packages/frontend/src/store/deck-store.ts:42:3  error  unused-methods      Method DeckStore.reset is never used
 packages/api/src/shared/links/links.ts:30:3     error  unused-object-keys  links.privacyPolicy is never read
 
-2 problems (2 errors, 0 warnings)
+2 errors, 0 warnings
 ```
 
 ## Configuration
@@ -45,6 +50,7 @@ slop-police reads `slop-police.json` from the current directory:
 - `ignore`: glob patterns (relative to the config) for files to skip entirely.
 - `testFiles`: glob patterns for tests. Usages inside tests count, but declarations inside tests are not reported.
 - `rules`: `"error"`, `"warn"` or `"off"`, or `[severity, options]`. Rules that aren't listed are off.
+- `plugins`: modules with [custom rules](#custom-rules), as paths relative to the config or package names.
 
 Exit code is `1` when there are errors, `2` for an invalid config, `0` otherwise.
 
@@ -62,7 +68,7 @@ class Store {
 new Store().load();
 ```
 
-A member also counts as used when it implements an interface member that is used, when it's named in `Pick<Class, "name">`, or when an instance is passed to a JSX prop whose type requires it. Options: `includePrivate` and `includeProtected` (both `false` by default).
+A member also counts as used when it implements an interface member that is used or that is declared outside the analyzed code (a library calls it), when it's named in `Pick<Class, "name">`, or when an instance is passed to a JSX prop whose type requires it. Options: `includePrivate` and `includeProtected` (both `false` by default).
 
 ### unused-object-keys
 
@@ -174,7 +180,7 @@ const enabled = await fetchFlag().catch((error) => { // Promise rejection is log
 
 ### no-stringified-unknown-error
 
-`error instanceof Error ? error.message : String(error)` (in either order), which flattens a caught value into a string and drops its type, stack and cause. A plain `instanceof Error` check counts when the variable is named `error`, `err`, `e` or `cause`; an `||` of `instanceof` checks counts for any name.
+`error instanceof Error ? error.message : String(error)` (in either order), which flattens a caught value into a string and drops its type, stack and cause. A plain `instanceof Error` check counts when the variable is named `error`, `err`, `e` or `cause`; an `||` of `instanceof` checks counts for any name. A function that does nothing but this conversion, like `getErrorMessage(error)`, is where it belongs and isn't reported; use it instead of repeating the expression.
 
 ```ts
 try {
@@ -184,6 +190,101 @@ try {
 }
 ```
 
+## Custom rules
+
+Write rules in TypeScript or JavaScript, list their modules in `plugins` and enable them in `rules` like built-in ones:
+
+```json
+{
+  "projects": ["tsconfig.json"],
+  "plugins": ["./slop-rules.ts"],
+  "rules": {
+    "no-direct-fetch": ["error", { "allowIn": "src/api/" }],
+    "no-needless-nullish-fallback": "warn"
+  }
+}
+```
+
+A plugin exports rules made with `defineRule`, by default or by name. `visit` has a handler per node kind, called for every node of that kind in every linted file:
+
+```ts
+// slop-rules.ts
+import { defineRule, isIdentifier, SyntaxKind } from "slop-police";
+
+export const noDirectFetch = defineRule({
+  name: "no-direct-fetch",
+  // Option defaults. The config's options must have the same types.
+  options: { allowIn: "" },
+  visit: {
+    CallExpression(node, ctx) {
+      if (ctx.options.allowIn && ctx.file.path.startsWith(ctx.options.allowIn)) return;
+      if (isIdentifier(node.expression) && node.expression.text === "fetch") {
+        ctx.report(node.expression, "Use the API client instead of fetch()");
+      }
+    },
+  },
+});
+
+export const noNeedlessNullishFallback = defineRule({
+  name: "no-needless-nullish-fallback",
+  visit: {
+    BinaryExpression(node, ctx) {
+      if (node.operatorToken.kind !== SyntaxKind.QuestionQuestionToken) return;
+      const { checker } = ctx;
+      const type = checker.getTypeAtLocation(node.left);
+      if (!type) return;
+      const nullable = [checker.getUndefinedType(), checker.getNullType()].some((t) => checker.isTypeAssignableTo(t, type));
+      if (!nullable) ctx.report(node.right, `${node.left.getText()} is never null or undefined`);
+    },
+  },
+});
+```
+
+Nodes, `SyntaxKind`, the `is*` guards and the checker come from the TypeScript 7 API that slop-police runs on. The handler's `ctx` has:
+
+- `options`: the defaults merged with the config's options.
+- `file`: the file being visited: `path` (relative to the config), `fileName`, `isTest` and `sourceFile`.
+- `checker` and `program`: those of the file's project. Each checker call is a round trip to the linter process, so check the syntax first.
+- `report(node, message)`: reports a finding at the node's start. `// slop-police-ignore` comments work as for built-in rules.
+
+For rules that compare files, `create(ctx)` returns the visitor instead, so its state lives in a closure, and `finish` runs after the last file:
+
+```ts
+import { defineRule, type Node } from "slop-police";
+
+export const noRepeatedUrl = defineRule({
+  name: "no-repeated-url",
+  create(ctx) {
+    const byUrl = new Map<string, Node[]>();
+    return {
+      StringLiteral(node) {
+        if (node.text.startsWith("https://")) byUrl.set(node.text, [...(byUrl.get(node.text) ?? []), node]);
+      },
+      finish() {
+        for (const [url, nodes] of byUrl) {
+          if (nodes.length > 2) for (const node of nodes) ctx.report(node, `${url} is hard-coded in ${nodes.length} places`);
+        }
+      },
+    };
+  },
+});
+```
+
+Test rules with `lint` from `slop-police/testing`, which runs a rule alone on a source string (or on files, given an object of paths to contents) in a strict TypeScript project:
+
+```ts
+import { lint } from "slop-police/testing";
+import { noDirectFetch } from "./slop-rules.ts";
+
+test("no-direct-fetch", () => {
+  expect(lint(noDirectFetch, `fetch("/users");`)).toEqual([
+    { line: 1, column: 1, message: "Use the API client instead of fetch()" },
+  ]);
+});
+```
+
+Plugins need the npm launcher (`npx slop-police` or `pnpm exec slop-police`), which runs them in Node while the linter serves ASTs and types. TypeScript plugins need Node.js 22.18 or later, and published plugin packages must ship JavaScript.
+
 ## Ignoring findings
 
 A `// slop-police-ignore` comment directly above a statement, class member or object property silences findings in it, including everything nested inside. List rule names to silence only those, and add a reason after `--`:

package/bin/slop-police.js

@@ -1,18 +1,37 @@
 #!/usr/bin/env node
-const { spawnSync } = require("node:child_process");
-
-const platformPackage = `slop-police-${process.platform}-${process.arch}`;
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { findBinary } from "../lib/binary.js";
 
 let binary;
 try {
-  binary = require.resolve(`${platformPackage}/bin/slop-police`);
-} catch {
-  console.error(
-    `slop-police: no binary for ${process.platform}-${process.arch}. Supported: macOS and Linux on arm64 and x64 (use WSL on Windows).`,
-  );
+  binary = findBinary();
+} catch (error) {
+  console.error(error.message);
   process.exit(2);
 }
 
-const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
-if (result.error) throw result.error;
-process.exitCode = result.status ?? 1;
+const root = process.cwd();
+const plugins = configuredPlugins(root);
+if (plugins) {
+  // Plugin rules run here, in Node, with the binary serving ASTs and types.
+  const { run } = await import("../lib/runner.js");
+  process.exitCode = await run(binary, root, plugins);
+} else {
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}
+
+// configuredPlugins returns the config's plugins, if it has any. Any problem
+// with the config is left to the binary to report.
+function configuredPlugins(root) {
+  try {
+    const { plugins } = JSON.parse(fs.readFileSync(path.join(root, "slop-police.json"), "utf8"));
+    if (Array.isArray(plugins) && plugins.length > 0 && plugins.every((plugin) => typeof plugin === "string")) {
+      return plugins;
+    }
+  } catch {}
+  return undefined;
+}

package/lib/binary.js

@@ -0,0 +1,18 @@
+import { createRequire } from "node:module";
+
+// findBinary returns the path of the prebuilt binary from the platform package
+// npm installed for this machine. SLOP_POLICE_BINARY overrides it, for
+// developing slop-police itself.
+export function findBinary() {
+  if (process.env.SLOP_POLICE_BINARY) {
+    return process.env.SLOP_POLICE_BINARY;
+  }
+  const platformPackage = `slop-police-${process.platform}-${process.arch}`;
+  try {
+    return createRequire(import.meta.url).resolve(`${platformPackage}/bin/slop-police`);
+  } catch {
+    throw new Error(
+      `slop-police: no binary for ${process.platform}-${process.arch}. Supported: macOS and Linux on arm64 and x64 (use WSL on Windows).`,
+    );
+  }
+}

package/lib/index.d.ts

@@ -0,0 +1,119 @@
+// TypeScript's API declarations use Symbol.dispose.
+/// <reference lib="esnext.disposable" />
+import type { Checker, Program } from "./typescript/dist/api/sync/api.js";
+import type { Node, SourceFile, SyntaxKind } from "./typescript/dist/ast/index.js";
+import type { NodesByKind } from "./typescript/nodes-by-kind.js";
+
+export * from "./typescript/dist/ast/index.js";
+export {
+  ElementFlags,
+  isBigIntLiteralType,
+  isBooleanLiteralType,
+  isClassOrInterfaceType,
+  isConditionalType,
+  isErrorType,
+  isIndexedAccessType,
+  isIndexType,
+  isIntersectionType,
+  isIntrinsicType,
+  isLiteralType,
+  isNumberLiteralType,
+  isObjectType,
+  isStringLiteralType,
+  isStringMappingType,
+  isSubstitutionType,
+  isTemplateLiteralType,
+  isTupleType,
+  isTypeParameter,
+  isTypeReference,
+  isUnionType,
+  NodeBuilderFlags,
+  ObjectFlags,
+  SignatureFlags,
+  SignatureKind,
+  SymbolFlags,
+  TypeFlags,
+  TypePredicateKind,
+} from "./typescript/dist/api/sync/api.js";
+export type {
+  Checker,
+  ConditionalType,
+  IndexedAccessType,
+  IndexType,
+  InterfaceType,
+  IntersectionType,
+  IntrinsicType,
+  LiteralType,
+  ObjectType,
+  Program,
+  Signature,
+  StringLiteralType,
+  Symbol,
+  TupleType,
+  Type,
+  TypeParameter,
+  TypeReference,
+  UnionType,
+} from "./typescript/dist/api/sync/api.js";
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** Option defaults. The config's values must have the same JSON types. */
+export type RuleOptions = Record<string, JsonValue>;
+
+export interface LintedFile {
+  /** The path relative to slop-police.json, with forward slashes. */
+  readonly path: string;
+  /** The absolute path. */
+  readonly fileName: string;
+  /** Whether the file matches the config's testFiles. */
+  readonly isTest: boolean;
+  readonly sourceFile: SourceFile;
+}
+
+export interface RuleContext<Options extends RuleOptions = {}> {
+  /** The rule's option defaults, merged with the options from the config. */
+  readonly options: Options;
+  /** The file being visited. Undefined in finish. */
+  readonly file: LintedFile;
+  /** The type checker of the file's project. Undefined in finish. */
+  readonly checker: Checker;
+  /** The program of the file's project. Undefined in finish. */
+  readonly program: Program;
+  /**
+   * Reports a finding at the start of node, which can be in any linted file.
+   * `// slop-police-ignore` comments apply as for built-in rules.
+   */
+  report(node: Node, message: string): void;
+}
+
+type NodeOfKind<Kind extends string> = Kind extends keyof NodesByKind ? NodesByKind[Kind] : Node;
+
+/**
+ * Handlers by SyntaxKind name, called for every node of that kind in every
+ * linted file, plus finish, called once after the last file.
+ */
+export type Visitor<Options extends RuleOptions = {}> = {
+  [Kind in keyof typeof SyntaxKind]?: (node: NodeOfKind<Kind>, ctx: RuleContext<Options>) => void;
+} & {
+  finish?: (ctx: RuleContext<Options>) => void;
+};
+
+interface RuleBase<Options extends RuleOptions> {
+  /** The name to enable the rule with in slop-police.json and to list in ignore comments. */
+  name: string;
+  /** Option defaults, which also set the types of the options the config can pass. */
+  options?: Options;
+}
+
+export type Rule<Options extends RuleOptions = {}> = RuleBase<Options> &
+  (
+    | { visit: Visitor<Options>; create?: never }
+    | {
+        /** Called once per run, for rules that keep state across files. Returns the visitor. */
+        create(ctx: RuleContext<Options>): Visitor<Options>;
+        visit?: never;
+      }
+  );
+
+export declare function defineRule<Options extends RuleOptions = {}>(rule: Rule<Options>): Rule<Options>;

package/lib/index.js

@@ -0,0 +1,35 @@
+// The API for plugin rules: defineRule, plus TypeScript 7's AST (node types,
+// SyntaxKind, is* guards and utilities) and the checker's enums and type
+// guards.
+export * from "./typescript/dist/ast/index.js";
+export {
+  ElementFlags,
+  isBigIntLiteralType,
+  isBooleanLiteralType,
+  isClassOrInterfaceType,
+  isConditionalType,
+  isErrorType,
+  isIndexedAccessType,
+  isIndexType,
+  isIntersectionType,
+  isIntrinsicType,
+  isLiteralType,
+  isNumberLiteralType,
+  isObjectType,
+  isStringLiteralType,
+  isStringMappingType,
+  isSubstitutionType,
+  isTemplateLiteralType,
+  isTupleType,
+  isTypeParameter,
+  isTypeReference,
+  isUnionType,
+  NodeBuilderFlags,
+  ObjectFlags,
+  SignatureFlags,
+  SignatureKind,
+  SymbolFlags,
+  TypeFlags,
+  TypePredicateKind,
+} from "./typescript/dist/api/sync/api.js";
+export { defineRule } from "./rule.js";

package/lib/rule.js

@@ -0,0 +1,54 @@
+import { isDeepStrictEqual } from "node:util";
+import { SyntaxKind } from "./typescript/dist/ast/index.js";
+
+// Marks rules made by defineRule, so plugins can export helpers next to them.
+// Symbol.for, so that rules from another copy of slop-police count too.
+const ruleBrand = Symbol.for("slop-police.rule");
+
+export function defineRule(rule) {
+  const name = rule?.name;
+  if (typeof name !== "string" || !/^[^\s,]+$/.test(name)) {
+    throw new TypeError(`Rule name must be a non-empty string without spaces or commas, got ${JSON.stringify(name)}`);
+  }
+  if ((rule.visit === undefined) === (rule.create === undefined)) {
+    throw new TypeError(`Rule ${name} must have either visit or create`);
+  }
+  if (rule.create !== undefined && typeof rule.create !== "function") {
+    throw new TypeError(`Rule ${name}: create must be a function`);
+  }
+  // The defaults go through the binary, which merges the config's options
+  // into them, as JSON.
+  const { options } = rule;
+  if (
+    options !== undefined &&
+    (typeof options !== "object" || options === null || Array.isArray(options) || !isDeepStrictEqual(JSON.parse(JSON.stringify(options)), options))
+  ) {
+    throw new TypeError(`Rule ${name}: options must be an object of JSON default values`);
+  }
+  if (rule.visit !== undefined) {
+    visitorHandlers(name, rule.visit);
+  }
+  return Object.freeze({ ...rule, [ruleBrand]: true });
+}
+
+export function isRule(value) {
+  return value?.[ruleBrand] === true;
+}
+
+// visitorHandlers checks a visitor and returns its handlers as [kind, handler]
+// pairs, where kind is a SyntaxKind or "finish".
+export function visitorHandlers(ruleName, visitor) {
+  if (typeof visitor !== "object" || visitor === null) {
+    throw new TypeError(`Rule ${ruleName}: the visitor must be an object`);
+  }
+  return Object.entries(visitor).map(([key, handler]) => {
+    const kind = key === "finish" ? key : SyntaxKind[key];
+    if (kind !== "finish" && typeof kind !== "number") {
+      throw new TypeError(`Rule ${ruleName}: unknown node kind ${key} in the visitor`);
+    }
+    if (typeof handler !== "function") {
+      throw new TypeError(`Rule ${ruleName}: visitor ${key} must be a function`);
+    }
+    return [kind, handler];
+  });
+}

package/lib/runner.js

@@ -0,0 +1,177 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { isRule, visitorHandlers } from "./rule.js";
+import { API } from "./typescript/dist/api/sync/api.js";
+
+// LintError is a failed run, with the exit code to report it with: 2 for
+// config errors, 1 for others.
+class LintError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+// run lints root with its plugins, prints the report and returns the exit
+// code, like the binary does without plugins.
+export async function run(binary, root, plugins) {
+  try {
+    const result = lint(binary, root, await loadPlugins(root, plugins));
+    process.stdout.write(`${result.output}\n`);
+    return result.exitCode;
+  } catch (error) {
+    if (error instanceof LintError) {
+      console.error(error.message);
+      return error.exitCode;
+    }
+    throw error;
+  }
+}
+
+// loadPlugins imports the plugins (paths relative to root, or package names)
+// and returns the rules they export, as a rule or an array of rules.
+async function loadPlugins(root, plugins) {
+  const rules = new Map();
+  for (const plugin of plugins) {
+    let exports;
+    try {
+      exports = await import(resolvePlugin(root, plugin));
+    } catch (error) {
+      throw new LintError(`Unable to load plugin ${plugin}: ${error.message}${loadHint(error, plugin)}`, 2);
+    }
+    const found = Object.values(exports).flat().filter(isRule);
+    if (found.length === 0) {
+      throw new LintError(`Plugin ${plugin} exports no rules (create them with defineRule)`, 2);
+    }
+    for (const rule of found) {
+      const existing = rules.get(rule.name);
+      if (existing && existing.rule !== rule) {
+        throw new LintError(`Rule ${rule.name} is defined in both ${existing.plugin} and ${plugin}`, 2);
+      }
+      rules.set(rule.name, { rule, plugin });
+    }
+  }
+  return [...rules.values()].map(({ rule }) => rule);
+}
+
+function resolvePlugin(root, plugin) {
+  if (plugin.startsWith(".") || path.isAbsolute(plugin)) {
+    return pathToFileURL(path.resolve(root, plugin)).href;
+  }
+  return pathToFileURL(createRequire(path.join(root, "package.json")).resolve(plugin)).href;
+}
+
+function loadHint(error, plugin) {
+  if (error.code === "ERR_UNKNOWN_FILE_EXTENSION" && /\.[cm]?tsx?$/.test(plugin)) {
+    return " (TypeScript plugins need Node.js 22.18 or later)";
+  }
+  return "";
+}
+
+// lint runs the built-in rules enabled in root's config in the binary and the
+// enabled ones among rules here, and returns the binary's report: {results,
+// output, exitCode}. It throws a LintError when the run fails.
+export function lint(binary, root, rules) {
+  const api = new API({ tsserverPath: binary, cwd: root });
+  try {
+    // The API has no public way to send requests of its own.
+    const { client } = api;
+    const start = client.apiRequest("slopPolice/start", {
+      rules: rules.map((rule) => ({ name: rule.name, options: rule.options ?? {} })),
+    });
+    if (start.error) {
+      throw new LintError(start.error, start.exitCode);
+    }
+    const findings = start.rules.length > 0 ? runRules(api, start, rules) : [];
+    return client.apiRequest("slopPolice/finish", { findings });
+  } finally {
+    api.close();
+  }
+}
+
+// runRules visits every analyzed file once, calling the enabled rules'
+// handlers for each node, and returns their findings.
+function runRules(api, start, rules) {
+  const snapshot = api.updateSnapshot({ openProjects: [...new Set(start.files.map((file) => file.project))] });
+  const byName = new Map(rules.map((rule) => [rule.name, rule]));
+  const findings = [];
+  const handlers = []; // [rule name, ctx, handler] by SyntaxKind
+  const finishers = [];
+  let current; // the file being visited, and its project
+
+  for (const { name, options } of start.rules) {
+    const rule = byName.get(name);
+    const ctx = {
+      options,
+      get file() {
+        return current?.file;
+      },
+      get checker() {
+        return current?.project.checker;
+      },
+      get program() {
+        return current?.project.program;
+      },
+      report(node, message) {
+        if (typeof node?.id !== "string") {
+          throw new TypeError("report() takes a node of a linted file");
+        }
+        findings.push({ rule: name, node: node.id, message: String(message) });
+      },
+    };
+    let visitor = rule.visit;
+    if (rule.create) {
+      try {
+        visitor = rule.create(ctx);
+      } catch (error) {
+        throw ruleError(name, "in create", error);
+      }
+    }
+    for (const [kind, handler] of visitorHandlers(name, visitor)) {
+      if (kind === "finish") {
+        finishers.push([name, ctx, handler]);
+      } else {
+        (handlers[kind] ??= []).push([name, ctx, handler]);
+      }
+    }
+  }
+
+  const visit = (node) => {
+    const list = handlers[node.kind];
+    if (list) {
+      for (const [name, ctx, handler] of list) {
+        try {
+          handler(node, ctx);
+        } catch (error) {
+          throw ruleError(name, `on ${location(current.file, node)}`, error);
+        }
+      }
+    }
+    node.forEachChild(visit);
+  };
+  for (const file of start.files) {
+    const project = snapshot.getProject(file.project);
+    const sourceFile = project.program.getSourceFile(file.fileName);
+    current = { file: { path: file.path, fileName: file.fileName, isTest: file.isTest, sourceFile }, project };
+    visit(sourceFile);
+  }
+  current = undefined;
+  for (const [name, ctx, finish] of finishers) {
+    try {
+      finish(ctx);
+    } catch (error) {
+      throw ruleError(name, "in finish", error);
+    }
+  }
+  return findings;
+}
+
+function ruleError(name, where, error) {
+  return new LintError(`Rule ${name} failed ${where}: ${error?.stack ?? error}`, 1);
+}
+
+function location(file, node) {
+  const { line, character } = file.sourceFile.getLineAndCharacterOfPosition(node.getStart(file.sourceFile));
+  return `${file.path}:${line + 1}:${character + 1}`;
+}

package/lib/testing.d.ts

@@ -0,0 +1,21 @@
+import type { Rule, RuleOptions } from "./index.js";
+
+export interface Finding {
+  /** 1-based. */
+  line: number;
+  /** 1-based, in UTF-16 code units. */
+  column: number;
+  message: string;
+}
+
+/** Runs rule alone on source, as index.ts in a strict TypeScript project. */
+export declare function lint(rule: Rule<any>, source: string, options?: RuleOptions): Finding[];
+/**
+ * Runs rule alone on files (paths to contents), in a strict TypeScript project
+ * unless files has a tsconfig.json.
+ */
+export declare function lint(
+  rule: Rule<any>,
+  files: Record<string, string>,
+  options?: RuleOptions,
+): (Finding & { file: string })[];

package/lib/testing.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findBinary } from "./binary.js";
+import { lint as lintWithRules } from "./runner.js";
+
+const tsconfig = {
+  compilerOptions: {
+    strict: true,
+    target: "ES2022",
+    module: "ESNext",
+    moduleResolution: "Bundler",
+    jsx: "preserve",
+    allowImportingTsExtensions: true,
+    noEmit: true,
+  },
+  include: ["**/*.ts", "**/*.tsx"],
+};
+
+// lint runs rule alone on source (index.ts) or on files (paths to contents,
+// with a default strict tsconfig.json unless one is given) and returns the
+// findings, with the file of each when given files.
+export function lint(rule, source, options) {
+  const files = typeof source === "string" ? { "index.ts": source } : source;
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "slop-police-test-"));
+  try {
+    const config = { projects: ["tsconfig.json"], rules: { [rule.name]: options ? ["error", options] : "error" } };
+    const all = { "tsconfig.json": JSON.stringify(tsconfig), ...files, "slop-police.json": JSON.stringify(config) };
+    for (const [name, content] of Object.entries(all)) {
+      const file = path.join(root, name);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, content);
+    }
+    return lintWithRules(findBinary(), root, [rule]).results.map(({ file, line, column, message }) =>
+      typeof source === "string" ? { line, column, message } : { file, line, column, message },
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}