@mark1russell7/ste-lint 0.0.0-stage → 0.1.2

package/dist/word-list.js

@@ -0,0 +1,90 @@
+/**
+ * The project word list: plain-language substitutions for the documentation
+ * of this repository. This list is the style guide of the project, written
+ * for it. It is not a copy of the ASD-STE100 dictionary. The local
+ * dictionary file (refer to `dictionary.ts`) does that job, and it is not
+ * part of the repository at any time.
+ *
+ * Each entry has the words or phrases to find, the words to write instead,
+ * and a severity. `ste.config.json` can add entries, change them, or set an
+ * entry to "off".
+ */
+function entry(input) {
+    return {
+        id: input.id ?? input.match[0],
+        match: input.match,
+        suggest: input.suggest ?? null,
+        note: input.note ?? null,
+        severity: input.severity ?? "error",
+        verbOnly: input.verbOnly ?? false,
+        context: input.context ?? null,
+    };
+}
+/** The default word list. */
+export const DEFAULT_WORD_LIST = [
+    // Long or formal words that have a short, common equivalent.
+    entry({ match: ["utilize", "utilizes", "utilized", "utilizing", "utilization", "utilise", "utilises", "utilised", "utilising"], suggest: "\"use\"" }),
+    entry({ match: ["initiate", "initiates", "initiated", "initiating"], suggest: "\"start\"" }),
+    entry({ match: ["ensure", "ensures", "ensured", "ensuring"], suggest: "\"make sure\"", note: "Write \"that\" after it: \"make sure that ...\"." }),
+    entry({ match: ["via"], suggest: "\"through\" or \"with\"" }),
+    entry({ match: ["leverage", "leverages", "leveraged", "leveraging"], suggest: "\"use\"" }),
+    entry({ match: ["facilitate", "facilitates", "facilitated", "facilitating"], suggest: "\"help\" or \"make ... easier\"" }),
+    entry({ match: ["commence", "commences", "commenced", "commencing"], suggest: "\"start\"" }),
+    entry({ match: ["terminate", "terminates", "terminated", "terminating"], suggest: "\"stop\"" }),
+    entry({ match: ["obtain", "obtains", "obtained", "obtaining"], suggest: "\"get\"" }),
+    entry({ match: ["assist", "assists", "assisted", "assisting"], suggest: "\"help\"" }),
+    entry({ match: ["modify", "modifies", "modified", "modifying"], suggest: "\"change\"" }),
+    entry({ match: ["indicate", "indicates", "indicated", "indicating"], suggest: "\"show\"" }),
+    entry({ match: ["demonstrate", "demonstrates", "demonstrated", "demonstrating"], suggest: "\"show\"" }),
+    entry({ match: ["perform", "performs", "performed", "performing"], suggest: "\"do\"" }),
+    entry({ match: ["attempt", "attempts", "attempted", "attempting"], suggest: "\"try\"" }),
+    entry({ match: ["numerous"], suggest: "\"many\", or give the number" }),
+    entry({ match: ["additional"], suggest: "\"more\"" }),
+    entry({ match: ["additionally"], suggest: "\"also\"" }),
+    entry({ match: ["regarding"], suggest: "\"about\"" }),
+    entry({ match: ["hence"], suggest: "\"thus\"" }),
+    // Phrases that have a shorter equivalent.
+    entry({ match: ["prior to"], suggest: "\"before\"" }),
+    entry({ match: ["in order to"], suggest: "\"to\"" }),
+    entry({ match: ["due to the fact that"], suggest: "\"because\"" }),
+    entry({ match: ["due to"], suggest: "\"because of\"" }),
+    entry({ match: ["in the event that"], suggest: "\"if\"" }),
+    entry({ match: ["at this point in time"], suggest: "\"at this time\"" }),
+    entry({ match: ["in an effort to"], suggest: "\"to\"" }),
+    entry({ match: ["for the purpose of"], suggest: "\"to\" or \"for\"" }),
+    entry({ match: ["with respect to", "with regard to"], suggest: "\"about\" or \"for\"" }),
+    entry({ match: ["as well as"], suggest: "\"and\"" }),
+    entry({ match: ["a number of"], suggest: "\"some\", or give the number" }),
+    entry({ match: ["is able to", "are able to", "be able to"], suggest: "\"can\"" }),
+    entry({ match: ["such as"], suggest: "\"for example\"" }),
+    entry({ match: ["follow these steps", "follow the steps"], suggest: "\"do these steps\" or \"do the steps\"" }),
+    // Connecting words.
+    entry({ match: ["however"], suggest: "\"but\"", note: "Start a new sentence with \"But\" if necessary." }),
+    entry({ match: ["therefore"], suggest: "\"thus\" or \"as a result\"" }),
+    entry({ match: ["whether or not", "whether"], suggest: "\"if\"" }),
+    // Verbs that have a simpler equivalent.
+    entry({ match: ["allow", "allows", "allowed", "allowing"], suggest: "\"let\" or \"lets\"", note: "For an adjective, write \"permitted\"." }),
+    entry({ match: ["require", "requires", "required", "requiring"], suggest: "\"necessary\"", note: "For example, write \"X is necessary for Y\", or use the imperative." }),
+    entry({ match: ["provided that"], suggest: "\"if\"" }),
+    entry({ match: ["provide", "provides", "provided", "providing"], suggest: "\"give\" or \"gives\"" }),
+    entry({ match: ["execute", "executes", "executed", "executing"], suggest: "\"do\", \"does\" or \"start\"" }),
+    entry({ match: ["create", "creates", "created", "creating"], suggest: "\"make\" or \"makes\"" }),
+    entry({ match: ["kill", "kills", "killed", "killing"], suggest: "\"stop\"" }),
+    entry({ id: "displays", match: ["displayed", "displaying"], suggest: "\"show\" or \"shows\"", severity: "warning" }),
+    entry({ id: "display", match: ["display", "displays"], suggest: "\"show\" or \"shows\"", severity: "warning", verbOnly: true }),
+    entry({ id: "returns", match: ["returns", "returned", "returning"], suggest: "\"gives\"", severity: "warning", note: "For a function, write \"This function gives ...\"." }),
+    entry({ id: "return", match: ["return"], suggest: "\"give\" or \"gives\"", severity: "warning", verbOnly: true }),
+    entry({ id: "call", match: ["call", "calls", "called", "calling"], suggest: "\"use\" or \"start\"", severity: "warning", verbOnly: true, note: "This applies when the verb means to start a function." }),
+    entry({ id: "ran", match: ["ran"], suggest: "\"started\" or \"operated\"", severity: "warning" }),
+    entry({ id: "run", match: ["run", "runs", "running"], suggest: "\"start\", \"starts\" or \"operates\"", severity: "warning", verbOnly: true }),
+    entry({ id: "see", match: ["see"], suggest: "\"refer to\"", severity: "warning", context: "reference" }),
+    // Words that do not add information.
+    entry({ match: ["simple", "simply", "easily"], severity: "warning", note: "The word tells the reader what to think. Tell the reader what to do." }),
+    entry({ match: ["just"], suggest: "\"only\"", severity: "warning", note: "Or remove the word." }),
+    entry({ match: ["basically", "obviously", "of course"], severity: "warning", note: "The word does not add information." }),
+    entry({ match: ["please"], severity: "warning", note: "Write the instruction in the imperative." }),
+    // Time and negation.
+    entry({ match: ["currently", "now"], suggest: "\"at this time\"", note: "Or remove the word if the time is clear." }),
+    entry({ match: ["never"], suggest: "\"do not\"", note: "For a description, write \"not ... at any time\"." }),
+];
+//# sourceMappingURL=word-list.js.map

