@mark1russell7/ste-lint 0.0.0-stage → 0.1.2

package/src/config.ts

@@ -0,0 +1,83 @@
+/**
+ * The configuration file `ste.config.json`, and the configuration that the
+ * linter uses after it reads the file, the environment and the defaults.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { baseConfig, CONFIG_FILE_NAME, ConfigError, DICTIONARY_ENV, validateConfig, type ResolvedConfig, type SteConfigFile } from "./config-core.js";
+
+export * from "./config-core.js";
+
+/** This function expands a leading `~/` to the home directory, and makes the path absolute. */
+export function resolvePath(path : string, base : string) : string {
+    const expanded = path === "~" ? homedir() : path.startsWith("~/") || path.startsWith("~\\") ? join(homedir(), path.slice(2)) : path;
+    return resolve(base, expanded);
+}
+
+export type ResolveOptions = {
+    /** The directory of the configuration file, or the working directory. */
+    readonly root : string;
+    readonly configFile? : string | null;
+    /** The working directory. `STE_DICTIONARY` is relative to it. */
+    readonly cwd? : string;
+    readonly env? : Readonly<Record<string, string | undefined>>;
+};
+
+/** This function applies the defaults and the environment to a configuration file. */
+export function resolveConfig(file : SteConfigFile, options : ResolveOptions) : ResolvedConfig {
+    const env = options.env ?? {};
+    const cwd = options.cwd ?? options.root;
+    const fromEnv = env[DICTIONARY_ENV];
+    let dictionaryPath : string | null = null;
+    let dictionarySource : ResolvedConfig["dictionarySource"] = null;
+    if (fromEnv !== undefined && fromEnv.trim().length > 0) {
+        dictionaryPath = resolvePath(fromEnv.trim(), cwd);
+        dictionarySource = "env";
+    } else if (typeof file.dictionaryPath === "string" && file.dictionaryPath.trim().length > 0) {
+        dictionaryPath = resolvePath(file.dictionaryPath.trim(), options.root);
+        dictionarySource = "config";
+    }
+    return { ...baseConfig(file, { root : options.root, configFile : options.configFile ?? null }), dictionaryPath, dictionarySource };
+}
+
+/** The first `ste.config.json` in `cwd` or one of its parent directories, or null. */
+export function findConfigFile(cwd : string) : string | null {
+    let directory = resolve(cwd);
+    for (;;) {
+        const candidate = join(directory, CONFIG_FILE_NAME);
+        if (existsSync(candidate)) return candidate;
+        const parent = dirname(directory);
+        if (parent === directory) return null;
+        directory = parent;
+    }
+}
+
+export type LoadOptions = {
+    readonly cwd : string;
+    /** An explicit configuration file. Without it, the linter looks for `ste.config.json`. */
+    readonly configPath? : string;
+    readonly env? : Readonly<Record<string, string | undefined>>;
+};
+
+/** This function reads the configuration file, if there is one, and resolves it. */
+export function loadConfig(options : LoadOptions) : ResolvedConfig {
+    const configFile = options.configPath !== undefined ? resolve(options.cwd, options.configPath) : findConfigFile(options.cwd);
+    const env = options.env ?? {};
+    if (configFile === null) return resolveConfig({}, { root : resolve(options.cwd), cwd : options.cwd, env });
+    let text : string;
+    try {
+        text = readFileSync(configFile, "utf8");
+    } catch (error) {
+        throw new ConfigError(`Cannot read the configuration file ${configFile}: ${(error as Error).message}`);
+    }
+    let value : unknown;
+    try {
+        value = JSON.parse(text);
+    } catch (error) {
+        throw new ConfigError(`${configFile}: the file is not valid JSON: ${(error as Error).message}`);
+    }
+    const file = validateConfig(value, configFile);
+    return resolveConfig(file, { root : dirname(configFile), configFile, cwd : options.cwd, env });
+}

