@mark1russell7/ste-lint 0.0.0-bootstrap.0 → 0.1.1

package/src/rules/punctuation.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig } from "../config.js";
+import { Linter } from "../lint.js";
+import type { RuleId } from "../types.js";
+
+const linter = new Linter(resolveConfig({}, { root : "/" }));
+const lint = (rule : RuleId, text : string, path : string = "doc.md") => linter.lintText(text, path).filter((finding) => finding.ruleId === rule);
+const found = (rule : RuleId, text : string) : string[] => lint(rule, text).map((finding) => text.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("semicolon", () => {
+    it("reports semicolons in prose", () => {
+        const findings = lint("semicolon", "The first part; the second part.");
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ line : 1, column : 15, severity : "error" });
+        expect(findings[0]!.message).toContain("two sentences");
+    });
+
+    it("does not report semicolons in code spans, code blocks, HTML entities or URLs", () => {
+        expect(lint("semicolon", "Write `a; b` and &   here.\n\n```js\nf(); g();\n```\n\nRead https://x.dev/a;b now.")).toEqual([]);
+    });
+
+    it("reports semicolons in doc comments, but not in the code", () => {
+        expect(lint("semicolon", "/** A; b. */\nconst a = 1; const b = 2;", "a.ts")).toHaveLength(1);
+    });
+});
+
+describe("latin-abbreviation", () => {
+    it("reports e.g., i.e., etc., vs., viz., cf. and et al.", () => {
+        expect(found("latin-abbreviation", "Some, e.g. this, i.e. that, etc. A vs. B, viz. C, cf. D, Smith et al. wrote.")).toEqual([
+            "e.g.", "i.e.", "etc.", "vs.", "viz.", "cf.", "et al.",
+        ]);
+    });
+
+    it("reports the forms without periods that cannot be other words", () => {
+        expect(found("latin-abbreviation", "A vs B, and so on etc, and E.g., this.")).toEqual(["vs", "etc", "E.g."]);
+    });
+
+    it("gives the alternative in the message", () => {
+        expect(lint("latin-abbreviation", "Use a tool, e.g. a linter.")[0]!.message).toContain("\"for example\"");
+    });
+
+    it("does not report other words", () => {
+        expect(found("latin-abbreviation", "VS Code, IE and the cf flag are names. The etcetera word and /etc/hosts are fine. Et cetera, et cetera.")).toEqual([]);
+        expect(found("latin-abbreviation", "The constructor and the prototype are words.")).toEqual([]);
+    });
+});
+
+describe("about-quantity", () => {
+    it("reports \"about\" before a number or a quantity", () => {
+        expect(found("about-quantity", "It takes about 5 ms. About twenty runs. About a second. About an hour. About 10%. About ~3.")).toEqual([
+            "about", "About", "About", "About", "About", "About",
+        ]);
+        expect(lint("about-quantity", "It takes about 5 ms.")[0]!.message).toContain("\"approximately\"");
+    });
+
+    it("does not report \"about\" before a topic", () => {
+        expect(found("about-quantity", "Read about the monitor. It is about a page. Approximately 5 ms is fine.")).toEqual([]);
+    });
+});

package/src/rules/rule.ts

