@mark1russell7/ste-lint 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig } from "../config.js";
+import { Linter } from "../lint.js";
+
+const linter = new Linter(resolveConfig({}, { root : "/" }));
+const lint = (text : string, path : string = "doc.md") => linter.lintText(text, path).filter((finding) => finding.ruleId === "modal-verb");
+const found = (text : string) : string[] => lint(text).map((finding) => text.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("modal-verb", () => {
+    it("reports the modal verbs that are not approved, without case", () => {
+        expect(found("You should stop. It may fail. It might fail. It would fail. You shall stop.")).toEqual(["should", "may", "might", "would", "shall"]);
+        expect(found("SHOULD and Should are the same.")).toEqual(["SHOULD", "Should"]);
+        expect(found("It shouldn't fail and wouldn't stop.")).toEqual(["shouldn't", "wouldn't"]);
+    });
+
+    it("reports the modal phrases with \"to\"", () => {
+        expect(found("You have to stop. It has to stop. You need to stop. It needs to stop. You ought to stop.")).toEqual([
+            "have to", "has to", "need to", "needs to", "ought to",
+        ]);
+    });
+
+    it("gives the approved alternative in the message", () => {
+        expect(lint("You should stop.")[0]!.message).toContain("\"must\"");
+        expect(lint("It may fail.")[0]!.message).toContain("\"can\"");
+        expect(lint("You need to stop.")[0]!.message).toContain("imperative");
+    });
+
+    it("uses word boundaries", () => {
+        expect(found("The shoulder, mayor, nightmare and wouldbe words are fine.")).toEqual([]);
+    });
+
+    it("does not report the approved modal verbs, the month May or a noun", () => {
+        expect(found("You can stop. You must stop. It will stop. It could stop.")).toEqual([]);
+        expect(found("The release is in May 2026. It came on 3 May. Since May, it works.")).toEqual([]);
+        expect(found("The need to stop is clear. I have two tools. It has tools.")).toEqual([]);
+    });
+
+    it("does not report modal verbs in code spans or in quoted text", () => {
+        expect(found("The `should` assertion and the word \"may\" are quoted.")).toEqual([]);
+    });
+
+    it("examines headings and table cells", () => {
+        expect(lint("# You should read this\n\n| a |\n| --- |\n| It may stop. |")).toHaveLength(2);
+    });
+});

package/src/rules/modal-verb.ts

@@ -0,0 +1,72 @@
+import { isClauseStart } from "../text/grammar.js";
+import { isNumber, isWord, type Token } from "../text/tokens.js";
+import { DETERMINERS } from "../text/words.js";
+import { forEachToken, surface, tokenRange, type Rule } from "./rule.js";
+
+// These tables are maps, not object literals, so a word such as "constructor" does not find an Object property.
+const SINGLE : ReadonlyMap<string, string> = new Map([
+    ["should", "Write \"must\" for an obligation, or \"if\" for a condition (\"If X occurs, ...\")."],
+    ["shouldn", "Write \"must not\" for an obligation."],
+    ["may", "Write \"can\" for a possibility or a permission, or \"possibly\"."],
+    ["might", "Write \"can\" or \"possibly\"."],
+    ["would", "Write \"can\", or use a simple tense (\"is\", \"gives\")."],
+    ["wouldn", "Write \"cannot\", or use a simple tense (\"is not\")."],
+    ["shall", "Write \"must\"."],
+]);
+
+const CONTRACTIONS : ReadonlyMap<string, string> = new Map([
+    ["shouldn't", "shouldn"],
+    ["wouldn't", "wouldn"],
+    ["mightn't", "might"],
+    ["shan't", "shall"],
+    ["mayn't", "may"],
+]);
+
+const IMPERATIVE_HELP = "Write the instruction in the imperative (\"Do X\"), or use \"must\".";
+const NECESSARY_HELP = "Write the instruction in the imperative (\"Do X\"), or use \"must\" or \"it is necessary to\".";
+
+const WITH_TO : ReadonlyMap<string, string> = new Map([
+    ["ought", "Write \"must\"."],
+    ["have", IMPERATIVE_HELP],
+    ["has", IMPERATIVE_HELP],
+    ["had", "Use the simple past tense of the verb, or \"must\"."],
+    ["having", "Rewrite the sentence with \"must\" or with the imperative."],
+    ["need", NECESSARY_HELP],
+    ["needs", NECESSARY_HELP],
+    ["needed", "Write \"it was necessary to\", or rewrite the sentence."],
+]);
+
+/** True when "May" is the month: "May 2026", "3 May". */
+function isMonth(tokens : readonly Token[], index : number) : boolean {
+    const token = tokens[index]!;
+    if (token.text !== "May") return false;
+    return !isClauseStart(tokens, index) || isNumber(tokens[index + 1]) || isNumber(tokens[index - 1]);
+}
+
+export const modalVerb : Rule = {
+    id : "modal-verb",
+    description : "Find modal verbs that are not approved: should, may, might, would, shall, ought to, have to, need to.",
+    ste : "3.1, 3.4, 5.3",
+    defaultSeverity : "error",
+    scope : "word",
+    check(unit, context) {
+        forEachToken(unit, (tokens, i) => {
+            const token = tokens[i]!;
+            if (!isWord(token)) return;
+            const key = CONTRACTIONS.get(token.lower) ?? token.lower;
+            const help = SINGLE.get(key);
+            if (help !== undefined) {
+                if (key === "may" && isMonth(tokens, i)) return;
+                context.report({ ...tokenRange(tokens, i, i + 1), message : `Do not use the modal verb "${token.text}". ${help}` });
+                return;
+            }
+            const withTo = WITH_TO.get(key);
+            const next = tokens[i + 1];
+            if (withTo === undefined || !isWord(next) || next.lower !== "to") return;
+            const previous = tokens[i - 1];
+            // "the need to ..." is a noun phrase, not a modal verb.
+            if (key.startsWith("need") && isWord(previous) && DETERMINERS.has(previous.lower)) return;
+            context.report({ ...tokenRange(tokens, i, i + 2), message : `Do not use "${surface(tokens, i, i + 2)}". ${withTo}` });
+        });
+    },
+};

package/src/rules/noun-cluster.test.ts

@@ -0,0 +1,49 @@
+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 lint = (text : string, file : SteConfigFile = {}) =>
+    new Linter(resolveConfig(file, { root : "/" })).lintText(text, "doc.md").filter((finding) => finding.ruleId === "noun-cluster");
+const found = (text : string, file : SteConfigFile = {}) : string[] => lint(text, file).map((finding) => text.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("noun-cluster", () => {
+    it("reports more than 3 known nouns in sequence", () => {
+        expect(found("Read the browser memory usage threshold value now.")).toEqual(["browser memory usage threshold value"]);
+        const findings = lint("Read the browser memory usage threshold now.");
+        expect(findings[0]!.severity).toBe("warning");
+        expect(findings[0]!.message).toContain("4 nouns");
+    });
+
+    it("accepts 3 nouns, and a preposition or an article stops the group", () => {
+        expect(found("Read the memory usage threshold. Read the threshold of the memory usage value.")).toEqual([]);
+    });
+
+    it("counts glossary nouns, abbreviations and code, and a multi-word technical noun as one noun", () => {
+        expect(found("The heartbeat `seq` API timer value is late.", { technicalNouns : ["heartbeat"] })).toEqual(["heartbeat `seq` API timer value"]);
+        expect(found("The memory usage threshold value is low.")).toEqual(["memory usage threshold value"]);
+        expect(found("The memory usage threshold value is low.", { technicalNouns : ["memory usage"] })).toEqual([]);
+        expect(found("The memory usage threshold value unit is low.", { technicalNouns : ["memory usage"] })).toEqual(["memory usage threshold value unit"]);
+    });
+
+    it("stops a group after a plural noun", () => {
+        expect(found("The browser timers memory usage threshold.")).toEqual([]);
+        expect(found("The browser memory usage thresholds are low.")).toEqual(["browser memory usage thresholds"]);
+    });
+
+    it("does not count words that are frequently verbs", () => {
+        expect(found("The page queue update process value is fine.")).toEqual([]);
+    });
+
+    it("uses the nouns of the dictionary", () => {
+        const config = resolveConfig({}, { root : "/" });
+        const dictionary = parseDictionary({ entries : [{ word : "valve", pos : "noun" }, { word : "pump", pos : "noun" }] }, "d.json");
+        const linter = new Linter(config, buildLexicon(config, dictionary));
+        expect(linter.lintText("The pump valve memory usage is low.", "doc.md").filter((finding) => finding.ruleId === "noun-cluster")).toHaveLength(1);
+    });
+
+    it("uses the limit of the configuration", () => {
+        expect(found("The memory usage threshold.", { limits : { nounClusterNouns : 2 } })).toEqual(["memory usage threshold"]);
+    });
+});

package/src/rules/noun-cluster.ts

@@ -0,0 +1,82 @@
+import type { Lexicon } from "../lexicon.js";
+import { isAbbreviation, isWord, type Token } from "../text/tokens.js";
+import { surface, tokenRange, type Rule } from "./rule.js";
+
+type NounUnit = {
+    /** The number of tokens in the noun. A multi-word technical noun is one noun. */
+    readonly length : number;
+    readonly plural : boolean;
+};
+
+function singular(word : string) : string[] {
+    const forms : string[] = [];
+    if (word.endsWith("ies")) forms.push(word.slice(0, -3) + "y");
+    if (word.endsWith("es")) forms.push(word.slice(0, -2));
+    if (word.endsWith("s")) forms.push(word.slice(0, -1));
+    return forms;
+}
+
+/** The noun at `tokens[index]`, or null when the token is not a known noun. */
+function nounAt(tokens : readonly Token[], index : number, lexicon : Lexicon) : NounUnit | null {
+    const token = tokens[index];
+    if (token === undefined) return null;
+    if (token.kind === "code") {
+        const kind = token.placeholder?.kind;
+        return kind === "code" || kind === "link" ? { length : 1, plural : false } : null;
+    }
+    if (!isWord(token)) return null;
+    const phrase = lexicon.technicalNounPhrases.longestMatch(tokens, index);
+    if (phrase > 1) return { length : phrase, plural : tokens[index + phrase - 1]!.lower.endsWith("s") };
+    if (isAbbreviation(token)) return { length : 1, plural : /[a-z]s$/.test(token.text) };
+    if (lexicon.nouns.has(token.lower)) return { length : 1, plural : false };
+    if (singular(token.lower).some((form) => lexicon.nouns.has(form))) return { length : 1, plural : true };
+    return null;
+}
+
+/**
+ * The rule counts a group of nouns in sequence, with no article,
+ * preposition or punctuation between them. Only these known nouns count:
+ *
+ * - Technical nouns and proper nouns from the glossary
+ * - Nouns from the dictionary
+ * - A built-in list of common software nouns
+ * - Abbreviations and code.
+ *
+ * Only the last noun of a group can be plural. Without a part-of-speech
+ * tagger, the rule cannot know if other words are nouns, so it does not
+ * count them. Thus it misses some clusters, but it seldom reports a false
+ * one.
+ */
+export const nounCluster : Rule = {
+    id : "noun-cluster",
+    description : "Find groups of more than 3 nouns in sequence (noun clusters).",
+    ste : "2.1",
+    defaultSeverity : "warning",
+    scope : "word",
+    check(unit, context) {
+        const max = context.config.limits.nounClusterNouns;
+        for (const sentence of unit.sentences) {
+            const tokens = sentence.tokens;
+            let i = 0;
+            while (i < tokens.length) {
+                let count = 0;
+                let j = i;
+                let plural = false;
+                while (!plural) {
+                    const noun = nounAt(tokens, j, context.lexicon);
+                    if (noun === null) break;
+                    count++;
+                    j += noun.length;
+                    plural = noun.plural;
+                }
+                if (count > max) {
+                    context.report({
+                        ...tokenRange(tokens, i, j),
+                        message : `"${surface(tokens, i, j)}" has ${count} nouns in sequence. Use no more than ${max}. Use a preposition to divide the group, for example "the interval of the heartbeat" instead of "heartbeat interval".`,
+                    });
+                }
+                i = count > 0 ? j : i + 1;
+            }
+        }
+    },
+};

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

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig, type SteConfigFile } from "../config.js";
+import { Linter } from "../lint.js";
+
+const lint = (text : string, file : SteConfigFile = {}) =>
+    new Linter(resolveConfig(file, { root : "/" })).lintText(text, "doc.md").filter((finding) => finding.ruleId === "paragraph-length");
+
+const paragraph = (count : number) : string => Array.from({ length : count }, (_, i) => `Sentence ${i + 1} is short.`).join(" ");
+
+describe("paragraph-length", () => {
+    it("reports a paragraph of more than 6 sentences as a warning", () => {
+        const findings = lint(paragraph(7));
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ severity : "warning", line : 1, column : 1 });
+        expect(findings[0]!.message).toContain("7 sentences");
+    });
+
+    it("accepts 6 sentences, and counts each paragraph separately", () => {
+        expect(lint(paragraph(6))).toEqual([]);
+        expect(lint(`${paragraph(4)}\n\n${paragraph(4)}`)).toEqual([]);
+    });
+
+    it("does not count an abbreviation as the end of a sentence", () => {
+        expect(lint("One, e.g. two. Three. Four. Five. Six. Seven, i.e. eight.")).toEqual([]);
+    });
+
+    it("uses the limit of the configuration", () => {
+        expect(lint(paragraph(3), { limits : { paragraphSentences : 2 } })).toHaveLength(1);
+    });
+});