package/src/core.test.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import * as core from "./core.js";
+import { extractCode } from "./source/code.js";
+import { Linter, resolveConfig } from "./index.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** The relative imports and the package imports of each module that `entry` reaches. */
+function importGraph(entry : string) : { modules : string[]; packages : string[] } {
+    const seen = new Set<string>();
+    const packages = new Set<string>();
+    const visit = (file : string) : void => {
+        if (seen.has(file)) return;
+        seen.add(file);
+        const text = readFileSync(file, "utf8");
+        // Type-only imports are erased, so they do not count.
+        for (const match of text.matchAll(/^(?:import|export)\s+(?!type\b)[^;]*?from\s+"([^"]+)"/gms)) {
+            const specifier = match[1]!;
+            if (specifier.startsWith(".")) visit(join(dirname(file), specifier.replace(/\.js$/, ".ts")));
+            else packages.add(specifier);
+        }
+    };
+    visit(join(here, entry));
+    return { modules : [...seen], packages : [...packages] };
+}
+
+const FIXTURE = [
+    "# Getting started",
+    "",
+    "You should utilize the CLI in order to check the docs; it is basically simple.",
+    "The values are about 5 ms, e.g. in the test run.",
+    "",
+    "Please make sure that the file is deleted. Stop the tool by closing the tab.",
+    "",
+    "- The user can edit his settings via the menu.",
+    "",
+    "<!-- ste-disable-next modal-verb -->",
+    "You should not see this modal verb.",
+    "",
+].join("\n");
+
+describe("the core entry", () => {
+    it("imports no Node module and not the TypeScript compiler", () => {
+        const { packages, modules } = importGraph("core.ts");
+        expect(packages).toEqual([]);
+        expect(modules.length).toBeGreaterThan(20);
+    });
+
+    it("lets the code extractor import the compiler, but no Node module", () => {
+        expect(importGraph("source/code.ts").packages).toEqual(["typescript"]);
+    });
+
+    it("gives the same Markdown findings as the linter of the command line", () => {
+        const config = resolveConfig({}, { root : "/" });
+        const cli = new Linter(config).lintText(FIXTURE, "README.md");
+        const browser = new core.ProseLinter(core.baseConfig()).lintText(FIXTURE, "README.md");
+        expect(browser).toEqual(cli);
+        expect(new Set(cli.map((finding) => finding.ruleId))).toEqual(new Set([
+            "modal-verb", "semicolon", "word-list", "about-quantity", "latin-abbreviation", "gendered-pronoun", "ing-verb",
+        ]));
+    });
+
+    it("gives the same doc comment findings with the code extractor", () => {
+        const source = "/** Returns the value. You should utilize it. */\nexport const x = 1;\n";
+        const cli = new Linter(resolveConfig({}, { root : "/" })).lintText(source, "a.ts");
+        const browser = new core.ProseLinter(core.baseConfig(), undefined, { extractCode }).lintText(source, "a.ts");
+        expect(browser).toEqual(cli);
+        expect(cli.map((finding) => finding.ruleId)).toContain("missing-subject");
+        expect(new core.ProseLinter(core.baseConfig()).lintText(source, "a.ts")).toEqual([]);
+    });
+
+    it("applies the settings of a configuration file and a dictionary", () => {
+        const config = core.baseConfig({ rules : { "modal-verb" : "off" } });
+        expect(new core.ProseLinter(config).lintText("You should stop.", "a.md")).toEqual([]);
+        const dictionary = core.parseDictionary(["you", "stop", "the"], "words.json");
+        const linter = new core.ProseLinter(core.baseConfig(), core.buildLexicon(core.baseConfig(), dictionary));
+        expect(linter.lintText("You stop the valve.", "a.md").map((finding) => finding.ruleId)).toEqual(["unknown-word"]);
+    });
+
+    it("gives the same configuration as resolveConfig without a dictionary", () => {
+        const file = { technicalNouns : ["valve"], limits : { instructionWords : 12 } };
+        expect(core.baseConfig(file, { root : "/" })).toEqual(resolveConfig(file, { root : "/" }));
+    });
+});

