@mark1russell7/ste-lint 0.0.0-stage → 0.1.1

package/src/lint.test.ts

@@ -0,0 +1,182 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveConfig, type SteConfigFile } from "./config.js";
+import { formatJson, formatText, summarize } from "./format.js";
+import { fileKind, Linter, lintText } from "./lint.js";
+import { getRule, RULES } from "./rules/index.js";
+import { RULE_IDS, isRuleId, type Finding } from "./types.js";
+
+const config = (file : SteConfigFile = {}) => resolveConfig(file, { root : "/" });
+const ids = (findings : readonly Finding[]) : string[] => findings.map((finding) => finding.ruleId);
+
+describe("fileKind", () => {
+    it("knows Markdown, MDX and TypeScript files", () => {
+        expect(fileKind("a.md")).toBe("markdown");
+        expect(fileKind("a.markdown")).toBe("markdown");
+        expect(fileKind("a.MDX")).toBe("mdx");
+        expect(fileKind("a.ts")).toBe("typescript");
+        expect(fileKind("a.tsx")).toBe("typescript");
+        expect(fileKind("a.mjs")).toBe("typescript");
+        expect(fileKind("a.d.ts")).toBeNull();
+        expect(fileKind("a.json")).toBeNull();
+    });
+});
+
+describe("Linter on TSX files", () => {
+    it("examines the text that the user interface shows, and the doc comments", () => {
+        const source = [
+            "/** Returns the page. */",
+            "export function Page() {",
+            "    return <p>The run may fail; <code>pnpm results</code> utilizes the data.</p>;",
+            "}",
+        ].join("\n");
+        const findings = lintText(source, "Page.tsx", config());
+        expect(ids(findings)).toEqual(expect.arrayContaining(["missing-subject", "modal-verb", "semicolon", "word-list"]));
+        const modal = findings.find((finding) => finding.ruleId === "modal-verb")!;
+        expect([modal.line, modal.column]).toEqual([3, source.split("\n")[2]!.indexOf("may") + 1]);
+    });
+
+    it("does not examine the text of JSX in a .ts file", () => {
+        expect(lintText("const a = 'You should stop.';", "a.ts", config())).toEqual([]);
+    });
+});
+
+describe("Linter", () => {
+    it("gives findings with the file, the position and the rule, in order", () => {
+        const findings = lintText("# Title\n\nYou should stop; it may fail.", "doc.md", config());
+        expect(findings.map((finding) => [finding.file, finding.line, finding.column, finding.ruleId, finding.severity])).toEqual([
+            ["doc.md", 3, 5, "modal-verb", "error"],
+            ["doc.md", 3, 16, "semicolon", "error"],
+            ["doc.md", 3, 21, "modal-verb", "error"],
+        ]);
+        expect(findings[0]).toMatchObject({ endLine : 3, endColumn : 11 });
+    });
+
+    it("gives correct positions in files with CRLF line ends", () => {
+        const markdown = lintText("# Title\r\n\r\nText. You should stop.\r\n", "doc.md", config());
+        expect(markdown.map((finding) => [finding.line, finding.column])).toEqual([[3, 11]]);
+        const source = lintText("/**\r\n * Text.\r\n * You should stop.\r\n */\r\nexport const a = 1;\r\n", "a.ts", config());
+        expect(source.map((finding) => [finding.line, finding.column])).toEqual([[3, 8]]);
+    });
+
+    it("gives correct positions after an HTML entity of a character outside the BMP", () => {
+        const text = "Text &#x1F600; then you should stop.";
+        const findings = lintText(text, "doc.md", config());
+        expect(findings.map((finding) => [finding.ruleId, finding.column, finding.endColumn])).toEqual([["modal-verb", text.indexOf("should") + 1, text.indexOf("should") + 7]]);
+    });
+
+    it("gives no findings for a file kind that it cannot read", () => {
+        expect(lintText("You should stop.", "a.json", config())).toEqual([]);
+    });
+
+    it("applies severity overrides and turns rules off", () => {
+        const findings = lintText("You should stop; now.", "doc.md", config({ rules : { "modal-verb" : "warning", semicolon : "off" } }));
+        expect(findings.map((finding) => [finding.ruleId, finding.severity])).toEqual([
+            ["modal-verb", "warning"],
+            ["word-list", "error"],
+        ]);
+    });
+
+    it("runs only the word rules on headings and table cells", () => {
+        const long = Array.from({ length : 30 }, (_, i) => `word${i}`).join(" ");
+        const findings = lintText(`# ${long} should\n\n| ${long} may |\n| --- |\n| x |`, "doc.md", config());
+        expect(ids(findings)).toEqual(["modal-verb", "modal-verb"]);
+    });
+
+    it("applies suppression comments in Markdown", () => {
+        const markdown = [
+            "<!-- ste-disable-next modal-verb -->",
+            "You should stop; it may fail.",
+            "",
+            "<!-- ste-disable -->",
+            "You should stop.",
+            "<!-- ste-enable -->",
+            "",
+            "You should stop.",
+        ].join("\n");
+        expect(lintText(markdown, "doc.md", config()).map((finding) => [finding.line, finding.ruleId])).toEqual([
+            [2, "semicolon"],
+            [8, "modal-verb"],
+        ]);
+    });
+
+    it("applies suppression comments in TypeScript", () => {
+        const source = "// ste-disable-next\n/** You should stop; now. */\nexport const a = 1;\n/** You should stop. */\nexport const b = 2;\n";
+        expect(lintText(source, "a.ts", config()).map((finding) => [finding.line, finding.ruleId])).toEqual([[4, "modal-verb"]]);
+    });
+
+    it("keeps an ste-enable for one rule from stopping a range for all rules", () => {
+        const markdown = "<!-- ste-disable semicolon modal-verb -->\nYou should; stop.\n<!-- ste-enable semicolon -->\nYou should; stop.\n\n<!-- ste-disable -->\n<!-- ste-enable semicolon -->\nYou should; stop.";
+        expect(lintText(markdown, "doc.md", config()).map((finding) => [finding.line, finding.ruleId])).toEqual([[4, "semicolon"]]);
+    });
+
+    it("gives the prose units of a file", () => {
+        const linter = new Linter(config());
+        const units = linter.units("# Title\n\nOne. Two.\n\n```\ncode\n```", "doc.md");
+        expect(units.map((unit) => [unit.kind, unit.sentences.length])).toEqual([["heading", 1], ["paragraph", 2]]);
+    });
+
+    it("reads a file from the disk", () => {
+        const directory = mkdtempSync(join(tmpdir(), "ste-lint-"));
+        try {
+            const path = join(directory, "doc.md");
+            writeFileSync(path, "You should stop.");
+            const linter = new Linter(config());
+            expect(linter.lintFile(path, "doc.md")[0]!.file).toBe("doc.md");
+            expect(linter.lintFile(path)[0]!.file).toBe(path);
+        } finally {
+            rmSync(directory, { recursive : true, force : true });
+        }
+    });
+});
+
+describe("rules", () => {
+    it("has one rule for each rule ID, with a description and an STE reference", () => {
+        expect(RULES.map((rule) => rule.id)).toEqual([...RULE_IDS]);
+        for (const id of RULE_IDS) {
+            expect(getRule(id).description.length).toBeGreaterThan(10);
+            expect(getRule(id).ste.length).toBeGreaterThan(0);
+        }
+        expect(isRuleId("semicolon")).toBe(true);
+        expect(isRuleId("nope")).toBe(false);
+    });
+});
+
+describe("format", () => {
+    const findings = lintText("You should stop; now.\n\nOur tool.", "doc.md", config());
+    const summary = summarize(findings, 3);
+
+    it("counts the findings by severity and by rule", () => {
+        expect(summary).toEqual({
+            files : 3,
+            filesWithFindings : 1,
+            errors : 3,
+            warnings : 1,
+            byRule : {
+                "modal-verb" : { errors : 1, warnings : 0 },
+                "semicolon" : { errors : 1, warnings : 0 },
+                "word-list" : { errors : 1, warnings : 0 },
+                "first-person" : { errors : 0, warnings : 1 },
+            },
+        });
+    });
+
+    it("writes text with one group for each file, a summary and the counts by rule", () => {
+        const text = formatText(findings, summary);
+        expect(text).toContain("doc.md\n  1:5   error    Do not use the modal verb \"should\".");
+        expect(text).toContain("  modal-verb");
+        expect(text).toContain("4 problems (3 errors, 1 warning) in 1 file of 3.");
+        expect(text).toContain("Findings by rule:");
+        expect(text).toMatch(/first-person\s+1 {2}\(1 warning\)/);
+        expect(formatText([], summarize([], 1))).toBe("No problems found in 1 file.\n");
+    });
+
+    it("writes JSON with the summary and the findings", () => {
+        const json = JSON.parse(formatJson(findings, summary)) as { tool : string; summary : unknown; findings : Finding[] };
+        expect(json.tool).toBe("ste-lint");
+        expect(json.summary).toEqual(summary);
+        expect(json.findings).toHaveLength(4);
+    });
+});