package/src/rules/paragraph-length.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "./rule.js";
+
+export const paragraphLength : Rule = {
+    id : "paragraph-length",
+    description : "A paragraph can have no more than 6 sentences.",
+    ste : "6.6",
+    defaultSeverity : "warning",
+    scope : "paragraph",
+    check(unit, context) {
+        const limit = context.config.limits.paragraphSentences;
+        const count = unit.sentences.length;
+        if (count <= limit) return;
+        context.report({
+            start : unit.start,
+            end : unit.end,
+            message : `This paragraph has ${count} sentences. Use no more than ${limit} sentences in a paragraph. Divide it into two paragraphs, each with one topic.`,
+        });
+    },
+};

package/src/rules/passive-instruction.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { resolveConfig } from "../config.js";
+import { Linter } from "../lint.js";
+
+const linter = new Linter(resolveConfig({}, { root : "/" }));
+const lint = (text : string, path : string = "doc.md") => linter.lintText(text, path).filter((finding) => finding.ruleId === "passive-instruction");
+const found = (text : string) : string[] => lint(text).map((finding) => text.split("\n")[finding.line - 1]!.slice(finding.column - 1, finding.endColumn - 1));
+
+describe("passive-instruction", () => {
+    it("reports an obligation in the passive voice in any sentence", () => {
+        expect(found("The token must be set before the start. The value has to be written first. The file should be removed.")).toEqual([
+            "must be set", "has to be written", "should be removed",
+        ]);
+        const findings = lint("The token must be set first.");
+        expect(findings[0]!.severity).toBe("warning");
+        expect(findings[0]!.message).toContain("imperative");
+    });
+
+    it("reports the passive voice in an imperative sentence", () => {
+        expect(found("Run the build, which is triggered by CI.")).toEqual(["is triggered"]);
+    });
+
+    it("reports the passive voice in a step of an ordered list", () => {
+        expect(found("1. The cache is cleared by the script.\n2. The tests are started.")).toEqual(["is cleared", "are started"]);
+    });
+
+    it("does not report a participle in a condition, which shows a state", () => {
+        expect(found("Make sure that the server is started. Wait until the build is finished. If the file is deleted, start again.")).toEqual([]);
+    });
+
+    it("does not report the passive voice in a description", () => {
+        expect(found("The file is created by the build. Samples are discarded when the page is hidden. It can be used.")).toEqual([]);
+    });
+
+    it("does not report \"be\" with an adjective", () => {
+        expect(found("Be careful. Make sure that the value is positive.")).toEqual([]);
+    });
+});

