@mark1russell7/ste-lint 0.0.0-stage → 0.1.1

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

package/src/run-cli.ts

@@ -0,0 +1,193 @@
+/**
+ * The command-line interface. `runCli` does not use `process` directly, so
+ * the tests can give it arguments, an environment and output functions.
+ */
+
+import { existsSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { ConfigError, DICTIONARY_ENV, loadConfig, type ResolvedConfig } from "./config.js";
+import { DictionaryError, loadDictionary, type Dictionary } from "./dictionary.js";
+import { findFiles } from "./files.js";
+import { formatJson, formatText, summarize } from "./format.js";
+import { buildLexicon } from "./lexicon.js";
+import { fileKind, Linter } from "./lint.js";
+import type { Finding } from "./types.js";
+
+export type CliIo = {
+    readonly cwd : string;
+    readonly env : Readonly<Record<string, string | undefined>>;
+    readonly stdout : (text : string) => void;
+    readonly stderr : (text : string) => void;
+};
+
+export type CliOptions = {
+    readonly patterns : readonly string[];
+    readonly format : "text" | "json";
+    readonly maxWarnings : number | null;
+    readonly configPath : string | null;
+    readonly help : boolean;
+};
+
+/** An incorrect command line. */
+export class UsageError extends Error {
+    override readonly name : string = "UsageError";
+}
+
+export const USAGE : string = `Usage: ste-lint [options] [patterns...]
+
+ste-lint examines the prose in Markdown files, MDX files and TypeScript doc
+comments. It finds text that does not obey the writing rules of ASD-STE100
+Simplified Technical English. The tool is an automated approximation of
+these rules. It does not certify that a text obeys the standard.
+
+Without patterns, ste-lint uses the "include" patterns of ste.config.json,
+or the default patterns. Patterns are relative to the working directory.
+
+Options:
+  --format <text|json>  The output format. The default is "text".
+  --max-warnings <n>    Exit with code 1 when there are more than n warnings.
+  --config <path>       Use this configuration file.
+  -h, --help            Show this help.
+
+Exit codes:
+  0  No errors, and not more warnings than the maximum.
+  1  One or more errors, or more warnings than the maximum.
+  2  An incorrect command line or configuration, or no files.
+
+Environment:
+  ${DICTIONARY_ENV}  The path of a local dictionary file. This path has
+                  priority over "dictionaryPath" in ste.config.json.
+`;
+
+function optionValue(argv : readonly string[], index : number, name : string) : string {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new UsageError(`The option ${name} needs a value.`);
+    return value;
+}
+
+/** This function reads the command-line arguments. */
+export function parseArgs(argv : readonly string[]) : CliOptions {
+    const patterns : string[] = [];
+    let format : CliOptions["format"] = "text";
+    let maxWarnings : number | null = null;
+    let configPath : string | null = null;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const argument = argv[i]!;
+        const [name, inline] = argument.startsWith("--") && argument.includes("=") ? [argument.slice(0, argument.indexOf("=")), argument.slice(argument.indexOf("=") + 1)] : [argument, undefined];
+        const value = () : string => {
+            if (inline !== undefined) return inline;
+            const next = optionValue(argv, i, name);
+            i++;
+            return next;
+        };
+        switch (name) {
+            case "-h":
+            case "--help":
+                help = true;
+                break;
+            case "--format": {
+                const text = value();
+                if (text !== "text" && text !== "json") throw new UsageError(`The format must be "text" or "json", not "${text}".`);
+                format = text;
+                break;
+            }
+            case "--max-warnings": {
+                const text = value();
+                const count = Number(text);
+                if (!/^\d+$/.test(text) || !Number.isSafeInteger(count)) throw new UsageError(`--max-warnings must be an integer of 0 or more, not "${text}".`);
+                maxWarnings = count;
+                break;
+            }
+            case "--config":
+                configPath = value();
+                break;
+            default:
+                if (argument.startsWith("-") && argument !== "-") throw new UsageError(`"${argument}" is not a known option. Use --help to show the options.`);
+                patterns.push(argument);
+        }
+    }
+    return { patterns, format, maxWarnings, configPath, help };
+}
+
+function displayPath(path : string, cwd : string) : string {
+    const shown = relative(cwd, path);
+    return (shown.length > 0 && !shown.startsWith("..") ? shown : path).split(sep).join("/");
+}
+
+function loadOptionalDictionary(config : ResolvedConfig, io : CliIo) : Dictionary | null {
+    if (config.dictionaryPath === null) return null;
+    if (!existsSync(config.dictionaryPath)) {
+        const from = config.dictionarySource === "env" ? DICTIONARY_ENV : "dictionaryPath";
+        io.stderr(`ste-lint: the dictionary file ${config.dictionaryPath} (from ${from}) does not exist. The unknown-word rule is off.\n`);
+        return null;
+    }
+    return loadDictionary(config.dictionaryPath);
+}
+
+/** This function starts the linter with command-line arguments. The result is the exit code. */
+export function runCli(argv : readonly string[], io : CliIo) : number {
+    let options : CliOptions;
+    try {
+        options = parseArgs(argv);
+    } catch (error) {
+        io.stderr(`ste-lint: ${(error as Error).message}\n`);
+        return 2;
+    }
+    if (options.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+
+    let config : ResolvedConfig;
+    let dictionary : Dictionary | null;
+    try {
+        config = loadConfig({ cwd : io.cwd, env : io.env, ...(options.configPath === null ? {} : { configPath : options.configPath }) });
+        dictionary = loadOptionalDictionary(config, io);
+    } catch (error) {
+        if (error instanceof ConfigError || error instanceof DictionaryError) {
+            io.stderr(`ste-lint: ${error.message}\n`);
+            return 2;
+        }
+        throw error;
+    }
+
+    const explicit = options.patterns.length > 0;
+    let files : string[];
+    try {
+        // The patterns of the command line are relative to the working directory. The ignore patterns are relative to the configuration.
+        files = (explicit
+            ? findFiles({ root : io.cwd, include : options.patterns, ignore : config.ignore, ignoreRoot : config.root })
+            : findFiles({ root : config.root, include : config.include, ignore : config.ignore })
+        ).filter((file) => fileKind(file) !== null);
+    } catch (error) {
+        // For example, a directory that the user cannot read (EACCES)
+        io.stderr(`ste-lint: cannot read the files: ${(error as Error).message}\n`);
+        return 2;
+    }
+    if (files.length === 0) {
+        io.stderr(explicit ? "ste-lint: no files match the patterns.\n" : "ste-lint: no files to examine.\n");
+        return explicit ? 2 : 0;
+    }
+
+    const linter = new Linter(config, buildLexicon(config, dictionary));
+    const findings : Finding[] = [];
+    let failed = false;
+    for (const file of files) {
+        try {
+            findings.push(...linter.lintFile(file, displayPath(file, resolve(io.cwd))));
+        } catch (error) {
+            io.stderr(`ste-lint: cannot examine ${file}: ${(error as Error).message}\n`);
+            failed = true;
+        }
+    }
+
+    const summary = summarize(findings, files.length);
+    io.stdout(options.format === "json" ? formatJson(findings, summary) : formatText(findings, summary));
+    const tooManyWarnings = options.maxWarnings !== null && summary.warnings > options.maxWarnings;
+    if (tooManyWarnings && options.format === "text") {
+        io.stderr(`ste-lint: ${summary.warnings} warnings. The maximum is ${options.maxWarnings}.\n`);
+    }
+    if (failed) return 2;
+    return summary.errors > 0 || tooManyWarnings ? 1 : 0;
+}