package/src/lint.ts

@@ -0,0 +1,135 @@
+/**
+ * The lint engine. It extracts the prose of a file, runs the rules on each
+ * prose unit, and gives the findings with their lines and columns.
+ */
+
+import { readFileSync } from "node:fs";
+import type { ResolvedConfig } from "./config.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 { extractTsdoc } from "./source/tsdoc.js";
+import { extractJsxText } from "./source/jsx.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 linter for one configuration. It makes the lexicon and the word list matcher one time. */
+export class Linter {
+    readonly lexicon : Lexicon;
+    private readonly wordList : WordListMatcher;
+    private readonly rules : ReadonlyArray<{ readonly rule : Rule; readonly override : Severity | null }>;
+
+    constructor(readonly config : ResolvedConfig, lexicon? : Lexicon) {
+        this.lexicon = lexicon ?? buildLexicon(config);
+        this.wordList = new WordListMatcher(config.wordList);
+        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 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 = 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,
+                };
+            });
+    }
+
+    /** The findings in a file on disk. `displayPath` is the file name in the findings. */
+    lintFile(path : string, displayPath : string = path) : Finding[] {
+        return this.lintText(readFileSync(path, "utf8"), displayPath);
+    }
+}
+
+/**
+ * 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";
+}
+
+function extract(text : string, path : string) : Extraction {
+    const kind = fileKind(path);
+    if (kind === "typescript") {
+        const comments = extractTsdoc(text, path);
+        if (!/\.[jt]sx$/i.test(path)) return comments;
+        // The text that the user interface shows
+        return { blocks : [...comments.blocks, ...extractJsxText(text, path).blocks], suppressions : comments.suppressions };
+    }
+    if (kind === null) return { blocks : [], suppressions : [] };
+    return extractMarkdown(text, { mdx : kind === "mdx" });
+}
+
+/** The findings in `text`, with a new linter. To lint many files, make one `Linter` and use it again. */
+export function lintText(text : string, path : string, config : ResolvedConfig, lexicon? : Lexicon) : Finding[] {
+    return new Linter(config, lexicon).lintText(text, path);
+}