package/src/rules/passive-instruction.ts

@@ -0,0 +1,37 @@
+import { findPassives } from "../text/grammar.js";
+import { surface, tokenRange, type Rule } from "./rule.js";
+
+/**
+ * The rule examines these constructions:
+ *
+ * - An obligation in the passive voice ("must be set", "has to be called",
+ *   "needs to be installed") in any sentence. This is an instruction in a
+ *   passive form.
+ * - Any passive ("is cleared", "are triggered by CI") in a procedural
+ *   sentence: an imperative sentence or an item of an ordered list. A
+ *   participle after "be" in a condition clause ("if the file is deleted",
+ *   "make sure that the server is started") shows a state, so the rule
+ *   ignores it.
+ */
+export const passiveInstruction : Rule = {
+    id : "passive-instruction",
+    description : "Find the passive voice in instructions. An instruction uses the active voice and the imperative.",
+    ste : "3.4, 3.6, 5.3",
+    defaultSeverity : "warning",
+    scope : "sentence",
+    check(unit, context) {
+        for (const sentence of unit.sentences) {
+            const procedural = sentence.instruction || unit.list?.ordered === true;
+            for (const passive of findPassives(sentence.tokens)) {
+                if (!passive.obligation && !(procedural && !passive.inCondition)) continue;
+                const from = passive.start;
+                const to = passive.participle + 1;
+                const phrase = surface(sentence.tokens, from, to);
+                const message = passive.obligation
+                    ? `"${phrase}" is an instruction in the passive voice. Write the instruction in the imperative, for example "Set the value before you start the monitor."`
+                    : `"${phrase}" is in the passive voice. In an instruction, use the active voice: write the imperative, or tell who or what does the action.`;
+                context.report({ ...tokenRange(sentence.tokens, from, to), message });
+            }
+        }
+    },
+};

