@jpeakai/prose-gates 0.1.2 → 0.3.0

package/src/language.ts

@@ -0,0 +1,107 @@
+// The language model of a paragraph: its sentences, and each sentence's words
+// with their part-of-speech tags and lemmas. Everything here takes a string and
+// returns plain data. compromise does the work, pinned exactly so a finding
+// never changes under an upgrade: it splits the sentences, tags each word and
+// gives its lemma. A paragraph exposes this as its lazy `language` view, so a
+// rule that never reads it pays nothing.
+
+import nlp from "compromise";
+import { type ConceptMention, type ConceptModel, mentionsIn, NO_CONCEPTS } from "./concepts.ts";
+
+// One word of a sentence. `lemma` is lower case, so "Parsing" reads as "parse".
+// `content` is true for a noun, verb or adjective that is not a pronoun or an
+// auxiliary, and never for the CODE token that stands for inline code.
+export interface LanguageWord {
+  text: string;
+  lemma: string;
+  tags: readonly string[];
+  content: boolean;
+}
+
+// One sentence, as the paragraph's prose holds it, with inline code as CODE.
+// `terms` is the lemmas of its content words. `opener` is CODE when the
+// sentence opens with inline code, else the lemma of a content word it opens
+// with, else null. `refersBack` is true when its first word is a pronoun, a
+// possessive, an adverb or a connective: "It", "Its", "Then", "However".
+// `verbPhrases` is how many verb phrases compromise finds, with an auxiliary
+// counted inside its verb, so "is shared" is one. `concepts` is each place it
+// names a concept of the project's concept file, empty when it has none.
+export interface LanguageSentence {
+  text: string;
+  words: readonly LanguageWord[];
+  terms: ReadonlySet<string>;
+  opener: string | null;
+  refersBack: boolean;
+  verbPhrases: number;
+  concepts: readonly ConceptMention[];
+}
+
+export interface LanguageView {
+  sentences: readonly LanguageSentence[];
+}
+
+const CONTENT = new Set(["Noun", "Verb", "Adjective"]);
+const FUNCTION = new Set(["Pronoun", "Possessive", "Auxiliary", "Copula", "Modal", "Determiner"]);
+const REFERS_BACK = new Set(["Pronoun", "Possessive", "Adverb", "Conjunction"]);
+
+// The shape compromise returns for a term once compute("root") has run.
+interface TaggedTerm {
+  text: string;
+  normal: string;
+  root?: string;
+  tags: string[];
+}
+
+const wordOf = (term: TaggedTerm): LanguageWord => ({
+  text: term.text,
+  lemma: (term.root ?? term.normal).toLowerCase(),
+  tags: term.tags,
+  content: term.text !== "CODE" && term.tags.some((t) => CONTENT.has(t)) && !term.tags.some((t) => FUNCTION.has(t)),
+});
+
+// One tagging pass gives the words and the verb phrases.
+const tag = (sentence: string): { words: LanguageWord[]; verbPhrases: number } => {
+  const doc = nlp(sentence);
+  // A participle between a determiner, adjective or number and a noun
+  // describes the noun, as in "the signed tag", so it is no verb phrase.
+  doc.match("(#Determiner|#Adjective|#Value) [(#PastTense|#Participle)] #Noun", 0).tag("Adjective");
+  doc.compute("root");
+  // compromise's option types omit root, which compute("root") adds.
+  const rows = doc.json({ terms: { normal: true, root: true, tags: true } } as object) as { terms: TaggedTerm[] }[];
+  return { words: rows.flatMap((row) => row.terms).map(wordOf), verbPhrases: doc.verbs().length };
+};
+
+const openerOf = (first: LanguageWord | undefined): string | null => {
+  if (!first) return null;
+  if (first.text === "CODE") return "CODE";
+  return first.content ? first.lemma : null;
+};
+
+// One sentence's words and what they say about cohesion, and the concepts it names.
+const sentenceWith = (text: string, concepts: ConceptModel): LanguageSentence => {
+  const { words, verbPhrases } = tag(text);
+  const first = words[0];
+  return {
+    text,
+    words,
+    terms: new Set(words.filter((w) => w.content).map((w) => w.lemma)),
+    opener: openerOf(first),
+    refersBack: first?.tags.some((t) => REFERS_BACK.has(t)) ?? false,
+    verbPhrases,
+    concepts: mentionsIn(words, concepts),
+  };
+};
+
+// One sentence on its own, with no concepts. It takes one argument, so it is
+// safe to pass to map.
+export const sentenceOf = (text: string): LanguageSentence => sentenceWith(text, NO_CONCEPTS);
+
+// The sentences of a paragraph's prose. compromise keeps abbreviations such
+// as e.g. and Dr., decimals and urls inside the sentence they belong to, and
+// still ends one after a number or before a lower-case word.
+export const sentenceTexts = (prose: string): string[] =>
+  (nlp(prose).sentences().out("array") as string[]).map((s) => s.trim()).filter((s) => s.length > 0);
+
+export const languageOf = (prose: string, concepts: ConceptModel = NO_CONCEPTS): LanguageView => ({
+  sentences: sentenceTexts(prose).map((s) => sentenceWith(s, concepts)),
+});

