@mark1russell7/ste-lint 0.0.0-stage → 0.1.2

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

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

package/src/rules/sentence-length.ts

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

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

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

package/src/rules/unknown-word.ts

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

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

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

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

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

package/src/rules/word-list.ts

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

package/src/run-cli.test.ts

@@ -0,0 +1,189 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Linter } from "./lint.js";
+import { parseArgs, runCli, UsageError, USAGE } from "./run-cli.js";
+
+let root : string;
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "ste-cli-"));
+    writeFileSync(join(root, "ste.config.json"), JSON.stringify({ include : ["README.md", "docs/**/*.md", "src/**/*.ts"] }));
+    mkdirSync(join(root, "docs"));
+    mkdirSync(join(root, "src"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive : true, force : true });
+});
+
+function run(argv : string[], env : Record<string, string | undefined> = {}) : { code : number; stdout : string; stderr : string } {
+    let stdout = "";
+    let stderr = "";
+    const code = runCli(argv, {
+        cwd : root,
+        env,
+        stdout : (text) => { stdout += text; },
+        stderr : (text) => { stderr += text; },
+    });
+    return { code, stdout, stderr };
+}
+
+describe("parseArgs", () => {
+    it("reads the options and the patterns", () => {
+        expect(parseArgs(["--format", "json", "--max-warnings=3", "--config", "c.json", "a.md", "docs/**"])).toEqual({
+            patterns : ["a.md", "docs/**"],
+            format : "json",
+            maxWarnings : 3,
+            configPath : "c.json",
+            help : false,
+        });
+        expect(parseArgs(["-h"]).help).toBe(true);
+        expect(parseArgs(["--format=text", "-"]).patterns).toEqual(["-"]);
+    });
+
+    it("rejects incorrect options", () => {
+        expect(() => parseArgs(["--format", "xml"])).toThrow(UsageError);
+        expect(() => parseArgs(["--max-warnings", "-1"])).toThrow("integer");
+        expect(() => parseArgs(["--max-warnings", "many"])).toThrow("integer");
+        expect(() => parseArgs(["--config"])).toThrow("needs a value");
+        expect(() => parseArgs(["--nope"])).toThrow("not a known option");
+    });
+});
+
+describe("runCli", () => {
+    it("shows the help", () => {
+        const result = run(["--help"]);
+        expect(result.code).toBe(0);
+        expect(result.stdout).toBe(USAGE);
+        expect(USAGE).toContain("automated approximation");
+    });
+
+    it("exits with 0 when there are no problems", () => {
+        writeFileSync(join(root, "README.md"), "The monitor measures lag.\n");
+        const result = run([]);
+        expect(result.code).toBe(0);
+        expect(result.stdout).toContain("No problems found in 1 file.");
+    });
+
+    it("exits with 1 when there are errors, and lints the default patterns of the configuration", () => {
+        writeFileSync(join(root, "README.md"), "You should stop.\n");
+        writeFileSync(join(root, "docs", "guide.md"), "Text; more text.\n");
+        writeFileSync(join(root, "src", "a.ts"), "/** Returns the value. */\nexport const a = 1;\n");
+        writeFileSync(join(root, "notes.txt"), "You should stop.\n");
+        const result = run([]);
+        expect(result.code).toBe(1);
+        expect(result.stdout).toContain("README.md\n  1:5");
+        expect(result.stdout).toContain("docs/guide.md");
+        expect(result.stdout).toContain("src/a.ts");
+        expect(result.stdout).not.toContain("notes.txt");
+    });
+
+    it("writes JSON", () => {
+        writeFileSync(join(root, "README.md"), "Our tool.\n");
+        const result = run(["--format", "json"]);
+        expect(result.code).toBe(0);
+        const json = JSON.parse(result.stdout) as { summary : { warnings : number }; findings : Array<{ file : string; ruleId : string }> };
+        expect(json.summary.warnings).toBe(1);
+        expect(json.findings[0]).toMatchObject({ file : "README.md", ruleId : "first-person" });
+    });
+
+    it("exits with 1 when there are more warnings than --max-warnings", () => {
+        writeFileSync(join(root, "README.md"), "Our tool. Our page.\n");
+        expect(run(["--max-warnings", "2"]).code).toBe(0);
+        const result = run(["--max-warnings", "1"]);
+        expect(result.code).toBe(1);
+        expect(result.stderr).toContain("2 warnings. The maximum is 1.");
+        expect(run(["--max-warnings", "1", "--format", "json"]).stderr).toBe("");
+    });
+
+    it("lints the patterns of the command line, relative to the working directory", () => {
+        writeFileSync(join(root, "other.md"), "You should stop.\n");
+        writeFileSync(join(root, "README.md"), "You should stop.\n");
+        const result = run(["other.md"]);
+        expect(result.stdout).toContain("other.md");
+        expect(result.stdout).not.toContain("README.md");
+    });
+
+    it("applies the ignore patterns of the configuration relative to its directory, also from a subdirectory", () => {
+        writeFileSync(join(root, "ste.config.json"), JSON.stringify({ include : ["docs/**/*.md"], ignore : ["docs/legacy/**"] }));
+        mkdirSync(join(root, "docs", "legacy"));
+        writeFileSync(join(root, "docs", "legacy", "old.md"), "You should stop.\n");
+        writeFileSync(join(root, "docs", "guide.md"), "You should stop.\n");
+        let stdout = "";
+        const code = runCli(["**/*.md"], { cwd : join(root, "docs"), env : {}, stdout : (text) => { stdout += text; }, stderr : () => {} });
+        expect(code).toBe(1);
+        expect(stdout).toContain("guide.md");
+        expect(stdout).not.toContain("old.md");
+    });
+
+    it("exits with 2 when it cannot read a directory", () => {
+        writeFileSync(join(root, "README.md"), "Text.\n");
+        // The walk reads README.md as a directory, and readdirSync fails with ENOTDIR
+        const result = run(["README.md/**/*.md"]);
+        expect(result.code).toBe(2);
+        expect(result.stderr).toMatch(/^ste-lint: cannot read the files: .*ENOTDIR/);
+    });
+
+    it("exits with 2 when the patterns match no files, and with 0 when the default patterns match no files", () => {
+        expect(run(["missing/*.md"])).toMatchObject({ code : 2, stderr : "ste-lint: no files match the patterns.\n" });
+        expect(run([])).toMatchObject({ code : 0, stderr : "ste-lint: no files to examine.\n" });
+    });
+
+    it("exits with 2 for an incorrect command line or configuration", () => {
+        expect(run(["--format", "xml"]).code).toBe(2);
+        writeFileSync(join(root, "ste.config.json"), JSON.stringify({ rules : { nope : "error" } }));
+        const result = run([]);
+        expect(result.code).toBe(2);
+        expect(result.stderr).toContain("is not a known rule");
+    });
+
+    it("uses a dictionary from STE_DICTIONARY", () => {
+        writeFileSync(join(root, "README.md"), "The valve opens the zorblat.\n");
+        writeFileSync(join(root, "dictionary.json"), JSON.stringify(["the", "valve", "opens"]));
+        const result = run(["--format", "json"], { STE_DICTIONARY : "dictionary.json" });
+        const json = JSON.parse(result.stdout) as { findings : Array<{ ruleId : string; message : string }> };
+        expect(json.findings.map((finding) => finding.ruleId)).toEqual(["unknown-word"]);
+        expect(json.findings[0]!.message).toContain("\"zorblat\"");
+    });
+
+    it("tells the user when the dictionary file does not exist, and continues without it", () => {
+        writeFileSync(join(root, "README.md"), "The valve opens the zorblat.\n");
+        const result = run([], { STE_DICTIONARY : "missing.json" });
+        expect(result.code).toBe(0);
+        expect(result.stderr).toContain("does not exist. The unknown-word rule is off.");
+        writeFileSync(join(root, "ste.config.json"), JSON.stringify({ include : ["README.md"], dictionaryPath : "missing.json" }));
+        expect(run([]).stderr).toContain("(from dictionaryPath)");
+    });
+
+    it("exits with 2 for a dictionary file that is not valid", () => {
+        writeFileSync(join(root, "README.md"), "Text.\n");
+        writeFileSync(join(root, "dictionary.json"), "{");
+        expect(run([], { STE_DICTIONARY : "dictionary.json" }).code).toBe(2);
+    });
+
+    it("exits with 2 when it cannot examine a file, and examines the other files", () => {
+        writeFileSync(join(root, "README.md"), "You should stop.\n");
+        writeFileSync(join(root, "docs", "guide.md"), "Text.\n");
+        const original = Linter.prototype.lintFile;
+        const spy = vi.spyOn(Linter.prototype, "lintFile").mockImplementation(function (this : Linter, path : string, shown? : string) {
+            if (path.endsWith("guide.md")) throw new Error("cannot read");
+            return original.call(this, path, shown);
+        });
+        try {
+            const result = run([]);
+            expect(result.code).toBe(2);
+            expect(result.stderr).toContain("cannot examine");
+            expect(result.stderr).toContain("cannot read");
+            expect(result.stdout).toContain("README.md");
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it("does not catch errors that are not configuration errors", () => {
+        const env = new Proxy({}, { get : () => { throw new TypeError("unexpected"); } });
+        expect(() => runCli([], { cwd : root, env, stdout : () => {}, stderr : () => {} })).toThrow("unexpected");
+    });
+});