package/src/rules/about-quantity.ts

@@ -0,0 +1,33 @@
+import { isNumber, isWord } from "../text/tokens.js";
+import { UNITS } from "../text/words.js";
+import { forEachToken, tokenRange, type Rule } from "./rule.js";
+
+/** Words after "about a" or "about an" that make a quantity: "about a second", "about an hour". */
+const QUANTITY_AFTER_ARTICLE = new Set([
+    "dozen", "few", "hundred", "thousand", "million", "billion", "third", "quarter", "half", "factor", "tenth",
+]);
+
+export const aboutQuantity : Rule = {
+    id : "about-quantity",
+    description : "Find \"about\" before a number or a quantity, where the word means \"approximately\".",
+    ste : "1.3, 9.2",
+    defaultSeverity : "error",
+    scope : "word",
+    check(unit, context) {
+        forEachToken(unit, (tokens, i) => {
+            const token = tokens[i]!;
+            if (!isWord(token) || token.lower !== "about") return;
+            const next = tokens[i + 1];
+            const after = tokens[i + 2];
+            const quantity = isNumber(next)
+                || (next !== undefined && next.text === "~")
+                || (isWord(next) && /^\d/.test(next.text))
+                || (isWord(next) && (next.lower === "a" || next.lower === "an") && isWord(after) && (QUANTITY_AFTER_ARTICLE.has(after.lower) || UNITS.has(after.lower)));
+            if (!quantity) return;
+            context.report({
+                ...tokenRange(tokens, i, i + 1),
+                message : "Do not use \"about\" for a quantity. Write \"approximately\". Use \"about\" only for a topic, for example \"about the monitor\".",
+            });
+        });
+    },
+};

package/src/rules/index.ts