package/dist/word-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"word-list.js","sourceRoot":"","sources":["../src/word-list.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,57 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/ste-lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.2",
+  "description": "A linter for the writing rules of ASD-STE100 Simplified Technical English in Markdown, MDX and TypeScript doc comments",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./code": {
+      "types": "./dist/source/code.d.ts",
+      "import": "./dist/source/code.js"
+    },
+    "./ste.config.schema.json": "./ste.config.schema.json"
+  },
+  "bin": {
+    "ste-lint": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "ste.config.schema.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mark1russell7/ste-lint.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@mark1russell7/cue": "^1.0.2",
+    "@types/node": "^26.6.4",
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -p tsconfig.test.json && pnpm --filter @ste-lint/site run typecheck",
+    "test": "vitest run",
+    "lint:ste": "tsx src/cli.ts"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "./run-cli.js";
+
+process.exitCode = runCli(process.argv.slice(2), {
+    cwd : process.cwd(),
+    env : process.env,
+    stdout : (text) => process.stdout.write(text),
+    stderr : (text) => process.stderr.write(text),
+});

package/src/config-core.ts

@@ -0,0 +1,258 @@
+/**
+ * The parts of the configuration that need no file system: the types of
+ * `ste.config.json`, the defaults, the validation and the word list merge.
+ * A browser can use this module.
+ */
+
+import { isRuleId, RULE_IDS, type RuleId, type RuleSetting, type Severity } from "./types.js";
+import { DEFAULT_WORD_LIST, type WordListEntry } from "./word-list.js";
+
+export const CONFIG_FILE_NAME = "ste.config.json";
+
+/** The environment variable that gives the path of the local dictionary. It has priority over `dictionaryPath`. */
+export const DICTIONARY_ENV = "STE_DICTIONARY";
+
+/** An entry of `wordList` in the configuration file. */
+export type WordListEntryConfig = {
+    /** The ID of a default entry to change. A new entry gets the first word of `match` as its ID. */
+    readonly id? : string;
+    readonly match? : string | readonly string[];
+    readonly suggest? : string | null;
+    readonly note? : string | null;
+    readonly severity? : RuleSetting;
+    readonly verbOnly? : boolean;
+};
+
+export type LimitsConfig = {
+    /** The maximum number of words in an instruction. Default: 20 (STE Rule 5.1). */
+    readonly instructionWords? : number;
+    /** The maximum number of words in a description. Default: 25 (STE Rule 6.3). */
+    readonly descriptionWords? : number;
+    /** The maximum number of sentences in a paragraph. Default: 6 (STE Rule 6.6). */
+    readonly paragraphSentences? : number;
+    /** The maximum number of nouns in a noun cluster. Default: 3 (STE Rule 2.1). */
+    readonly nounClusterNouns? : number;
+};
+
+/** The contents of `ste.config.json`. All properties are optional. */
+export type SteConfigFile = {
+    readonly $schema? : string;
+    readonly include? : readonly string[];
+    readonly ignore? : readonly string[];
+    readonly technicalNouns? : readonly string[];
+    readonly technicalVerbs? : readonly string[];
+    readonly properNouns? : readonly string[];
+    readonly allowedWords? : readonly string[];
+    readonly rules? : Readonly<Record<string, RuleSetting>>;
+    readonly wordList? : readonly WordListEntryConfig[];
+    readonly limits? : LimitsConfig;
+    readonly dictionaryPath? : string | null;
+};
+
+export type Limits = Required<LimitsConfig>;
+
+export type ResolvedConfig = {
+    /** The directory that `include` and `ignore` are relative to. */
+    readonly root : string;
+    /** The configuration file, or null when the linter uses the defaults. */
+    readonly configFile : string | null;
+    readonly include : readonly string[];
+    readonly ignore : readonly string[];
+    readonly technicalNouns : readonly string[];
+    readonly technicalVerbs : readonly string[];
+    readonly properNouns : readonly string[];
+    readonly allowedWords : readonly string[];
+    /** The rule settings from the configuration. A rule without a setting uses its default severity. */
+    readonly rules : Readonly<Partial<Record<RuleId, RuleSetting>>>;
+    readonly wordList : readonly WordListEntry[];
+    readonly limits : Limits;
+    /** The absolute path of the local dictionary, or null. */
+    readonly dictionaryPath : string | null;
+    /** Where the dictionary path came from. */
+    readonly dictionarySource : "env" | "config" | null;
+};
+
+export const DEFAULT_INCLUDE : readonly string[] = [
+    "README.md",
+    "docs/**/*.{md,mdx}",
+    "packages/*/README.md",
+    "packages/*/src/**/*.{ts,tsx}",
+    "packages/*/build/**/*.{ts,tsx}",
+    "packages/*/commands/**/*.{ts,tsx}",
+    "packages/*/*.config.{ts,mts}",
+];
+
+export const DEFAULT_IGNORE : readonly string[] = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/*.d.ts",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+];
+
+export const DEFAULT_LIMITS : Limits = {
+    instructionWords : 20,
+    descriptionWords : 25,
+    paragraphSentences : 6,
+    nounClusterNouns : 3,
+};
+
+/** An error in the configuration. */
+export class ConfigError extends Error {
+    override readonly name : string = "ConfigError";
+}
+
+const SETTINGS : readonly string[] = ["error", "warning", "off"];
+
+const KNOWN_KEYS = new Set([
+    "$schema", "include", "ignore", "technicalNouns", "technicalVerbs", "properNouns", "allowedWords",
+    "rules", "wordList", "limits", "dictionaryPath",
+]);
+
+const WORD_LIST_KEYS = new Set(["id", "match", "suggest", "note", "severity", "verbOnly"]);
+
+/** This function makes sure that `value` is a valid configuration. It throws a `ConfigError` that lists all problems. */
+export function validateConfig(value : unknown, source : string) : SteConfigFile {
+    const problems : string[] = [];
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ConfigError(`${source}: the configuration must be a JSON object.`);
+    }
+    const record = value as Record<string, unknown>;
+    for (const key of Object.keys(record)) {
+        if (!KNOWN_KEYS.has(key)) problems.push(`"${key}" is not a known property. Known properties: ${[...KNOWN_KEYS].join(", ")}.`);
+    }
+    for (const key of ["include", "ignore", "technicalNouns", "technicalVerbs", "properNouns", "allowedWords"]) {
+        const item = record[key];
+        if (item !== undefined && !(Array.isArray(item) && item.every((entry) => typeof entry === "string"))) {
+            problems.push(`"${key}" must be an array of strings.`);
+        }
+    }
+    const rules = record["rules"];
+    if (rules !== undefined) {
+        if (typeof rules !== "object" || rules === null || Array.isArray(rules)) {
+            problems.push(`"rules" must be an object.`);
+        } else {
+            for (const [id, setting] of Object.entries(rules)) {
+                if (!isRuleId(id)) problems.push(`"rules.${id}" is not a known rule. Known rules: ${RULE_IDS.join(", ")}.`);
+                if (typeof setting !== "string" || !SETTINGS.includes(setting)) problems.push(`"rules.${id}" must be "error", "warning" or "off".`);
+            }
+        }
+    }
+    const limits = record["limits"];
+    if (limits !== undefined) {
+        if (typeof limits !== "object" || limits === null || Array.isArray(limits)) {
+            problems.push(`"limits" must be an object.`);
+        } else {
+            for (const [key, limit] of Object.entries(limits)) {
+                if (!Object.hasOwn(DEFAULT_LIMITS, key)) problems.push(`"limits.${key}" is not a known limit. Known limits: ${Object.keys(DEFAULT_LIMITS).join(", ")}.`);
+                if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1) problems.push(`"limits.${key}" must be an integer of 1 or more.`);
+            }
+        }
+    }
+    const dictionaryPath = record["dictionaryPath"];
+    if (dictionaryPath !== undefined && dictionaryPath !== null && typeof dictionaryPath !== "string") {
+        problems.push(`"dictionaryPath" must be a string or null.`);
+    }
+    const wordList = record["wordList"];
+    if (wordList !== undefined) {
+        if (!Array.isArray(wordList)) {
+            problems.push(`"wordList" must be an array.`);
+        } else {
+            wordList.forEach((item : unknown, index : number) => problems.push(...validateWordListEntry(item, `wordList[${index}]`)));
+        }
+    }
+    if (problems.length > 0) throw new ConfigError(`${source}:\n  - ${problems.join("\n  - ")}`);
+    return record as SteConfigFile;
+}
+
+function validateWordListEntry(item : unknown, where : string) : string[] {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) return [`"${where}" must be an object.`];
+    const problems : string[] = [];
+    const entry = item as Record<string, unknown>;
+    for (const key of Object.keys(entry)) {
+        if (!WORD_LIST_KEYS.has(key)) problems.push(`"${where}.${key}" is not a known property.`);
+    }
+    const match = entry["match"];
+    const matchValid = typeof match === "string" || (Array.isArray(match) && match.length > 0 && match.every((word) => typeof word === "string"));
+    if (match !== undefined && !matchValid) problems.push(`"${where}.match" must be a string or an array of strings.`);
+    if (entry["id"] !== undefined && typeof entry["id"] !== "string") problems.push(`"${where}.id" must be a string.`);
+    if (entry["id"] === undefined && match === undefined) problems.push(`"${where}" must have "id" or "match".`);
+    for (const key of ["suggest", "note"]) {
+        const text = entry[key];
+        if (text !== undefined && text !== null && typeof text !== "string") problems.push(`"${where}.${key}" must be a string or null.`);
+    }
+    const severity = entry["severity"];
+    if (severity !== undefined && (typeof severity !== "string" || !SETTINGS.includes(severity))) problems.push(`"${where}.severity" must be "error", "warning" or "off".`);
+    if (entry["verbOnly"] !== undefined && typeof entry["verbOnly"] !== "boolean") problems.push(`"${where}.verbOnly" must be true or false.`);
+    return problems;
+}
+
+/**
+ * This function merges the default word list and the entries of the
+ * configuration. An entry with the ID (or the first `match` word) of a
+ * default entry changes that entry. The severity "off" removes the entry
+ * with that ID, and it removes the `match` words from all entries.
+ */
+export function mergeWordList(defaults : readonly WordListEntry[], overrides : readonly WordListEntryConfig[]) : WordListEntry[] {
+    const entries = new Map<string, WordListEntry | null>(defaults.map((entry) => [entry.id, entry]));
+    for (const override of overrides) {
+        const match = override.match === undefined ? undefined : typeof override.match === "string" ? [override.match] : [...override.match];
+        const id = override.id ?? match![0]!;
+        const base = entries.get(id) ?? null;
+        if (override.severity === "off") {
+            entries.set(id, null);
+            const removed = new Set((match ?? []).map((word) => word.toLowerCase()));
+            for (const [key, entry] of entries) {
+                if (entry === null) continue;
+                const kept = entry.match.filter((word) => !removed.has(word.toLowerCase()));
+                entries.set(key, kept.length === 0 ? null : { ...entry, match : kept });
+            }
+            continue;
+        }
+        const merged : WordListEntry = {
+            id,
+            match : match ?? base?.match ?? [id],
+            suggest : override.suggest !== undefined ? override.suggest : base?.suggest ?? null,
+            note : override.note !== undefined ? override.note : base?.note ?? null,
+            severity : (override.severity as Severity | undefined) ?? base?.severity ?? "error",
+            verbOnly : override.verbOnly ?? base?.verbOnly ?? false,
+            context : base?.context ?? null,
+        };
+        entries.set(id, merged);
+    }
+    return [...entries.values()].filter((entry) : entry is WordListEntry => entry !== null);
+}
+
+export type BaseConfigOptions = {
+    /** The directory that `include` and `ignore` are relative to. Default: the empty string. */
+    readonly root? : string;
+    readonly configFile? : string | null;
+};
+
+/**
+ * This function applies the defaults to a configuration file. It reads no
+ * file and no environment variable, thus the result has no dictionary path.
+ */
+export function baseConfig(file : SteConfigFile = {}, options : BaseConfigOptions = {}) : ResolvedConfig {
+    const rules : Partial<Record<RuleId, RuleSetting>> = {};
+    for (const [id, setting] of Object.entries(file.rules ?? {})) {
+        if (isRuleId(id)) rules[id] = setting;
+    }
+    return {
+        root : options.root ?? "",
+        configFile : options.configFile ?? null,
+        include : file.include ?? DEFAULT_INCLUDE,
+        ignore : file.ignore ?? DEFAULT_IGNORE,
+        technicalNouns : file.technicalNouns ?? [],
+        technicalVerbs : file.technicalVerbs ?? [],
+        properNouns : file.properNouns ?? [],
+        allowedWords : file.allowedWords ?? [],
+        rules,
+        wordList : mergeWordList(DEFAULT_WORD_LIST, file.wordList ?? []),
+        limits : { ...DEFAULT_LIMITS, ...file.limits },
+        dictionaryPath : null,
+        dictionarySource : null,
+    };
+}