package/src/rules/pronouns.test.ts

@@ -0,0 +1,38 @@
+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) => linter.lintText(text, "doc.md").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("gendered-pronoun", () => {
+    it("reports gendered pronouns as errors", () => {
+        expect(found("gendered-pronoun", "He opens it. She saves his file. Give her the key, and him the code. It is hers. He did it himself, and she herself.")).toEqual([
+            "He", "She", "his", "her", "him", "hers", "He", "himself", "she", "herself",
+        ]);
+        const findings = lint("gendered-pronoun", "The user saves his work.");
+        expect(findings[0]!.severity).toBe("error");
+        expect(findings[0]!.message).toContain("\"they\"");
+    });
+
+    it("does not report other words, code or quoted text", () => {
+        expect(found("gendered-pronoun", "The theme, the shell and `he` and \"she\" are fine. They save their work.")).toEqual([]);
+    });
+});
+
+describe("first-person", () => {
+    it("reports I, me, my, our and us as warnings", () => {
+        expect(found("first-person", "I run it. Give me the file. My file. Our tool. Tell us. Let's go. It is ours.")).toEqual([
+            "I", "me", "My", "Our", "us", "Let's", "ours",
+        ]);
+        const findings = lint("first-person", "Our tool works.");
+        expect(findings[0]!.severity).toBe("warning");
+        expect(findings[0]!.message).toContain("\"we\"");
+    });
+
+    it("does not report \"we\", the abbreviation US, or I/O", () => {
+        expect(found("first-person", "We release the tool in the US. The I/O is fast. You can use it.")).toEqual([]);
+    });
+});