package/src/core.ts

@@ -0,0 +1,32 @@
+/**
+ * `@mark1russell7/ste-lint/core`: the linter without a file system, for a
+ * browser or another host that has the text in memory. It examines Markdown
+ * and MDX. For TypeScript doc comments, give the extractor of
+ * `@mark1russell7/ste-lint/code` to `ProseLinter`. The rules are the same
+ * rules that the command line uses.
+ */
+
+export {
+    baseConfig,
+    CONFIG_FILE_NAME,
+    ConfigError,
+    DEFAULT_IGNORE,
+    DEFAULT_INCLUDE,
+    DEFAULT_LIMITS,
+    DICTIONARY_ENV,
+    mergeWordList,
+    validateConfig,
+    type BaseConfigOptions,
+    type Limits,
+    type LimitsConfig,
+    type ResolvedConfig,
+    type SteConfigFile,
+    type WordListEntryConfig,
+} from "./config-core.js";
+export { Dictionary, DICTIONARY_FORMAT, DictionaryError, parseDictionary, type DictionaryEntry, type DictionaryLookup } from "./dictionary-core.js";
+export { fileKind, ProseLinter, type CodeExtractor, type FileKind, type ProseLinterOptions } from "./engine.js";
+export { formatJson, formatText, summarize, type RuleCount, type Summary } from "./format.js";
+export { buildLexicon, type Lexicon } from "./lexicon.js";
+export { getRule, RULES, type Rule } from "./rules/index.js";
+export { isRuleId, RULE_IDS, type Finding, type RuleId, type RuleSetting, type Severity } from "./types.js";
+export { DEFAULT_WORD_LIST, type WordListEntry } from "./word-list.js";

package/src/dictionary-core.ts