package/src/model.ts

@@ -9,6 +9,9 @@ import { gfmFromMarkdown } from "mdast-util-gfm";
 import { frontmatter } from "micromark-extension-frontmatter";
 import { gfm } from "micromark-extension-gfm";
 import { visitParents } from "unist-util-visit-parents";
+import { type Document, isMap, isPair, isScalar, isSeq, LineCounter, parseDocument, type Scalar } from "yaml";
+import { type ConceptModel, NO_CONCEPTS } from "./concepts.ts";
+import { type LanguageView, languageOf } from "./language.ts";
 import type { Range } from "./text.ts";
 
 // Fenced blocks in these languages hold markdown templates (a conventions or
@@ -42,6 +45,8 @@ export interface ParagraphView {
   inBlockquote: boolean;
   inListItem: boolean;
   onlyChild: boolean; // the paragraph is its parent's only block
+  // Its sentences, words, tags and lemmas, read from `prose` on first use.
+  readonly language: LanguageView;
 }
 
 export interface TextView {
@@ -59,12 +64,60 @@ export interface FenceView {
   line: number; // line of the opening fence
 }
 
+// One top-level key of the frontmatter whose value is a string.
+export interface FrontmatterEntry {
+  key: string;
+  value: string; // the scalar as text, folded lines joined
+  line: number; // file line where the value starts
+  start: number; // source offsets of the value, quotes included
+  end: number;
+}
+
+// How a YAML string is written, which a fixer needs to rewrite it safely.
+export type ScalarStyle = "plain" | "double" | "single" | "literal" | "folded";
+
+// A string value anywhere in the frontmatter, found by walking the whole YAML
+// document in order. A value in a nested map or a list is here too, with the
+// path that leads to it.
+export interface FrontmatterScalar {
+  path: (string | number)[]; // keys and list indexes from the document root
+  key: string | null; // the nearest map key above it, at any depth
+  keyLine: number | null; // file line of that key
+  value: string; // the string as YAML reads it
+  line: number; // file line where the value starts
+  start: number; // absolute source offsets of the value, quotes included
+  end: number;
+  style: ScalarStyle;
+  indent: number; // leading spaces of the line the key, or the value, sits on
+  node: Scalar; // the yaml package node, for anything this view does not carry
+}
+
+export interface FrontmatterView {
+  format: "yaml";
+  // The top-level string entries, kept for the common flat case.
+  entries: FrontmatterEntry[];
+  // Every string scalar at any depth, in document order.
+  scalars: FrontmatterScalar[];
+  // The whole parsed document, from the yaml package, for full traversal.
+  document: Document.Parsed;
+  // Absolute offset in `src` where the YAML text starts, so a node range from
+  // `document` maps to the source as offset + range.
+  offset: number;
+  // The file line of an absolute source offset inside the block.
+  lineOf: (absoluteOffset: number) => number;
+}
+
 export interface DocModel {
   src: string;
   tree: Root;
   paragraphs: ParagraphView[];
   texts: TextView[]; // every prose text node, including headings and lists
   fences: FenceView[]; // embedded-markdown fences, audited recursively
+  // The project's concepts, which every paragraph's language view names.
+  concepts: ConceptModel;
+  // The leading YAML block as keys and values, read on first use so a document
+  // whose frontmatter is not valid YAML only fails the rules that ask for it.
+  readonly frontmatter: FrontmatterView | null;
 }
 
 export const parse = (src: string): Root =>
@@ -76,78 +129,228 @@ export const parse = (src: string): Root =>
     mdastExtensions: [frontmatterFromMarkdown(["yaml", "toml"]), gfmFromMarkdown()],
   });
 