package/src/rules/pronouns.ts

@@ -0,0 +1,54 @@
+import { isWord } from "../text/tokens.js";
+import { forEachToken, tokenRange, type Rule } from "./rule.js";
+
+const GENDERED = new Set([
+    "he", "she", "his", "her", "him", "hers", "himself", "herself",
+    "he's", "she's", "he'd", "she'd", "he'll", "she'll",
+]);
+
+export const genderedPronoun : Rule = {
+    id : "gendered-pronoun",
+    description : "Find gendered pronouns: he, she, his, her, him, hers, himself and herself.",
+    ste : "GR-3, GR-7",
+    defaultSeverity : "error",
+    scope : "word",
+    check(unit, context) {
+        forEachToken(unit, (tokens, i) => {
+            const token = tokens[i]!;
+            if (!isWord(token) || !GENDERED.has(token.lower)) return;
+            context.report({
+                ...tokenRange(tokens, i, i + 1),
+                message : `Do not use the gendered pronoun "${token.text}". Write "they" or "it", or write the noun again.`,
+            });
+        });
+    },
+};
+
+const SINGULAR = new Set(["i", "me", "my", "mine", "myself", "i'm", "i've", "i'll", "i'd"]);
+const PLURAL = new Set(["our", "ours", "ourselves"]);
+
+export const firstPerson : Rule = {
+    id : "first-person",
+    description : "Find first-person pronouns other than \"we\": I, me, my, our and us. Use \"we\" only for the organization that writes the text.",
+    ste : "GR-3",
+    defaultSeverity : "warning",
+    scope : "word",
+    check(unit, context) {
+        forEachToken(unit, (tokens, i) => {
+            const token = tokens[i]!;
+            if (!isWord(token)) return;
+            const lower = token.lower;
+            let message : string | null = null;
+            if (SINGULAR.has(lower)) {
+                message = `Do not use "${token.text}". Write "you" for the reader, or "we" for the organization that writes the text.`;
+            } else if (PLURAL.has(lower)) {
+                message = `Do not use "${token.text}". Write the name of the project or the product, or rewrite the sentence with "we" as the subject.`;
+            } else if (lower === "us" && token.text !== "US") {
+                message = "Do not use \"us\". Rewrite the sentence with \"we\" as the subject.";
+            } else if (lower === "let's") {
+                message = "Do not use \"let's\". Write the instruction in the imperative.";
+            }
+            if (message !== null) context.report({ ...tokenRange(tokens, i, i + 1), message });
+        });
+    },
+};

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.",
+            });
+        });
+    },
+};