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

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

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