-export const buildDocModel = (src: string): DocModel => {
-  const tree = parse(src);
-  const paragraphs: ParagraphView[] = [];
-  const texts: TextView[] = [];
-  const fences: FenceView[] = [];
-  const viewOf = new Map<Paragraph, ParagraphView>();
-  const proseParts = new Map<Paragraph, string[]>();
+// The views a single walk of the tree fills in, in document order.
+interface WalkState {
+  src: string;
+  paragraphs: ParagraphView[];
+  texts: TextView[];
+  fences: FenceView[];
+  viewOf: Map<Paragraph, ParagraphView>;
+  proseParts: Map<Paragraph, string[]>;
+  concepts: ConceptModel;
+}
+
+// A markdown-tagged fence is kept as a template to audit; any other code is exempt.
+const visitCode = (state: WalkState, c: Code): void => {
+  if (c.lang != null && MARKDOWN_FENCE_LANGS.has(c.lang) && c.position) {
+    state.fences.push({ value: c.value, line: c.position.start.line });
+  }
+};
+
+// A paragraph opens a view that its descendants fill in as the walk reaches them.
+const visitParagraph = (state: WalkState, p: Paragraph, ancestors: Node[]): void => {
+  const pos = p.position;
+  if (!pos || pos.start.offset == null || pos.end.offset == null) return;
+  const parent = ancestors.at(-1) as Parent | undefined;
+  const view: ParagraphView = {
+    node: p,
+    raw: state.src.slice(pos.start.offset, pos.end.offset),
+    line: pos.start.line,
+    startOffset: pos.start.offset,
+    endOffset: pos.end.offset,
+    startColumn: pos.start.column,
+    prose: "",
+    codeRanges: [],
+    directTexts: [],
+    hasBreak: false,
+    inTable: ancestors.some((a) => a.type === "table" || a.type === "tableCell"),
+    inBlockquote: ancestors.some((a) => a.type === "blockquote"),
+    inListItem: ancestors.some((a) => a.type === "listItem"),
+    onlyChild: parent !== undefined && parent.children.length === 1,
+    // Tagging is the slowest step in a check, so it waits for the first read.
+    // By then the walk has joined the prose, which it is built from.
+    get language() {
+      language ??= languageOf(view.prose, state.concepts);
+      return language;
+    },
+  };
+  let language: LanguageView | undefined;
+  state.paragraphs.push(view);
+  state.viewOf.set(p, view);
+  state.proseParts.set(p, []);
+};
+
+// Every text node is prose; one directly under its paragraph is also a split point.
+const visitText = (state: WalkState, t: Text, ancestors: Node[], paragraph: Paragraph | undefined): void => {
+  const start = t.position?.start.offset;
+  const end = t.position?.end.offset;
+  state.texts.push({
+    value: t.value,
+    line: t.position?.start.line ?? 0,
+    start,
+    end,
+    block: ancestors.findLast((a) => a.type === "paragraph" || a.type === "heading" || a.type === "tableCell"),
+  });
+  if (!paragraph) return;
+  state.proseParts.get(paragraph)?.push(t.value);
+  const view = state.viewOf.get(paragraph);
+  if (view && ancestors.at(-1) === paragraph && start != null && end != null) {
+    view.directTexts.push({ value: t.value, start, end });
+  }
+};
+
+// Inline code reads as one CODE token in the prose, and its range is exempt.
+const visitInlineCode = (state: WalkState, c: InlineCode, paragraph: Paragraph, view: ParagraphView): void => {
+  state.proseParts.get(paragraph)?.push("CODE");
+  if (c.position?.start.offset != null && c.position.end.offset != null) {
+    view.codeRanges.push([c.position.start.offset, c.position.end.offset]);
+  }
+};
+
+// Route one node of the walk to the view it feeds.
+const visitNode = (state: WalkState, node: Node, ancestors: Node[]): void => {
+  if (node.type === "code") {
+    visitCode(state, node as Code);
+    return;
+  }
+  if (node.type === "paragraph") {
+    visitParagraph(state, node as Paragraph, ancestors);
+    return;
+  }
+  const paragraph = ancestors.findLast((a): a is Paragraph => a.type === "paragraph");
+  if (node.type === "text") {
+    visitText(state, node as Text, ancestors, paragraph);
+    return;
+  }
+  const view = paragraph ? state.viewOf.get(paragraph) : undefined;
+  if (!(paragraph && view)) return;
+  if (node.type === "inlineCode") visitInlineCode(state, node as InlineCode, paragraph, view);
+  else if (node.type === "break") view.hasBreak = true;
+};
 
+export const buildDocModel = (src: string, concepts: ConceptModel = NO_CONCEPTS): DocModel => {
+  const tree = parse(src);
+  const state: WalkState = {
+    src,
+    paragraphs: [],
+    texts: [],
+    fences: [],
+    viewOf: new Map(),
+    proseParts: new Map(),
+    concepts,
+  };
   visitParents(tree, (node: Node, ancestors: Node[]) => {
-    if (node.type === "code") {
-      const c = node as Code;
-      if (c.lang != null && MARKDOWN_FENCE_LANGS.has(c.lang) && c.position) {
-        fences.push({ value: c.value, line: c.position.start.line });
-      }
-      return;
-    }
-    const parent = ancestors.at(-1) as Parent | undefined;
-    if (node.type === "paragraph") {
-      const p = node as Paragraph;
-      const pos = p.position;
-      if (!pos || pos.start.offset == null || pos.end.offset == null) return;
-      const view: ParagraphView = {
-        node: p,
-        raw: src.slice(pos.start.offset, pos.end.offset),
-        line: pos.start.line,
-        startOffset: pos.start.offset,
-        endOffset: pos.end.offset,
-        startColumn: pos.start.column,
-        prose: "",
-        codeRanges: [],
-        directTexts: [],
-        hasBreak: false,
-        inTable: ancestors.some((a) => a.type === "table" || a.type === "tableCell"),
-        inBlockquote: ancestors.some((a) => a.type === "blockquote"),
-        inListItem: ancestors.some((a) => a.type === "listItem"),
-        onlyChild: parent !== undefined && parent.children.length === 1,
-      };
-      paragraphs.push(view);
-      viewOf.set(p, view);
-      proseParts.set(p, []);
-    }
-    const paragraph = ancestors.findLast((a): a is Paragraph => a.type === "paragraph");
-    const view = paragraph ? viewOf.get(paragraph) : undefined;
-    if (node.type === "text") {
-      const t = node as Text;
-      const start = t.position?.start.offset;
-      const end = t.position?.end.offset;
-      texts.push({
-        value: t.value,
-        line: t.position?.start.line ?? 0,
-        start,
-        end,
-        block: ancestors.findLast((a) => a.type === "paragraph" || a.type === "heading" || a.type === "tableCell"),
-      });
-      if (paragraph) proseParts.get(paragraph)?.push(t.value);
-      if (view && parent === paragraph && start != null && end != null) {
-        view.directTexts.push({ value: t.value, start, end });
-      }
-    } else if (node.type === "inlineCode" && view) {
-      const c = node as InlineCode;
-      proseParts.get(paragraph as Paragraph)?.push("CODE");
-      if (c.position?.start.offset != null && c.position.end.offset != null) {
-        view.codeRanges.push([c.position.start.offset, c.position.end.offset]);
-      }
-    } else if (node.type === "break" && view) {
-      view.hasBreak = true;
-    }
+    visitNode(state, node, ancestors);
   });
 
-  for (const [p, parts] of proseParts) {
-    const view = viewOf.get(p);
+  for (const [p, parts] of state.proseParts) {
+    const view = state.viewOf.get(p);
     if (view) view.prose = parts.join(" ").replace(/\s+/g, " ").trim();
   }
-  return { src, tree, paragraphs, texts, fences };
+  let frontmatter: FrontmatterView | null | undefined;
+  return {
+    src,
+    tree,
+    paragraphs: state.paragraphs,
+    texts: state.texts,
+    fences: state.fences,
+    concepts,
+    get frontmatter() {
+      frontmatter ??= readFrontmatter(src, tree);
+      return frontmatter;
+    },
+  };
+};
+
+const STYLES: Record<string, ScalarStyle> = {
+  PLAIN: "plain",
+  QUOTE_DOUBLE: "double",
+  QUOTE_SINGLE: "single",
+  BLOCK_LITERAL: "literal",
+  BLOCK_FOLDED: "folded",
+};
+
+// What the walk of a YAML document needs to place each scalar in the source,
+// and the list it fills in document order.
+interface ScalarWalk {
+  contentStart: number; // absolute offset where the YAML text starts
+  lineOf: (absoluteOffset: number) => number;
+  indentOf: (relativeOffset: number) => number;
+  scalars: FrontmatterScalar[];
+}
+
+// A string scalar with a range is recorded; anything else is left out.
+const visitScalar = (walk: ScalarWalk, value: Scalar, path: (string | number)[], key: Scalar | null): void => {
+  if (typeof value.value !== "string" || !value.range) return;
+  const { contentStart, lineOf } = walk;
+  const [from, to] = value.range;
+  const anchor = key?.range ? key.range[0] : from;
+  walk.scalars.push({
+    path,
+    key: key && typeof key.value === "string" ? key.value : null,
+    keyLine: key?.range ? lineOf(contentStart + key.range[0]) : null,
+    value: value.value,
+    line: lineOf(contentStart + from),
+    start: contentStart + from,
+    end: contentStart + to,
+    style: STYLES[value.type ?? "PLAIN"] ?? "plain",
+    indent: walk.indentOf(anchor),
+    node: value,
+  });
+};
+
+// Descend into a YAML node in order: a map by key, a list by index, keeping the
+// nearest map key above each scalar.
+const walkYaml = (walk: ScalarWalk, value: unknown, path: (string | number)[], key: Scalar | null): void => {
+  if (isScalar(value)) {
+    visitScalar(walk, value, path, key);
+    return;
+  }
+  if (isMap(value)) {
+    for (const pair of value.items) {
+      if (!isPair(pair)) continue;
+      const k = isScalar(pair.key) ? pair.key : null;
+      walkYaml(walk, pair.value, [...path, k ? String(k.value) : ""], k);
+    }
+    return;
+  }
+  if (isSeq(value)) {
+    value.items.forEach((item, i) => {
+      walkYaml(walk, item, [...path, i], key);
+    });
+  }
+};
+
+// A leading YAML block as a whole document, plus the string scalars found by
+// walking all of it. Only the first node of the tree can be frontmatter, and
+// TOML is not read. A value that is not a string is left out of `scalars`
+// rather than guessed at, and an alias is not followed. Invalid YAML throws with
+// the line, so a rule that needs the keys cannot run on a block it could not read.
+const readFrontmatter = (src: string, tree: Root): FrontmatterView | null => {
+  const node = tree.children[0];
+  const offset = node?.position?.start.offset;
+  if (node?.type !== "yaml" || offset == null || !node.position) return null;
+  const opening = node.position.start;
+  const contentStart = offset + src.slice(offset).indexOf("\n") + 1;
+  const lines = new LineCounter();
+  const doc = parseDocument(node.value, { lineCounter: lines });
+  const [problem] = doc.errors;
+  if (problem) {
+    const line = opening.line + (problem.linePos?.[0].line ?? 1);
+    throw new Error(`frontmatter YAML error at line ${line}: ${problem.message.split("\n")[0]}`);
+  }
+  const lineOf = (absolute: number): number => opening.line + lines.linePos(absolute - contentStart).line;
+  const indentOf = (relative: number): number => {
+    const lineStart = node.value.lastIndexOf("\n", relative - 1) + 1;
+    return /^ */.exec(node.value.slice(lineStart))?.[0].length ?? 0;
+  };
+
+  const walk: ScalarWalk = { contentStart, lineOf, indentOf, scalars: [] };
+  walkYaml(walk, doc.contents, [], null);
+  const { scalars } = walk;
+
+  const entries: FrontmatterEntry[] = scalars
+    .filter((s) => s.path.length === 1 && typeof s.path[0] === "string")
+    .map((s) => ({ key: s.path[0] as string, value: s.value, line: s.line, start: s.start, end: s.end }));
+  return { format: "yaml", entries, scalars, document: doc, offset: contentStart, lineOf };
 };

package/src/plugins/contract.ts

@@ -0,0 +1,41 @@
+// What a plugin is: an ES module whose default export is a Plugin, or, for a
+// local rule, one PluginRule per file. The context a plugin rule receives is
+// the one the built-ins read, so a plugin rule is a built-in with a namespace.
+
+import type { Awaitable, CheckContext, Edit, Finding, FixContext, OptionSpec } from "../rules/types.ts";
+
+// Bumped when the contract changes in a way a plugin must notice. A plugin
+// that targets another version fails to load with both numbers in the message.
+export const API_VERSION = 1;
+
+// What a plugin returns. The engine adds the rule id and the file to a finding,
+// and the rule id to an edit, so a plugin cannot report as another rule.
+export type PluginFinding = Pick<Finding, "line" | "message">;
+
+export type PluginEdit = Omit<Edit, "rule">;
+
+export interface PluginRule {
+  category: string;
+  summary: string;
+  options?: OptionSpec;
+  check: (ctx: CheckContext) => Awaitable<PluginFinding[]>;
+  fix?: (ctx: FixContext) => Awaitable<PluginEdit[]>;
+}
+
+export interface PluginMeta {
+  name: string;
+  namespace: string;
+  apiVersion: number;
+  // A new category the plugin adds, as the word and a one-line description.
+  categories?: Record<string, string>;
+}
+
+export interface Plugin {
+  meta: PluginMeta;
+  rules: Record<string, PluginRule>;
+}
+
+// A one-word category and a namespace or rule key, as they appear in an id.
+export const CATEGORY_WORD = /^[a-z]+$/;
+export const NAMESPACE = /^[a-z][a-z0-9-]*$/;
+export const RULE_KEY = /^[a-z][a-z0-9-]*$/;

package/src/plugins/discover.ts

@@ -0,0 +1,146 @@
+// Discovery: which plugin sources a project has. Three places, in this order:
+// local rule files in .prose-gates/rules, packages the project declares as
+// dependencies and whose name matches the plugin pattern, and the paths or
+// names a config lists. A directory of node_modules is never scanned, so only
+// what the project chose to depend on can run.
+//
+// A source that cannot be resolved is a failure the caller decides how to
+// treat, not an exception, so a lenient run can skip it and a validating run
+// can report every one.
+
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, resolve } from "node:path";
+import type { Config } from "../config.ts";
+import { PluginNotInstalledError } from "../errors.ts";
+
+export type SourceKind = "local" | "package" | "config";
+
+export interface PluginSource {
+  kind: SourceKind;
+  // What the user would recognise: a package name or a path under the root.
+  spec: string;
+  // The file to import.
+  path: string;
+}
+
+export interface Discovery {
+  sources: PluginSource[];
+  // Sources found but not resolvable, such as a declared package that is not installed.
+  failures: PluginNotInstalledError[];
+}
+
+export const LOCAL_RULES = join(".prose-gates", "rules");
+
+// prose-gates-plugin-acme, @acme/prose-gates-plugin-acme or @acme/prose-gates-plugin.
+export const PACKAGE_PATTERN = /^(@[a-z0-9][a-z0-9._-]*\/)?prose-gates-plugin(-[a-z0-9-]+)?$/;
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+const readJson = async (path: string): Promise<Record<string, unknown> | null> => {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const value: unknown = JSON.parse(text);
+    if (isRecord(value)) return value;
+  } catch {
+    // Reported below with the path.
+  }
+  throw new Error(`${path} is not a JSON object`);
+};
+
+// Every extension a local rule may have. Whether the runtime can import a
+// TypeScript one is decided at load, so the reason is a named error.
+const LOCAL_EXTENSIONS = new Set([".js", ".mjs", ".ts", ".mts", ".cts"]);
+
+const localSources = async (root: string): Promise<PluginSource[]> => {
+  const dir = join(root, LOCAL_RULES);
+  let names: string[];
+  try {
+    names = (await readdir(dir)).sort();
+  } catch {
+    return [];
+  }
+  return names
+    .filter((name) => LOCAL_EXTENSIONS.has(extname(name)) && !name.endsWith(".d.ts") && !name.endsWith(".d.mts"))
+    .map((name) => ({ kind: "local", spec: join(LOCAL_RULES, name), path: join(dir, name) }));
+};
+
+// The file Node would import for a package, read from its package.json the
+// way a resolver does: the exports entry, then main, then index.js.
+const pick = (target: unknown): string | null => {
+  if (typeof target === "string") return target;
+  if (Array.isArray(target)) return pickFirst(target);
+  if (isRecord(target)) return pickCondition(target);
+  return null;
+};
+
+// A fallback array: the first entry that names a file.
+const pickFirst = (items: unknown[]): string | null => {
+  for (const item of items) {
+    const found = pick(item);
+    if (found) return found;
+  }
+  return null;
+};
+
+// A conditions object: the first condition Node would match that names a file.
+const pickCondition = (target: Record<string, unknown>): string | null => {
+  for (const condition of ["node", "import", "default"]) {
+    if (!(condition in target)) continue;
+    const found = pick(target[condition]);
+    if (found) return found;
+  }
+  return null;
+};
+
+const entryOf = (pkg: Record<string, unknown>): string => {
+  const exported = pkg.exports;
+  const hasMap = isRecord(exported) && Object.keys(exported).some((k) => k.startsWith("."));
+  const main = isRecord(exported) && "." in exported ? exported["."] : hasMap ? null : exported;
+  return pick(main) ?? (typeof pkg.main === "string" ? pkg.main : "index.js");
+};
+
+export const resolvePackage = async (root: string, name: string): Promise<string> => {
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    const folder = join(dir, "node_modules", name);
+    const pkg = await readJson(join(folder, "package.json"));
+    if (pkg) return join(folder, entryOf(pkg));
+    if (dirname(dir) === dir) break;
+  }
+  throw new PluginNotInstalledError(name, root);
+};
+
+const declaredPlugins = async (root: string): Promise<string[]> => {
+  const pkg = await readJson(join(root, "package.json"));
+  if (!pkg) return [];
+  const names = ["dependencies", "devDependencies", "optionalDependencies"].flatMap((field) => {
+    const deps = pkg[field];
+    return isRecord(deps) ? Object.keys(deps) : [];
+  });
+  return [...new Set(names)].filter((name) => PACKAGE_PATTERN.test(name)).sort();
+};
+
+export const discoverSources = async (root: string, config: Config): Promise<Discovery> => {
+  const sources = await localSources(root);
+  const failures: PluginNotInstalledError[] = [];
+  const add = async (kind: SourceKind, spec: string, resolveIt: () => Promise<string>): Promise<void> => {
+    try {
+      sources.push({ kind, spec, path: await resolveIt() });
+    } catch (err) {
+      if (!(err instanceof PluginNotInstalledError)) throw err;
+      failures.push(err);
+    }
+  };
+  for (const name of await declaredPlugins(root)) await add("package", name, () => resolvePackage(root, name));
+  for (const spec of config.plugins || []) {
+    const path = spec.startsWith(".") || isAbsolute(spec);
+    await add("config", spec, () => (path ? Promise.resolve(resolve(root, spec)) : resolvePackage(root, spec)));
+  }
+  // A package both declared and listed in the config loads once.
+  const seen = new Set<string>();
+  return { sources: sources.filter((s) => !seen.has(s.path) && seen.add(s.path)), failures };
+};