@@ -0,0 +1,40 @@
+import type { RuleId } from "../types.js";
+import { aboutQuantity } from "./about-quantity.js";
+import { ingVerb } from "./ing-verb.js";
+import { latinAbbreviation } from "./latin-abbreviation.js";
+import { missingSubjectRule } from "./missing-subject.js";
+import { modalVerb } from "./modal-verb.js";
+import { nounCluster } from "./noun-cluster.js";
+import { paragraphLength } from "./paragraph-length.js";
+import { passiveInstruction } from "./passive-instruction.js";
+import { firstPerson, genderedPronoun } from "./pronouns.js";
+import type { Rule } from "./rule.js";
+import { semicolon } from "./semicolon.js";
+import { sentenceLength } from "./sentence-length.js";
+import { unknownWord } from "./unknown-word.js";
+import { wordList } from "./word-list.js";
+
+/** All rules, in the order of the documentation. */
+export const RULES : readonly Rule[] = [
+    sentenceLength,
+    paragraphLength,
+    modalVerb,
+    semicolon,
+    latinAbbreviation,
+    aboutQuantity,
+    wordList,
+    genderedPronoun,
+    firstPerson,
+    passiveInstruction,
+    nounCluster,
+    missingSubjectRule,
+    ingVerb,
+    unknownWord,
+];
+
+/** The rule with the ID `id`. */
+export function getRule(id : RuleId) : Rule {
+    return RULES.find((rule) => rule.id === id)!;
+}
+
+export type { Report, Rule, RuleContext, RuleScope } from "./rule.js";