@@ -0,0 +1,73 @@
+import type { ResolvedConfig } from "../config.js";
+import type { Lexicon } from "../lexicon.js";
+import type { Token } from "../text/tokens.js";
+import type { RuleId, Severity } from "../types.js";
+import type { ProseUnit, Sentence } from "../units.js";
+import type { WordListMatcher } from "./word-list-matcher.js";
+
+/**
+ * Which units a rule examines. Headings and table cells get only the
+ * "word" rules. Paragraphs and list items get all rules.
+ */
+export type RuleScope = "word" | "sentence" | "paragraph";
+
+export type Report = {
+    /** The file offset of the first character of the problem. */
+    readonly start : number;
+    /** The file offset after the last character of the problem. */
+    readonly end : number;
+    readonly message : string;
+    /** The severity of this finding, when it is not the default severity of the rule (for example a word list entry). */
+    readonly severity? : Severity;
+};
+
+export type RuleContext = {
+    readonly config : ResolvedConfig;
+    readonly lexicon : Lexicon;
+    readonly wordList : WordListMatcher;
+    report(report : Report) : void;
+};
+
+export type Rule = {
+    readonly id : RuleId;
+    /** One sentence that tells what the rule finds. */
+    readonly description : string;
+    /** The related ASD-STE100 rule numbers. */
+    readonly ste : string;
+    readonly defaultSeverity : Severity;
+    readonly scope : RuleScope;
+    check(unit : ProseUnit, context : RuleContext) : void;
+};
+
+/** The surface text of `tokens[from]` to `tokens[to - 1]`, with one space between tokens that had space between them. */
+export function surface(tokens : readonly Token[], from : number, to : number) : string {
+    let text = "";
+    for (let i = from; i < to; i++) {
+        const token = tokens[i]!;
+        const value = token.kind === "code" && token.placeholder !== null ? placeholderText(token) : token.text;
+        text += (i > from && token.spaceBefore ? " " : "") + value;
+    }
+    return text;
+}
+
+function placeholderText(token : Token) : string {
+    const placeholder = token.placeholder!;
+    switch (placeholder.kind) {
+        case "code": return `\`${placeholder.text}\``;
+        case "quote": return `"${placeholder.text}"`;
+        case "link": return `{${placeholder.text}}`;
+        default: return placeholder.text;
+    }
+}
+
+/** A report for the tokens `from` to `to - 1` of a sentence. */
+export function tokenRange(tokens : readonly Token[], from : number, to : number) : { start : number; end : number } {
+    return { start : tokens[from]!.start, end : tokens[to - 1]!.end };
+}
+
+/** This function gives each token of each sentence of the unit to `visit`. */
+export function forEachToken(unit : ProseUnit, visit : (tokens : readonly Token[], index : number, sentence : Sentence) => void) : void {
+    for (const sentence of unit.sentences) {
+        for (let i = 0; i < sentence.tokens.length; i++) visit(sentence.tokens, i, sentence);
+    }
+}

package/src/rules/semicolon.ts

@@ -0,0 +1,19 @@
+import { forEachToken, tokenRange, type Rule } from "./rule.js";
+
+export const semicolon : Rule = {
+    id : "semicolon",
+    description : "Find semicolons in prose. Semicolons in code spans are not prose.",
+    ste : "8.1",
+    defaultSeverity : "error",
+    scope : "word",
+    check(unit, context) {
+        forEachToken(unit, (tokens, i) => {
+            const token = tokens[i]!;
+            if (token.kind !== "punct" || (token.text !== ";" && token.text !== "；")) return;
+            context.report({
+                ...tokenRange(tokens, i, i + 1),
+                message : "Do not use a semicolon. Write two sentences, or use a comma and \"and\" or \"but\". For a list of items, use a vertical list.",
+            });
+        });
+    },
+};