package/src/config.test.ts

@@ -0,0 +1,188 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+    ConfigError,
+    DEFAULT_IGNORE,
+    DEFAULT_INCLUDE,
+    DEFAULT_LIMITS,
+    findConfigFile,
+    loadConfig,
+    mergeWordList,
+    resolveConfig,
+    resolvePath,
+    validateConfig,
+} from "./config.js";
+import { DEFAULT_WORD_LIST } from "./word-list.js";
+
+let directory : string;
+
+beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), "ste-config-"));
+});
+
+afterEach(() => {
+    rmSync(directory, { recursive : true, force : true });
+});
+
+describe("validateConfig", () => {
+    it("accepts a full configuration", () => {
+        const file = {
+            $schema : "./schema.json",
+            include : ["README.md"],
+            ignore : ["**/dist/**"],
+            technicalNouns : ["monitor"],
+            technicalVerbs : ["flush"],
+            properNouns : ["Grafana"],
+            allowedWords : ["okay"],
+            rules : { "modal-verb" : "warning", "noun-cluster" : "off" },
+            wordList : [{ match : ["blazingly fast"], suggest : "\"fast\"", severity : "warning", verbOnly : false, note : null }, { id : "via", severity : "off" }],
+            limits : { instructionWords : 18 },
+            dictionaryPath : null,
+        };
+        expect(validateConfig(file, "ste.config.json")).toBe(file);
+    });
+
+    it("lists all problems in one error", () => {
+        const bad = {
+            unknown : 1,
+            include : "README.md",
+            rules : { "no-such-rule" : "error", "semicolon" : "fatal", "constructor" : "off" },
+            limits : { instructionWords : 0, constructor : 5, wordCount : 2 },
+            dictionaryPath : 3,
+            wordList : [{}, "x", { match : [], severity : "loud", verbOnly : "yes", id : 4, suggest : 5, extra : true }],
+        };
+        let message = "";
+        try {
+            validateConfig(bad, "ste.config.json");
+        } catch (error) {
+            expect(error).toBeInstanceOf(ConfigError);
+            message = (error as Error).message;
+        }
+        for (const part of [
+            "\"unknown\" is not a known property",
+            "\"include\" must be an array of strings",
+            "\"rules.no-such-rule\" is not a known rule",
+            "\"rules.semicolon\" must be \"error\", \"warning\" or \"off\"",
+            "\"rules.constructor\" is not a known rule",
+            "\"limits.instructionWords\" must be an integer of 1 or more",
+            "\"limits.constructor\" is not a known limit",
+            "\"limits.wordCount\" is not a known limit",
+            "\"dictionaryPath\" must be a string or null",
+            "\"wordList[0]\" must have \"id\" or \"match\"",
+            "\"wordList[1]\" must be an object",
+            "\"wordList[2].match\" must be a string or an array of strings",
+            "\"wordList[2].severity\"",
+            "\"wordList[2].verbOnly\" must be true or false",
+            "\"wordList[2].id\" must be a string",
+            "\"wordList[2].suggest\" must be a string or null",
+            "\"wordList[2].extra\" is not a known property",
+        ]) {
+            expect(message).toContain(part);
+        }
+    });
+
+    it("rejects values that are not objects", () => {
+        expect(() => validateConfig([], "x")).toThrow(ConfigError);
+        expect(() => validateConfig(null, "x")).toThrow("must be a JSON object");
+        expect(() => validateConfig({ rules : [] }, "x")).toThrow("\"rules\" must be an object");
+        expect(() => validateConfig({ limits : 3 }, "x")).toThrow("\"limits\" must be an object");
+        expect(() => validateConfig({ wordList : {} }, "x")).toThrow("\"wordList\" must be an array");
+    });
+});
+
+describe("resolveConfig", () => {
+    it("applies the defaults", () => {
+        const config = resolveConfig({}, { root : directory });
+        expect(config.include).toBe(DEFAULT_INCLUDE);
+        expect(config.ignore).toBe(DEFAULT_IGNORE);
+        expect(config.limits).toEqual(DEFAULT_LIMITS);
+        expect(config.wordList).toEqual(DEFAULT_WORD_LIST);
+        expect(config.dictionaryPath).toBeNull();
+        expect(config.dictionarySource).toBeNull();
+        expect(config.configFile).toBeNull();
+    });
+
+    it("keeps known rule settings and merges the limits", () => {
+        const config = resolveConfig({ rules : { "modal-verb" : "warning" }, limits : { paragraphSentences : 4 } }, { root : directory });
+        expect(config.rules).toEqual({ "modal-verb" : "warning" });
+        expect(config.limits).toEqual({ ...DEFAULT_LIMITS, paragraphSentences : 4 });
+    });
+
+    it("resolves the dictionary path from the configuration, relative to the root", () => {
+        const config = resolveConfig({ dictionaryPath : ".ste/dictionary.json" }, { root : directory });
+        expect(config.dictionaryPath).toBe(resolve(directory, ".ste/dictionary.json"));
+        expect(config.dictionarySource).toBe("config");
+    });
+
+    it("gives the environment variable priority, relative to the working directory", () => {
+        const config = resolveConfig({ dictionaryPath : "a.json" }, { root : directory, cwd : "/work", env : { STE_DICTIONARY : "b.json" } });
+        expect(config.dictionaryPath).toBe(resolve("/work", "b.json"));
+        expect(config.dictionarySource).toBe("env");
+        expect(resolveConfig({}, { root : directory, env : { STE_DICTIONARY : "  " } }).dictionaryPath).toBeNull();
+    });
+
+    it("expands ~ to the home directory", () => {
+        expect(resolvePath("~/ste/dictionary.json", "/base")).toBe(join(homedir(), "ste/dictionary.json"));
+        expect(resolvePath("~", "/base")).toBe(homedir());
+        expect(resolvePath("/abs/file.json", "/base")).toBe(resolve("/abs/file.json"));
+    });
+});
+
+describe("mergeWordList", () => {
+    it("changes, adds and removes entries", () => {
+        const merged = mergeWordList(DEFAULT_WORD_LIST, [
+            { id : "via", suggest : "\"by\"", severity : "warning" },
+            { match : "blazingly fast", suggest : "\"fast\"" },
+            { id : "utilize", severity : "off" },
+            { match : ["easily"], severity : "off" },
+        ]);
+        const byId = new Map(merged.map((entry) => [entry.id, entry]));
+        expect(byId.get("via")).toMatchObject({ suggest : "\"by\"", severity : "warning", match : ["via"] });
+        expect(byId.get("blazingly fast")).toMatchObject({ match : ["blazingly fast"], suggest : "\"fast\"", severity : "error", verbOnly : false, note : null });
+        expect(byId.has("utilize")).toBe(false);
+        expect(byId.get("simple")!.match).toEqual(["simple", "simply"]);
+    });
+
+    it("removes an entry that has no words left", () => {
+        const merged = mergeWordList(DEFAULT_WORD_LIST, [{ match : ["numerous"], severity : "off" }]);
+        expect(merged.some((entry) => entry.id === "numerous")).toBe(false);
+    });
+
+    it("keeps the fields of a default entry that the override does not give", () => {
+        const merged = mergeWordList(DEFAULT_WORD_LIST, [{ id : "run", note : "Extra." }]);
+        expect(merged.find((entry) => entry.id === "run")).toMatchObject({ verbOnly : true, severity : "warning", note : "Extra." });
+    });
+});
+
+describe("loadConfig", () => {
+    it("finds ste.config.json in a parent directory and uses its directory as the root", () => {
+        writeFileSync(join(directory, "ste.config.json"), JSON.stringify({ technicalNouns : ["monitor"], dictionaryPath : "dict.json" }));
+        const nested = join(directory, "a", "b");
+        mkdirSync(nested, { recursive : true });
+        expect(findConfigFile(nested)).toBe(join(directory, "ste.config.json"));
+        const config = loadConfig({ cwd : nested });
+        expect(config.root).toBe(directory);
+        expect(config.technicalNouns).toEqual(["monitor"]);
+        expect(config.dictionaryPath).toBe(join(directory, "dict.json"));
+    });
+
+    it("uses the defaults without a configuration file", () => {
+        const config = loadConfig({ cwd : directory, env : {} });
+        expect(config.configFile === null || !config.configFile.startsWith(directory)).toBe(true);
+    });
+
+    it("reads an explicit configuration file", () => {
+        writeFileSync(join(directory, "custom.json"), JSON.stringify({ rules : { semicolon : "warning" } }));
+        expect(loadConfig({ cwd : directory, configPath : "custom.json" }).rules).toEqual({ semicolon : "warning" });
+    });
+
+    it("gives clear errors for a missing file, a file that is not JSON and a configuration that is not valid", () => {
+        expect(() => loadConfig({ cwd : directory, configPath : "missing.json" })).toThrow("Cannot read the configuration file");
+        writeFileSync(join(directory, "broken.json"), "{ nope");
+        expect(() => loadConfig({ cwd : directory, configPath : "broken.json" })).toThrow("is not valid JSON");
+        writeFileSync(join(directory, "invalid.json"), JSON.stringify({ rules : { nope : "error" } }));
+        expect(() => loadConfig({ cwd : directory, configPath : "invalid.json" })).toThrow("is not a known rule");
+    });
+});