@@ -0,0 +1,158 @@
+/**
+ * The optional local dictionary of approved words.
+ *
+ * The ASD-STE100 dictionary is copyrighted. This package does not contain
+ * it, and the repository must not contain it. Each user makes a local file
+ * from their own copy of the standard. Keep that file outside the
+ * repository, or in a git-ignored folder, for example `.ste/`.
+ *
+ * File format (JSON). The short form is an array of approved words:
+ *
+ * ```json
+ * ["a", "about", "make", "makes", "made"]
+ * ```
+ *
+ * The full form is an object with entries:
+ *
+ * ```json
+ * {
+ *   "format": "ste-lint-dictionary",
+ *   "version": 1,
+ *   "entries": [
+ *     { "word": "make", "pos": "verb", "forms": ["makes", "made"] },
+ *     { "word": "valve", "pos": "noun" },
+ *     { "word": "utilize", "pos": "verb", "approved": false, "alternatives": ["use"] }
+ *   ]
+ * }
+ * ```
+ *
+ * - `word` (necessary): the headword. A phrase, for example "make sure", approves each of its words.
+ * - `pos`: the part of speech. A noun also permits its regular plural.
+ * - `approved`: `false` for a word that is not approved. The default is `true`.
+ * - `forms`: other approved forms, for example the past tense of a verb.
+ * - `alternatives`: approved words to use instead of a word that is not approved.
+ */
+
+export type DictionaryEntry = {
+    readonly word : string;
+    readonly pos? : string;
+    readonly approved? : boolean;
+    readonly forms? : readonly string[];
+    readonly alternatives? : readonly string[];
+};
+
+export type DictionaryLookup =
+    | { readonly status : "approved" }
+    | { readonly status : "not-approved"; readonly alternatives : readonly string[] }
+    | { readonly status : "unknown" };
+
+export const DICTIONARY_FORMAT = "ste-lint-dictionary";
+
+/** An error in a dictionary file. */
+export class DictionaryError extends Error {
+    override readonly name : string = "DictionaryError";
+}
+
+const normalize = (word : string) : string => word.trim().toLowerCase().replace(/[’‘]/g, "'");
+
+/** The approved words of a local dictionary. */
+export class Dictionary {
+    private readonly approved = new Set<string>();
+    private readonly approvedNouns = new Set<string>();
+    private readonly notApproved = new Map<string, readonly string[]>();
+    /** The approved nouns. The noun-cluster rule uses them. */
+    readonly nouns : Set<string> = new Set<string>();
+    /** The approved verbs. The imperative and missing-subject heuristics use them. */
+    readonly verbs : Set<string> = new Set<string>();
+
+    constructor(entries : readonly DictionaryEntry[]) {
+        for (const entry of entries) {
+            const words = [entry.word, ...(entry.forms ?? [])].flatMap((form) => normalize(form).split(/\s+/)).filter((form) => form.length > 0);
+            if (entry.approved === false) {
+                for (const word of words) this.notApproved.set(word, entry.alternatives ?? []);
+                continue;
+            }
+            for (const word of words) this.approved.add(word);
+            const pos = (entry.pos ?? "").toLowerCase();
+            const base = normalize(entry.word);
+            if (pos === "n" || pos === "noun") {
+                this.approvedNouns.add(base);
+                this.nouns.add(base);
+            }
+            if (pos === "v" || pos === "verb") this.verbs.add(base);
+        }
+    }
+
+    /** The number of approved words and forms. */
+    get size() : number {
+        return this.approved.size;
+    }
+
+    /** The status of `word` in the dictionary. */
+    lookup(word : string) : DictionaryLookup {
+        const lower = normalize(word);
+        const candidates = [lower];
+        if (lower.endsWith("'s")) candidates.push(lower.slice(0, -2));
+        for (const candidate of candidates) {
+            if (this.approved.has(candidate)) return { status : "approved" };
+            const plurals = [candidate.slice(0, -1), candidate.slice(0, -2), candidate.slice(0, -3) + "y"];
+            if (candidate.endsWith("s") && plurals.some((singular) => this.approvedNouns.has(singular))) return { status : "approved" };
+        }
+        for (const candidate of candidates) {
+            const alternatives = this.notApproved.get(candidate);
+            if (alternatives !== undefined) return { status : "not-approved", alternatives };
+        }
+        return { status : "unknown" };
+    }
+}
+
+/** This function makes a dictionary from parsed JSON. `source` is the file name for error messages. */
+export function parseDictionary(value : unknown, source : string) : Dictionary {
+    if (Array.isArray(value)) {
+        if (!value.every((word) => typeof word === "string")) {
+            throw new DictionaryError(`${source}: the array form must contain only strings.`);
+        }
+        return new Dictionary(value.map((word : string) => ({ word })));
+    }
+    if (typeof value !== "object" || value === null) {
+        throw new DictionaryError(`${source}: the file must contain an array of words or an object with "entries".`);
+    }
+    const record = value as Record<string, unknown>;
+    const format = record["format"];
+    if (format !== undefined && format !== DICTIONARY_FORMAT) {
+        throw new DictionaryError(`${source}: "format" must be "${DICTIONARY_FORMAT}".`);
+    }
+    const entries = record["entries"];
+    if (!Array.isArray(entries)) throw new DictionaryError(`${source}: "entries" must be an array.`);
+    const parsed : DictionaryEntry[] = entries.map((entry : unknown, index : number) => parseEntry(entry, `${source}: entries[${index}]`));
+    return new Dictionary(parsed);
+}
+
+function stringArray(value : unknown, where : string) : string[] | undefined {
+    if (value === undefined) return undefined;
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new DictionaryError(`${where} must be an array of strings.`);
+    }
+    return value as string[];
+}
+
+function parseEntry(entry : unknown, where : string) : DictionaryEntry {
+    if (typeof entry === "string") return { word : entry };
+    if (typeof entry !== "object" || entry === null) throw new DictionaryError(`${where} must be a string or an object.`);
+    const record = entry as Record<string, unknown>;
+    const word = record["word"];
+    if (typeof word !== "string" || word.trim().length === 0) throw new DictionaryError(`${where}.word must be a string that is not empty.`);
+    const pos = record["pos"];
+    if (pos !== undefined && typeof pos !== "string") throw new DictionaryError(`${where}.pos must be a string.`);
+    const approved = record["approved"];
+    if (approved !== undefined && typeof approved !== "boolean") throw new DictionaryError(`${where}.approved must be true or false.`);
+    const forms = stringArray(record["forms"], `${where}.forms`);
+    const alternatives = stringArray(record["alternatives"], `${where}.alternatives`);
+    return {
+        word,
+        ...(pos === undefined ? {} : { pos }),
+        ...(approved === undefined ? {} : { approved }),
+        ...(forms === undefined ? {} : { forms }),
+        ...(alternatives === undefined ? {} : { alternatives }),
+    };
+}