package/src/rules/sentence-length.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig, type SteConfigFile } from "../config.js";
+import { Linter } from "../lint.js";
+
+const lint = (text : string, path : string = "doc.md", file : SteConfigFile = {}) =>
+    new Linter(resolveConfig(file, { root : "/" })).lintText(text, path).filter((finding) => finding.ruleId === "sentence-length");
+
+const words = (count : number, first : string = "The") : string => [first, ...Array.from({ length : count - 1 }, (_, i) => `word${i}`)].join(" ");
+
+describe("sentence-length", () => {
+    it("reports a description of more than 25 words", () => {
+        const findings = lint(`${words(26)}.`);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ line : 1, column : 1, severity : "error" });
+        expect(findings[0]!.message).toContain("26 words");
+        expect(findings[0]!.message).toContain("25 words");
+    });
+
+    it("accepts a description of 25 words", () => {
+        expect(lint(`${words(25)}.`)).toEqual([]);
+    });
+
+    it("uses the limit of 20 words for an instruction", () => {
+        expect(lint(`${words(21, "Remove")}.`)[0]!.message).toContain("This instruction has 21 words");
+        expect(lint(`${words(20, "Remove")}.`)).toEqual([]);
+    });
+
+    it("counts each code span as one word", () => {
+        const code = "`pnpm --filter @lag/ste-lint exec ste-lint --format json --max-warnings 10 README.md docs`";
+        expect(lint(`Run ${code} ${words(18, "now")}.`)).toEqual([]);
+        expect(lint(`Run ${code} ${words(19, "now")}.`)).toHaveLength(1);
+    });
+
+    it("reports a parenthesis with more than 25 words as a separate sentence", () => {
+        const findings = lint(`The value is fine (${words(26, "this")}).`);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]!.message).toContain("text in parentheses has 26 words");
+    });
+
+    it("does not examine headings or table cells", () => {
+        expect(lint(`# ${words(30)}\n\n| ${words(30)} |\n| --- |\n| ${words(30)} |`)).toEqual([]);
+    });
+
+    it("uses the limits of the configuration", () => {
+        expect(lint(`${words(11)}.`, "doc.md", { limits : { descriptionWords : 10 } })).toHaveLength(1);
+    });
+
+    it("examines doc comments and the text of block tags", () => {
+        expect(lint(`/** ${words(26)}. */\nexport const a = 1;`, "a.ts")).toHaveLength(1);
+        expect(lint(`/**\n * @param a - ${words(26)}.\n */\nexport function f(a : number) : number { return a; }`, "a.ts")).toHaveLength(1);
+    });
+});

package/src/rules/sentence-length.ts

@@ -0,0 +1,32 @@
+import { countWords } from "../text/sentences.js";
+import type { Rule } from "./rule.js";
+
+export const sentenceLength : Rule = {
+    id : "sentence-length",
+    description : "An instruction can have no more than 20 words. A description can have no more than 25 words.",
+    ste : "5.1, 6.3, 8.4-8.7",
+    defaultSeverity : "error",
+    scope : "sentence",
+    check(unit, context) {
+        const { instructionWords, descriptionWords } = context.config.limits;
+        for (const sentence of unit.sentences) {
+            const limit = sentence.instruction ? instructionWords : descriptionWords;
+            if (sentence.words > limit) {
+                const message = sentence.instruction
+                    ? `This instruction has ${sentence.words} words. Use no more than ${limit} words in an instruction. Divide it into shorter sentences.`
+                    : `This sentence has ${sentence.words} words. Use no more than ${limit} words in a descriptive sentence. Divide it into shorter sentences.`;
+                context.report({ start : sentence.start, end : sentence.end, message });
+            }
+            for (const inner of sentence.parentheticals) {
+                const words = countWords(inner, { properNouns : context.lexicon.properNounPhrases }).words;
+                if (words > descriptionWords) {
+                    context.report({
+                        start : inner[0]!.start,
+                        end : inner[inner.length - 1]!.end,
+                        message : `The text in parentheses has ${words} words. It counts as a separate sentence. Use no more than ${descriptionWords} words, or write it as a sentence after this one.`,
+                    });
+                }
+            }
+        }
+    },
+};

