@mark1russell7/ste-lint 0.0.0-stage → 0.1.2

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,30 @@
+/**
+ * The linter for files: the engine of `engine.ts`, with the extractor of
+ * TypeScript doc comments and the file system.
+ */
+
+import { readFileSync } from "node:fs";
+import type { ResolvedConfig } from "./config.js";
+import { ProseLinter } from "./engine.js";
+import type { Lexicon } from "./lexicon.js";
+import { extractCode } from "./source/code.js";
+import type { Finding } from "./types.js";
+
+export { fileKind, type FileKind } from "./engine.js";
+
+/** A linter for one configuration. It makes the lexicon and the word list matcher one time. */
+export class Linter extends ProseLinter {
+    constructor(config : ResolvedConfig, lexicon? : Lexicon) {
+        super(config, lexicon, { extractCode });
+    }
+
+    /** 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);
+    }
+}
+
+/** 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([]);
+    });
+});

package/src/rules/missing-subject.ts

@@ -0,0 +1,129 @@
+import type { Lexicon } from "../lexicon.js";
+import { isParticiple, nextCounted, startsObject } from "../text/grammar.js";
+import { isCapitalized, isCounted, isWord, type Token } from "../text/tokens.js";
+import { BE_FORMS, CONJUNCTIONS, DETERMINERS, HAVE_FORMS, MODALS, PREPOSITIONS, SUBJECT_PRONOUNS } from "../text/words.js";
+import { tokenRange, type Rule } from "./rule.js";
+
+/** Auxiliary verbs that start a sentence without a subject: "Is true when ...", "Can be null.". */
+const AUXILIARY_STARTS = new Set(["is", "are", "was", "were", "has", "have", "had", "does", "can", "cannot", "must", "will", "should", "may", "might", "would", "could"]);
+
+/** Words that end in -s but are not verbs. */
+const NOT_VERBS = new Set([
+    "this", "its", "always", "perhaps", "sometimes", "whereas", "unless", "plus", "thus", "yes", "less", "across",
+    "towards", "afterwards", "besides", "nevertheless", "regardless", "various", "numerous", "previous", "analysis",
+    "basis", "bias", "canvas", "status", "series", "species", "atlas", "alias", "chaos", "corpus", "focus", "bonus",
+]);
+
+/** Words after a participle that show a missing subject: "Called when ...", "Used by ...". */
+const AFTER_PARTICIPLE = new Set([...PREPOSITIONS, "when", "if", "once", "only", "while", "as", "whenever", "unless"]);
+
+function stems(word : string) : string[] {
+    const forms = [word.slice(0, -1)];
+    if (word.endsWith("es")) forms.push(word.slice(0, -2));
+    if (word.endsWith("ies")) forms.push(word.slice(0, -3) + "y");
+    return forms;
+}
+
+/** True when a comma comes later and a subject comes after it: "Based on X, the monitor ...". */
+function hasLaterSubject(tokens : readonly Token[], from : number) : boolean {
+    for (let i = from; i < tokens.length; i++) {
+        const token = tokens[i]!;
+        if (token.kind !== "punct" || token.text !== ",") continue;
+        const next = tokens[nextCounted(tokens, i + 1)];
+        if (next === undefined) return false;
+        return next.kind === "code" || isCapitalized(next) || (isWord(next) && (DETERMINERS.has(next.lower) || SUBJECT_PRONOUNS.has(next.lower)));
+    }
+    return false;
+}
+
+const PLURAL_AUXILIARIES = new Set(["are", "were", "have", "do", "don't", "aren't", "weren't", "can", "cannot", "must", "will"]);
+
+/**
+ * True when a verb for a plural subject comes later, after a noun:
+ * "Samples at or above this value wait ...", "Values below zero are ...".
+ * Then the first word is a plural noun, not a verb.
+ */
+function hasPluralVerbLater(tokens : readonly Token[], from : number, lexicon : Lexicon) : boolean {
+    for (let i = from; i < tokens.length; i++) {
+        const token = tokens[i]!;
+        const previous = tokens[i - 1];
+        if (!isWord(token) || !isWord(previous)) continue;
+        if (DETERMINERS.has(previous.lower) || PREPOSITIONS.has(previous.lower) || MODALS.has(previous.lower) || previous.lower === "not") continue;
+        if (PLURAL_AUXILIARIES.has(token.lower)) return true;
+        if (lexicon.verbs.has(token.lower) && !token.lower.endsWith("s")) return true;
+    }
+    return false;
+}
+
+/** Relative pronouns. A word before one of them is a noun: "Tags whose content ...". */
+const RELATIVE_PRONOUNS = new Set(["whose", "which", "who", "whom"]);
+
+/**
+ * True when the words after the first word show that the first word is a
+ * plural noun, not a verb. These words show a noun:
+ *
+ * - An auxiliary verb, a conjunction or "of": "Values are ...", "Values of ..."
+ * - "per" or a relative pronoun: "Samples per round", "Tags whose ..."
+ * - A base form of a verb: "Monitors ask ..."
+ * - A participle and a preposition: "Handles returned by ...".
+ */
+function isNounSubject(tokens : readonly Token[], index : number, lexicon : Lexicon) : boolean {
+    const next = tokens[index + 1];
+    if (!isWord(next)) return false;
+    const lower = next.lower;
+    if (BE_FORMS.has(lower) || MODALS.has(lower) || HAVE_FORMS.has(lower) || CONJUNCTIONS.has(lower) || lower === "of") return true;
+    if (lower === "per" || RELATIVE_PRONOUNS.has(lower)) return true;
+    const after = tokens[index + 2];
+    const objectAfter = after === undefined || after.kind === "punct" || startsObject(after) || (isWord(after) && PREPOSITIONS.has(after.lower));
+    if (lexicon.verbs.has(lower) && !lower.endsWith("s") && !DETERMINERS.has(lower) && objectAfter) return true;
+    return isParticiple(lower) && isWord(after) && PREPOSITIONS.has(after.lower);
+}
+
+/** The message when the sentence at `tokens` starts without a subject, or null. */
+export function missingSubject(tokens : readonly Token[], lexicon : Lexicon) : { index : number; message : string } | null {
+    const k = nextCounted(tokens, 0);
+    const first = tokens[k];
+    if (!isWord(first) || !isCapitalized(first)) return null;
+    const lower = first.lower;
+    const next = tokens[k + 1];
+    const last = [...tokens].reverse().find((token) => token.kind === "punct");
+    if (AUXILIARY_STARTS.has(lower)) {
+        if (last?.text === "?") return null;
+        return { index : k, message : `This sentence has no subject. Write the subject before "${first.text}", for example "This value ${lower} ...".` };
+    }
+    if (/^[a-z]{3,}s$/.test(lower) && !/(ss|us|is|ous|ics|ness)$/.test(lower) && !NOT_VERBS.has(lower)) {
+        const knownVerb = stems(lower).some((stem) => lexicon.verbs.has(stem));
+        if (next?.text === "," || isNounSubject(tokens, k, lexicon)) return null;
+        if (!knownVerb && !startsObject(next)) return null;
+        if (isWord(next) && PREPOSITIONS.has(next.lower) && hasPluralVerbLater(tokens, k + 2, lexicon)) return null;
+        const example = lower === "returns" ? "This function gives ..." : `This function ${lower} ...`;
+        return { index : k, message : `"${first.text}" has no subject. Do not omit the subject. Write a full sentence, for example "${example}".` };
+    }
+    if (isParticiple(lower) && isWord(next) && AFTER_PARTICIPLE.has(next.lower) && !hasLaterSubject(tokens, k + 1)) {
+        return { index : k, message : `"${first.text}" starts a sentence that has no subject. Write a full sentence with a subject in the active voice, for example "The monitor uses this value when ...".` };
+    }
+    return null;
+}
+
+/**
+ * The rule examines the summary and the `@remarks` text of doc comments.
+ * For example, "Returns the value." and "Called when the page is hidden."
+ * omit the subject. Text after `@param` and `@returns`, and list items, can
+ * be fragments, so the rule does not examine them.
+ */
+export const missingSubjectRule : Rule = {
+    id : "missing-subject",
+    description : "Find doc comment sentences that have no subject, for example \"Returns the value.\".",
+    ste : "4.2",
+    defaultSeverity : "error",
+    scope : "sentence",
+    check(unit, context) {
+        if (unit.origin.source !== "tsdoc" || unit.origin.tsdocSection === "tag" || unit.list !== null) return;
+        for (const sentence of unit.sentences) {
+            if (!sentence.tokens.some(isCounted)) continue;
+            const found = missingSubject(sentence.tokens, context.lexicon);
+            if (found === null) continue;
+            context.report({ ...tokenRange(sentence.tokens, found.index, found.index + 1), message : found.message });
+        }
+    },
+};