package/src/dictionary.test.ts

@@ -0,0 +1,82 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Dictionary, DictionaryError, loadDictionary, parseDictionary } from "./dictionary.js";
+
+let directory : string;
+
+beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), "ste-dictionary-"));
+});
+
+afterEach(() => {
+    rmSync(directory, { recursive : true, force : true });
+});
+
+describe("parseDictionary", () => {
+    it("reads the short form: an array of approved words", () => {
+        const dictionary = parseDictionary(["Make", "makes", "valve"], "d.json");
+        expect(dictionary.size).toBe(3);
+        expect(dictionary.lookup("make").status).toBe("approved");
+        expect(dictionary.lookup("MAKES").status).toBe("approved");
+        expect(dictionary.lookup("made").status).toBe("unknown");
+    });
+
+    it("reads the full form with parts of speech, forms and words that are not approved", () => {
+        const dictionary = parseDictionary({
+            format : "ste-lint-dictionary",
+            version : 1,
+            entries : [
+                "a",
+                { word : "make", pos : "verb", forms : ["makes", "made"] },
+                { word : "make sure", pos : "verb" },
+                { word : "valve", pos : "noun" },
+                { word : "battery", pos : "n" },
+                { word : "utilize", pos : "v", approved : false, alternatives : ["use"] },
+                { word : "frob", approved : false },
+            ],
+        }, "d.json");
+        expect(dictionary.lookup("made").status).toBe("approved");
+        expect(dictionary.lookup("sure").status).toBe("approved");
+        expect(dictionary.lookup("valves").status).toBe("approved");
+        expect(dictionary.lookup("batteries").status).toBe("approved");
+        expect(dictionary.lookup("valve's").status).toBe("approved");
+        expect(dictionary.lookup("makings").status).toBe("unknown");
+        expect(dictionary.lookup("Utilize")).toEqual({ status : "not-approved", alternatives : ["use"] });
+        expect(dictionary.lookup("frob")).toEqual({ status : "not-approved", alternatives : [] });
+        expect([...dictionary.nouns].sort()).toEqual(["battery", "valve"]);
+        expect([...dictionary.verbs].sort()).toEqual(["make", "make sure"]);
+    });
+
+    it("gives clear errors for a file that is not valid", () => {
+        expect(() => parseDictionary(["a", 1], "d.json")).toThrow("only strings");
+        expect(() => parseDictionary(3, "d.json")).toThrow(DictionaryError);
+        expect(() => parseDictionary({ format : "other", entries : [] }, "d.json")).toThrow("\"format\" must be");
+        expect(() => parseDictionary({ entries : {} }, "d.json")).toThrow("\"entries\" must be an array");
+        expect(() => parseDictionary({ entries : [5] }, "d.json")).toThrow("entries[0] must be a string or an object");
+        expect(() => parseDictionary({ entries : [{ word : "" }] }, "d.json")).toThrow("word must be a string");
+        expect(() => parseDictionary({ entries : [{ word : "a", pos : 1 }] }, "d.json")).toThrow("pos must be a string");
+        expect(() => parseDictionary({ entries : [{ word : "a", approved : "no" }] }, "d.json")).toThrow("approved must be true or false");
+        expect(() => parseDictionary({ entries : [{ word : "a", forms : "b" }] }, "d.json")).toThrow("forms must be an array of strings");
+    });
+
+    it("makes an empty dictionary", () => {
+        expect(new Dictionary([]).lookup("anything").status).toBe("unknown");
+    });
+});
+
+describe("loadDictionary", () => {
+    it("reads a JSON file", () => {
+        const path = join(directory, "dictionary.json");
+        writeFileSync(path, JSON.stringify(["valve"]));
+        expect(loadDictionary(path).lookup("valve").status).toBe("approved");
+    });
+
+    it("gives clear errors for a missing file and a file that is not JSON", () => {
+        expect(() => loadDictionary(join(directory, "missing.json"))).toThrow("Cannot read the dictionary file");
+        const path = join(directory, "broken.json");
+        writeFileSync(path, "[");
+        expect(() => loadDictionary(path)).toThrow("is not valid JSON");
+    });
+});