package/src/rules/unknown-word.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig, type SteConfigFile } from "../config.js";
+import { parseDictionary } from "../dictionary.js";
+import { buildLexicon } from "../lexicon.js";
+import { Linter } from "../lint.js";
+
+const dictionary = parseDictionary({
+    entries : [
+        ...["the", "a", "is", "it", "you", "and", "to", "of", "in", "on", "this", "with", "for", "can", "not", "do", "when", "file", "that"].map((word) => ({ word })),
+        { word : "make", pos : "verb", forms : ["makes", "made"] },
+        { word : "valve", pos : "noun" },
+        { word : "open", pos : "verb", forms : ["opens", "opened"] },
+        { word : "use", pos : "verb", forms : ["uses", "used"] },
+        { word : "utilize", pos : "verb", approved : false, alternatives : ["use"] },
+        { word : "frob", approved : false },
+    ],
+}, "test.json");
+
+const lint = (text : string, file : SteConfigFile = {}, path : string = "doc.md") => {
+    const config = resolveConfig(file, { root : "/" });
+    return new Linter(config, buildLexicon(config, dictionary)).lintText(text, path).filter((finding) => finding.ruleId === "unknown-word");
+};
+const found = (text : string, file : SteConfigFile = {}) : string[] => lint(text, file).map((finding) => text.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("unknown-word", () => {
+    it("is off without a dictionary", () => {
+        const linter = new Linter(resolveConfig({}, { root : "/" }));
+        expect(linter.lintText("Zorblat the frimble.", "doc.md").filter((finding) => finding.ruleId === "unknown-word")).toEqual([]);
+    });
+
+    it("reports words that are not in the dictionary or the glossary", () => {
+        expect(found("The valve opens the zorblat.")).toEqual(["zorblat"]);
+        const findings = lint("The valve opens the zorblat.");
+        expect(findings[0]!.severity).toBe("warning");
+        expect(findings[0]!.message).toContain("technicalNouns");
+    });
+
+    it("accepts approved forms, noun plurals and possessives, but not other verb forms", () => {
+        expect(found("The valves open. It made the valve's file. It opened.")).toEqual([]);
+        expect(found("It makings the file.")).toEqual(["makings"]);
+    });
+
+    it("gives the alternatives of a word that is not approved", () => {
+        expect(lint("You frob it.")[0]!.message).toContain("Use an approved word, or a different construction.");
+        expect(lint("Utilize it.", { rules : { "word-list" : "off" } })[0]!.message).toBe("\"utilize\" is not an approved word. Use \"use\".");
+    });
+
+    it("does not report glossary words, proper nouns, numbers, abbreviations, code or identifiers", () => {
+        const file : SteConfigFile = { technicalNouns : ["heartbeat", "worker thread"], technicalVerbs : ["flush"], properNouns : ["Grafana"], allowedWords : ["okay"] };
+        expect(found("The heartbeats flush in the worker thread. Grafana is okay. 42 API `zorblat` camelCase v1.2 x86.", file)).toEqual([]);
+    });
+
+    it("does not report a capitalized word after the start of a sentence, and checks each part of a hyphenated word", () => {
+        expect(found("The Zorblat opens it.")).toEqual([]);
+        expect(found("Zorblat opens it.")).toEqual(["Zorblat"]);
+        expect(found("The valve-zorblat opens.")).toEqual(["valve-zorblat"]);
+    });
+
+    it("does not add a finding to a word that another rule reports", () => {
+        expect(found("Utilize it.")).toEqual([]);
+    });
+
+    it("reports a word in a sentence, a paragraph or a noun cluster that a different rule reports", () => {
+        const all = (text : string, file : SteConfigFile = {}) => {
+            const config = resolveConfig(file, { root : "/" });
+            return new Linter(config, buildLexicon(config, dictionary)).lintText(text, "doc.md").map((finding) => finding.ruleId);
+        };
+        // A descriptive sentence with more than 25 words
+        const sentence = `The valve opens ${"the file and ".repeat(8)}the zorblat.`;
+        expect(all(sentence)).toContain("sentence-length");
+        expect(found(sentence)).toEqual(["zorblat"]);
+        // A paragraph with more than 6 sentences
+        const paragraph = `${"The valve opens the file. ".repeat(6)}The valve opens the zorblat.`;
+        expect(all(paragraph)).toContain("paragraph-length");
+        expect(found(paragraph)).toEqual(["zorblat"]);
+        // More than 3 nouns in sequence: "cache" and "buffer" are common nouns, but not in the dictionary
+        const cluster = "Open the valve file cache buffer.";
+        expect(all(cluster)).toContain("noun-cluster");
+        expect(found(cluster)).toEqual(["cache", "buffer"]);
+    });
+});

package/src/rules/unknown-word.ts

@@ -0,0 +1,43 @@
+import { isGlossaryWord } from "../lexicon.js";
+import { nextCounted } from "../text/grammar.js";
+import { isAbbreviation, isCapitalized, isIdentifierLike, isNumber, isWord } from "../text/tokens.js";
+import { coveredByPhrases } from "./ing-verb.js";
+import { tokenRange, type Rule } from "./rule.js";
+
+/**
+ * This rule is active only when a local dictionary is configured. It does
+ * not examine numbers, abbreviations, words that look like code or glossary
+ * terms. It also does not examine a word with a capital letter after the
+ * start of a sentence, because that word is possibly a proper noun.
+ */
+export const unknownWord : Rule = {
+    id : "unknown-word",
+    description : "Find words that are not in the local dictionary and not in the project glossary.",
+    ste : "1.1, 1.5, 1.12",
+    defaultSeverity : "warning",
+    scope : "word",
+    check(unit, context) {
+        const { lexicon } = context;
+        const dictionary = lexicon.dictionary;
+        if (dictionary === null) return;
+        for (const sentence of unit.sentences) {
+            const tokens = sentence.tokens;
+            const covered = coveredByPhrases(tokens, lexicon.glossaryPhrases);
+            const first = nextCounted(tokens, 0);
+            tokens.forEach((token, i) => {
+                if (!isWord(token) || covered.has(i)) return;
+                if (isNumber(token) || isAbbreviation(token) || isIdentifierLike(token) || /\d/.test(token.text)) return;
+                if (i !== first && isCapitalized(token)) return;
+                for (const part of token.lower.split("-")) {
+                    if (part.length === 0 || isGlossaryWord(part, lexicon)) continue;
+                    const lookup = dictionary.lookup(part);
+                    if (lookup.status === "approved") continue;
+                    const message = lookup.status === "not-approved"
+                        ? `"${part}" is not an approved word. ${lookup.alternatives.length > 0 ? `Use ${lookup.alternatives.map((word) => `"${word}"`).join(" or ")}.` : "Use an approved word, or a different construction."}`
+                        : `"${part}" is not in the dictionary or the project glossary. Use an approved word. If "${part}" is a technical term, add it to technicalNouns or technicalVerbs.`;
+                    context.report({ ...tokenRange(tokens, i, i + 1), message });
+                }
+            });
+        }
+    },
+};

package/src/rules/word-list-matcher.ts

@@ -0,0 +1,68 @@
+import { isClauseStart, isVerbUse } from "../text/grammar.js";
+import { PhraseMatcher, splitPhrase } from "../text/phrases.js";
+import { isWord, type Token } from "../text/tokens.js";
+import type { WordListEntry } from "../word-list.js";
+
+export type WordListMatch = {
+    readonly entry : WordListEntry;
+    readonly from : number;
+    readonly to : number;
+};
+
+/** Words before "see" that show the meaning "refer to": "(see X)", "For details, see X", "See also X". */
+const REFERENCE_BEFORE = new Set(["also", "please", "and", "or", "then"]);
+const REFERENCE_PUNCTUATION = new Set(["(", ",", ":", ";", "—", "–", "-"]);
+
+/** True when "see" at `index` tells the reader to look at other text, not to see with the eyes. */
+export function isReferenceSee(tokens : readonly Token[], index : number) : boolean {
+    const previous = tokens[index - 1];
+    if (previous === undefined || isClauseStart(tokens, index)) return true;
+    if (previous.kind === "punct") return REFERENCE_PUNCTUATION.has(previous.text);
+    return isWord(previous) && REFERENCE_BEFORE.has(previous.lower);
+}
+
+/** This class finds the entries of the word list in a sentence. */
+export class WordListMatcher {
+    private readonly phrases = new PhraseMatcher<WordListEntry>();
+    /** The single words of the list. Other rules skip these words, so that a word gets one finding. */
+    readonly words : ReadonlySet<string>;
+
+    constructor(entries : readonly WordListEntry[]) {
+        const words = new Set<string>();
+        for (const entry of entries) {
+            for (const match of entry.match) {
+                this.phrases.add(match, entry);
+                const parts = splitPhrase(match);
+                if (parts.length === 1) words.add(parts[0]!);
+            }
+        }
+        this.words = words;
+    }
+
+    /**
+     * The matches in `tokens`. The longest phrase wins. `skipWord` tells the
+     * matcher to ignore a single word, for example a glossary term.
+     */
+    find(tokens : readonly Token[], options : { readonly verbs : ReadonlySet<string>; readonly skipWord : (word : string) => boolean }) : WordListMatch[] {
+        const matches : WordListMatch[] = [];
+        let i = 0;
+        while (i < tokens.length) {
+            const match = this.phrases.match(tokens, i);
+            if (match === null) {
+                i++;
+                continue;
+            }
+            const entry = match.value;
+            const skip = (match.length === 1 && options.skipWord(tokens[i]!.lower))
+                || (entry.verbOnly && !isVerbUse(tokens, i, { verbs : options.verbs }))
+                || (entry.context === "reference" && !isReferenceSee(tokens, i));
+            if (skip) {
+                i++;
+                continue;
+            }
+            matches.push({ entry, from : i, to : i + match.length });
+            i += match.length;
+        }
+        return matches;
+    }
+}

package/src/rules/word-list.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig, type SteConfigFile } from "../config.js";
+import { Linter } from "../lint.js";
+import { WordListMatcher } from "./word-list-matcher.js";
+import { DEFAULT_WORD_LIST } from "../word-list.js";
+
+const lint = (text : string, file : SteConfigFile = {}, path : string = "doc.md") =>
+    new Linter(resolveConfig(file, { root : "/" })).lintText(text, path).filter((finding) => finding.ruleId === "word-list");
+const found = (text : string, file : SteConfigFile = {}) : string[] => lint(text, file).map((finding) => text.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("word-list", () => {
+    it("reports long words and gives the plain-language word", () => {
+        const findings = lint("Utilize the cache to initiate the run and ensure that it facilitates the work via the API.");
+        expect(findings.map((finding) => finding.message)).toEqual([
+            "Write \"use\", not \"Utilize\".",
+            "Write \"start\", not \"initiate\".",
+            "Write \"make sure\", not \"ensure\". Write \"that\" after it: \"make sure that ...\".",
+            "Write \"help\" or \"make ... easier\", not \"facilitates\".",
+            "Write \"through\" or \"with\", not \"via\".",
+        ]);
+        expect(findings.every((finding) => finding.severity === "error")).toBe(true);
+    });
+
+    it("reports phrases, and the longest phrase wins", () => {
+        expect(found("Prior to the run, and in order to stop, due to the fact that it fails, due to the load.")).toEqual([
+            "Prior to", "in order to", "due to the fact that", "due to",
+        ]);
+        expect(found("However, it works. Therefore, it stops. Ask whether or not it runs, or whether it stops. Tools such as this.")).toEqual([
+            "However", "Therefore", "whether or not", "runs", "whether", "such as",
+        ]);
+    });
+
+    it("reports the verbs that have simpler words", () => {
+        expect(found("It allows a restart. It requires a key. It provides data, provided that it runs. It executes code. It creates files. Kill it.")).toEqual([
+            "allows", "requires", "provides", "provided that", "runs", "executes", "creates", "Kill",
+        ]);
+    });
+
+    it("reports run, call, return and display only where they are verbs", () => {
+        expect(found("Run the tests. The monitor runs every second. Call `stop()`. It returns the value. The page displays a chart.")).toEqual([
+            "Run", "runs", "Call", "returns", "displays",
+        ]);
+        expect(found("A test run takes time. Each call is fast. The return value is 0. The display is dark.")).toEqual([]);
+    });
+
+    it("reports \"see\" only where it means \"refer to\"", () => {
+        expect(found("See the guide. For details, see `x`. Read it (see below). You can see the chart. I want to see it.")).toEqual([
+            "See", "see", "see",
+        ]);
+    });
+
+    it("reports filler words as warnings, and gives the time and negation alternatives", () => {
+        const findings = lint("It is simple. Simply run it. It is easily done. It is just a test. Please wait. It is currently off. Now it runs. It never stops.");
+        expect(findings.map((finding) => [finding.severity, finding.message.split(".")[0]])).toEqual([
+            ["warning", "Remove \"simple\""],
+            ["warning", "Remove \"Simply\""],
+            ["warning", "Write \"start\", \"starts\" or \"operates\", not \"run\""],
+            ["warning", "Remove \"easily\""],
+            ["warning", "Write \"only\", not \"just\""],
+            ["warning", "Remove \"Please\""],
+            ["error", "Write \"at this time\", not \"currently\""],
+            ["error", "Write \"at this time\", not \"Now\""],
+            ["warning", "Write \"start\", \"starts\" or \"operates\", not \"runs\""],
+            ["error", "Write \"do not\", not \"never\""],
+        ]);
+    });
+
+    it("does not report \"approximately\" or words in code", () => {
+        expect(found("It takes approximately 5 ms. Use `utilize()` and `createMonitor`.")).toEqual([]);
+    });
+
+    it("does not report a word that the glossary permits", () => {
+        expect(found("Run the tests.", { technicalVerbs : ["run"] })).toEqual([]);
+        expect(found("It creates a file.", { allowedWords : ["creates"] })).toEqual([]);
+    });
+
+    it("lets the configuration change, add and remove entries", () => {
+        const file : SteConfigFile = {
+            wordList : [
+                { id : "via", severity : "warning", suggest : "\"by\"" },
+                { match : ["blazingly fast"], suggest : "\"fast\"" },
+                { match : "simply", severity : "off" },
+                { id : "utilize", note : "Short words are better." },
+            ],
+        };
+        const findings = lint("Go via the API. It is blazingly fast. Simply utilize it.", file);
+        expect(findings.map((finding) => [finding.severity, finding.message])).toEqual([
+            ["warning", "Write \"by\", not \"via\"."],
+            ["error", "Write \"fast\", not \"blazingly fast\"."],
+            ["error", "Write \"use\", not \"utilize\". Short words are better."],
+        ]);
+    });
+
+    it("lets the rule setting override the severity of all entries", () => {
+        expect(lint("Utilize it.", { rules : { "word-list" : "warning" } })[0]!.severity).toBe("warning");
+        expect(lint("Utilize it.", { rules : { "word-list" : "off" } })).toEqual([]);
+    });
+
+    it("examines doc comments", () => {
+        expect(lint("/** This function returns the value. */\nexport const a = 1;", {}, "a.ts")).toHaveLength(1);
+    });
+});
+
+describe("WordListMatcher", () => {
+    it("gives the single words of the list, for the other rules", () => {
+        const matcher = new WordListMatcher(DEFAULT_WORD_LIST);
+        expect(matcher.words.has("running")).toBe(true);
+        expect(matcher.words.has("in order to")).toBe(false);
+    });
+});

package/src/rules/word-list.ts

@@ -0,0 +1,25 @@
+import { isGlossaryWord } from "../lexicon.js";
+import { surface, tokenRange, type Rule } from "./rule.js";
+
+export const wordList : Rule = {
+    id : "word-list",
+    description : "Find the words and phrases of the project word list, and give the plain-language words to use instead.",
+    ste : "1.1, 9.1",
+    defaultSeverity : "error",
+    scope : "word",
+    check(unit, context) {
+        for (const sentence of unit.sentences) {
+            const matches = context.wordList.find(sentence.tokens, {
+                verbs : context.lexicon.verbs,
+                skipWord : (word) => isGlossaryWord(word, context.lexicon),
+            });
+            for (const match of matches) {
+                const found = surface(sentence.tokens, match.from, match.to);
+                const { entry } = match;
+                let message = entry.suggest === null ? `Remove "${found}".` : `Write ${entry.suggest}, not "${found}".`;
+                if (entry.note !== null) message += ` ${entry.note}`;
+                context.report({ ...tokenRange(sentence.tokens, match.from, match.to), message, severity : entry.severity });
+            }
+        }
+    },
+};