package/src/rules/ing-verb.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig, type SteConfigFile } from "../config.js";
+import { Linter } from "../lint.js";
+import { COMMON_VERBS } from "../text/words.js";
+import { baseForm } from "./ing-verb.js";
+
+const lint = (text : string, file : SteConfigFile = {}) =>
+    new Linter(resolveConfig(file, { root : "/" })).lintText(text, "doc.md").filter((finding) => finding.ruleId === "ing-verb");
+const found = (text : string, file : SteConfigFile = {}) : string[] => lint(text, file).map((finding) => text.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("ing-verb", () => {
+    it("reports -ing forms used as verbs", () => {
+        expect(found("The browser is throttling timers.")).toEqual(["throttling"]);
+        expect(found("Stop it by closing the tab.")).toEqual(["closing"]);
+        expect(found("Using the worker, the monitor measures lag.")).toEqual(["Using"]);
+        expect(found("A timer firing every second is fine.")).toEqual(["firing"]);
+        expect(found("The monitor is still waiting.")).toEqual(["waiting"]);
+        const findings = lint("Stop it by closing the tab.");
+        expect(findings[0]!.severity).toBe("warning");
+        expect(findings[0]!.message).toContain("when you close");
+    });
+
+    it("does not report nouns, adjectives or words that are not verbs", () => {
+        expect(found("The timing is good. The existing code works. Add something during the morning. The string is missing. The mark is outstanding.")).toEqual([]);
+        expect(found("Logging is fast.")).toEqual([]);
+    });
+
+    it("does not examine headings", () => {
+        expect(found("# Troubleshooting by restarting the worker")).toEqual([]);
+    });
+
+    it("does not report technical nouns and allowed words", () => {
+        expect(found("The page is blocking the thread.", { technicalNouns : ["blocking"] })).toEqual([]);
+        expect(found("The page is buffering the data.", { allowedWords : ["buffering"] })).toEqual([]);
+        expect(found("Read the logging pipeline docs about closing the logging pipeline.", { technicalNouns : ["logging pipeline"] })).toEqual(["closing"]);
+    });
+
+    it("does not report a word that the word list reports", () => {
+        expect(found("The worker is running.")).toEqual([]);
+    });
+
+    it("gives the base form of a known verb for the message", () => {
+        expect(baseForm("running", COMMON_VERBS)).toBe("run");
+        expect(baseForm("using", COMMON_VERBS)).toBe("use");
+        expect(baseForm("frobnicating", COMMON_VERBS)).toBeNull();
+        expect(lint("It is frobnicating the data.")[0]!.message).not.toContain("for example");
+    });
+});

package/src/rules/ing-verb.ts

@@ -0,0 +1,54 @@
+import { isIngVerbUse, lemmas } from "../text/grammar.js";
+import type { PhraseMatcher } from "../text/phrases.js";
+import { isCounted, isWord, type Token } from "../text/tokens.js";
+import { NON_VERB_ING } from "../text/words.js";
+import { forEachToken, tokenRange, type Rule } from "./rule.js";
+
+/** The token indices that a multi-word glossary phrase covers. */
+export function coveredByPhrases(tokens : readonly Token[], phrases : PhraseMatcher) : Set<number> {
+    const covered = new Set<number>();
+    if (phrases.empty) return covered;
+    for (let i = 0; i < tokens.length; i++) {
+        const length = phrases.longestMatch(tokens, i);
+        if (length > 1) for (let k = i; k < i + length; k++) covered.add(k);
+    }
+    return covered;
+}
+
+/** The base form of an -ing word when it is a known verb ("running" gives "run"), or null. */
+export function baseForm(word : string, verbs : ReadonlySet<string>) : string | null {
+    return lemmas(word).find((form) => form !== word && verbs.has(form)) ?? null;
+}
+
+export const ingVerb : Rule = {
+    id : "ing-verb",
+    description : "Find -ing forms used as verbs. Headings, technical nouns and allowed words are not examined.",
+    ste : "3.2, 3.5",
+    defaultSeverity : "warning",
+    scope : "word",
+    check(unit, context) {
+        if (unit.kind === "heading") return;
+        const { lexicon, wordList } = context;
+        let covered : Set<number> = new Set();
+        let current : readonly Token[] | null = null;
+        forEachToken(unit, (tokens, i) => {
+            if (tokens !== current) {
+                current = tokens;
+                covered = coveredByPhrases(tokens, lexicon.technicalNounPhrases);
+            }
+            const token = tokens[i]!;
+            if (!isWord(token) || !isCounted(token)) return;
+            const lower = token.lower;
+            if (lower.length < 5 || !/^[a-z]+ing$/.test(lower)) return;
+            if (NON_VERB_ING.has(lower) || lexicon.technicalNouns.has(lower) || lexicon.properNouns.has(lower) || lexicon.allowedWords.has(lower)) return;
+            if (wordList.words.has(lower) || covered.has(i)) return;
+            if (!isIngVerbUse(tokens, i)) return;
+            const base = baseForm(lower, lexicon.verbs);
+            const example = base === null ? "" : `, for example "when you ${base} ..." or "to ${base} ..."`;
+            context.report({
+                ...tokenRange(tokens, i, i + 1),
+                message : `Do not use "${token.text}" as a verb. Use a simple tense, the infinitive or a noun${example}. If "${lower}" is a technical noun, add it to technicalNouns.`,
+            });
+        });
+    },
+};

package/src/rules/latin-abbreviation.ts

@@ -0,0 +1,46 @@
+import { isWord } from "../text/tokens.js";
+import { forEachToken, tokenRange, type Rule } from "./rule.js";
+
+// A map, not an object literal, so that a word such as "constructor" does not find an Object property.
+const HELP : ReadonlyMap<string, { readonly name : string; readonly help : string }> = new Map([
+    ["e.g", { name : "e.g.", help : "Write \"for example\"." }],
+    ["eg", { name : "eg.", help : "Write \"for example\"." }],
+    ["i.e", { name : "i.e.", help : "Write \"that is\", or write a separate sentence." }],
+    ["ie", { name : "ie.", help : "Write \"that is\", or write a separate sentence." }],
+    ["etc", { name : "etc.", help : "Give all the items, or write \"for example\" before the items." }],
+    ["vs", { name : "vs.", help : "Write \"compared to\", \"and\" or \"or\"." }],
+    ["viz", { name : "viz.", help : "Write \"that is\" or \"for example\"." }],
+    ["cf", { name : "cf.", help : "Write \"compare with\" or \"refer to\"." }],
+]);
+
+/** Abbreviations that are a problem only with a period after them, because the letters alone can be another word. */
+const NEEDS_PERIOD = new Set(["eg", "ie", "cf"]);
+
+export const latinAbbreviation : Rule = {
+    id : "latin-abbreviation",
+    description : "Find Latin abbreviations: e.g., i.e., etc., vs., viz., cf. and et al.",
+    ste : "GR-6",
+    defaultSeverity : "error",
+    scope : "word",
+    check(unit, context) {
+        forEachToken(unit, (tokens, i) => {
+            const token = tokens[i]!;
+            if (!isWord(token)) return;
+            const next = tokens[i + 1];
+            const period = next !== undefined && next.kind === "punct" && next.text === "." && !next.spaceBefore;
+            const end = period ? i + 2 : i + 1;
+            if (token.lower === "et" && isWord(next) && next.lower === "al") {
+                const after = tokens[i + 2];
+                const withPeriod = after !== undefined && after.text === "." && !after.spaceBefore;
+                context.report({ ...tokenRange(tokens, i, withPeriod ? i + 3 : i + 2), message : "Do not use \"et al.\". Write \"and others\", or give the names." });
+                return;
+            }
+            const entry = HELP.get(token.lower);
+            if (entry === undefined) return;
+            // "VS" in capital letters is a name (for example "VS Code"), not "versus".
+            if (token.lower === "vs" && token.text === "VS") return;
+            if (NEEDS_PERIOD.has(token.lower) && (!period || token.text !== token.lower)) return;
+            context.report({ ...tokenRange(tokens, i, end), message : `Do not use the Latin abbreviation "${entry.name}". ${entry.help}` });
+        });
+    },
+};

package/src/rules/missing-subject.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig } from "../config.js";
+import { Linter } from "../lint.js";
+
+const linter = new Linter(resolveConfig({ technicalVerbs : ["flush"] }, { root : "/" }));
+const lint = (comment : string, path : string = "a.ts") =>
+    linter.lintText(`${comment}\nexport const a = 1;\n`, path).filter((finding) => finding.ruleId === "missing-subject");
+const found = (comment : string) : string[] => lint(comment).map((finding) => comment.split("\n")[finding.line - 1]!.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("missing-subject", () => {
+    it("reports a doc comment sentence that starts with a verb", () => {
+        expect(found("/** Returns the value. */")).toEqual(["Returns"]);
+        expect(found("/** Creates a monitor and starts it. */")).toEqual(["Creates"]);
+        expect(found("/** Stops `monitor` while the page is hidden. */")).toEqual(["Stops"]);
+        expect(found("/** Flushes the buffer. */")).toEqual(["Flushes"]);
+        expect(found("/** Applies the change. */")).toEqual(["Applies"]);
+        expect(found("/** Runs in the worker. */")).toEqual(["Runs"]);
+        const findings = lint("/** Returns the value. */");
+        expect(findings[0]!.severity).toBe("error");
+        expect(findings[0]!.message).toContain("This function gives");
+    });
+
+    it("reports a sentence that starts with an auxiliary verb or a participle", () => {
+        expect(found("/** Can be null. */")).toEqual(["Can"]);
+        expect(found("/** Is true when the page is visible. */")).toEqual(["Is"]);
+        expect(found("/** Called when the worker stops. */")).toEqual(["Called"]);
+        expect(found("/** Used by the worker. */")).toEqual(["Used"]);
+    });
+
+    it("examines each sentence of the summary and of @remarks", () => {
+        expect(found("/**\n * The monitor. Returns the value.\n * @remarks\n * Uses a timer.\n */")).toEqual(["Returns", "Uses"]);
+    });
+
+    it("does not report a sentence with a subject, a question or a plural noun subject", () => {
+        expect(found("/** This function returns the value. */")).toEqual([]);
+        expect(found("/** Is it visible? */")).toEqual([]);
+        expect(found("/** Samples at or above this value wait for evidence. */")).toEqual([]);
+        expect(found("/** Values are clamped. */")).toEqual([]);
+        expect(found("/** Samples per calibration round. */")).toEqual([]);
+        expect(found("/** Tags whose content is code. */")).toEqual([]);
+        expect(found("/** Monitors ask whether the window overlaps. */")).toEqual([]);
+        expect(found("/** Handles returned by the setup. */")).toEqual([]);
+        expect(found("/** Settings for the run. */")).toEqual([]);
+        expect(found("/** Based on the frame time, the monitor reports lag. */")).toEqual([]);
+        expect(found("/** Status of the monitor. */")).toEqual([]);
+        expect(found("/** `stop()` releases the timers. */")).toEqual([]);
+    });
+
+    it("does not examine block tag text, list items or Markdown files", () => {
+        expect(found("/**\n * The function.\n * @returns Returns the value.\n * - Returns a list item.\n */")).toEqual([]);
+        expect(linter.lintText("Returns the value.", "doc.md").filter((finding) => finding.ruleId === "missing-subject")).toEqual([]);
+    });
+});