package/src/dictionary.ts

@@ -0,0 +1,26 @@
+/**
+ * The local dictionary file. The format and the lookup are in
+ * `dictionary-core.ts`, which a browser can use. This module reads the file.
+ */
+
+import { readFileSync } from "node:fs";
+import { DictionaryError, parseDictionary, type Dictionary } from "./dictionary-core.js";
+
+export * from "./dictionary-core.js";
+
+/** This function reads a dictionary file. */
+export function loadDictionary(path : string) : Dictionary {
+    let text : string;
+    try {
+        text = readFileSync(path, "utf8");
+    } catch (error) {
+        throw new DictionaryError(`Cannot read the dictionary file ${path}: ${(error as Error).message}`);
+    }
+    let value : unknown;
+    try {
+        value = JSON.parse(text);
+    } catch (error) {
+        throw new DictionaryError(`${path}: the file is not valid JSON: ${(error as Error).message}`);
+    }
+    return parseDictionary(value, path);
+}

package/src/engine.ts

@@ -0,0 +1,138 @@
+/**
+ * The lint engine without a file system. It extracts the prose of a text,
+ * runs the rules on each prose unit, and gives the findings with their lines
+ * and columns. A browser can use this module.
+ */
+
+import type { ResolvedConfig } from "./config-core.js";
+import { buildLexicon, type Lexicon } from "./lexicon.js";
+import { RULES, type Rule } from "./rules/index.js";
+import { WordListMatcher } from "./rules/word-list-matcher.js";
+import { LineIndex } from "./source/lines.js";
+import { extractMarkdown, type Extraction } from "./source/markdown.js";
+import { isSuppressed } from "./source/suppressions.js";
+import type { Finding, RuleId, Severity } from "./types.js";
+import { buildUnit, type ProseUnit } from "./units.js";
+
+export type FileKind = "markdown" | "mdx" | "typescript";
+
+/** The kind of a file, from its extension, or null when the linter cannot read it. */
+export function fileKind(path : string) : FileKind | null {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".mdx")) return "mdx";
+    if (lower.endsWith(".md") || lower.endsWith(".markdown")) return "markdown";
+    if (/\.(?:[mc]?ts|tsx|[mc]?js|jsx)$/.test(lower) && !lower.endsWith(".d.ts")) return "typescript";
+    return null;
+}
+
+/**
+ * A function that extracts the prose of a TypeScript or JavaScript file:
+ * the doc comments, and the JSX text of a TSX or JSX file.
+ */
+export type CodeExtractor = (text : string, path : string) => Extraction;
+
+export type ProseLinterOptions = {
+    /**
+     * The extractor for TypeScript and JavaScript files. Without it, the
+     * linter gives no findings for these files. The extractor of this
+     * package (`extractCode`) needs the `typescript` package.
+     */
+    readonly extractCode? : CodeExtractor;
+};
+
+/**
+ * A linter for one configuration, for text in memory. It makes the lexicon
+ * and the word list matcher one time. It reads no file.
+ */
+export class ProseLinter {
+    readonly lexicon : Lexicon;
+    private readonly wordList : WordListMatcher;
+    private readonly rules : ReadonlyArray<{ readonly rule : Rule; readonly override : Severity | null }>;
+    private readonly extractCode : CodeExtractor | null;
+
+    constructor(readonly config : ResolvedConfig, lexicon? : Lexicon, options : ProseLinterOptions = {}) {
+        this.lexicon = lexicon ?? buildLexicon(config);
+        this.wordList = new WordListMatcher(config.wordList);
+        this.extractCode = options.extractCode ?? null;
+        this.rules = RULES.flatMap((rule) => {
+            const setting = config.rules[rule.id];
+            if (setting === "off") return [];
+            if (rule.id === "unknown-word" && this.lexicon.dictionary === null) return [];
+            return [{ rule, override : setting ?? null }];
+        });
+    }
+
+    /** The prose units of a file. */
+    units(text : string, path : string) : ProseUnit[] {
+        return this.extract(text, path).blocks.flatMap((block) => buildUnit(block, this.lexicon) ?? []);
+    }
+
+    /** The findings in `text`. `path` gives the kind of file, and it is the file name in the findings. */
+    lintText(text : string, path : string) : Finding[] {
+        const extraction = this.extract(text, path);
+        const lineIndex = new LineIndex(text);
+        type Raw = { ruleId : RuleId; severity : Severity; start : number; end : number; message : string; eachWord : boolean };
+        const raw : Raw[] = [];
+        for (const block of extraction.blocks) {
+            const unit = buildUnit(block, this.lexicon);
+            if (unit === null) continue;
+            const wordOnly = unit.kind !== "paragraph";
+            for (const { rule, override } of this.rules) {
+                if (wordOnly && rule.scope !== "word") continue;
+                rule.check(unit, {
+                    config : this.config,
+                    lexicon : this.lexicon,
+                    wordList : this.wordList,
+                    report : (report) => {
+                        raw.push({
+                            ruleId : rule.id,
+                            severity : override ?? report.severity ?? rule.defaultSeverity,
+                            start : report.start,
+                            end : report.end,
+                            message : report.message,
+                            eachWord : reportsEachWord(rule),
+                        });
+                    },
+                });
+            }
+        }
+        // An unknown word that another rule reports already gets no second finding. A finding for a
+        // sentence, a paragraph or a noun cluster does not report each word in it.
+        const others = raw.filter((finding) => finding.ruleId !== "unknown-word" && finding.eachWord);
+        const kept = raw.filter((finding) => finding.ruleId !== "unknown-word"
+            || !others.some((other) => other.start < finding.end && finding.start < other.end));
+        return kept
+            .filter((finding) => !isSuppressed(extraction.suppressions, finding.ruleId, finding.start))
+            .sort((a, b) => a.start - b.start || a.end - b.end || a.ruleId.localeCompare(b.ruleId))
+            .map((finding) => {
+                const start = lineIndex.position(finding.start);
+                const end = lineIndex.position(Math.max(finding.start, finding.end));
+                return {
+                    file : path,
+                    line : start.line,
+                    column : start.column,
+                    endLine : end.line,
+                    endColumn : end.column,
+                    ruleId : finding.ruleId,
+                    severity : finding.severity,
+                    message : finding.message,
+                };
+            });
+    }
+
+    private extract(text : string, path : string) : Extraction {
+        const kind = fileKind(path);
+        if (kind === "typescript") return this.extractCode === null ? { blocks : [], suppressions : [] } : this.extractCode(text, path);
+        if (kind === null) return { blocks : [], suppressions : [] };
+        return extractMarkdown(text, { mdx : kind === "mdx" });
+    }
+}
+
+/**
+ * True when a finding of the rule is about each word in its range. A word rule reports a word or a
+ * phrase, for example a modal verb or a word list phrase. The noun-cluster rule reports a group of
+ * nouns, and the sentence and paragraph rules report a full sentence or paragraph.
+ */
+function reportsEachWord(rule : Rule) : boolean {
+    return rule.scope === "word" && rule.id !== "noun-cluster";
+}