mdrefine 0.2.0-rc.2 → 0.2.0

package/dist/cli/main.js

@@ -1,151 +1,184 @@
 #!/usr/bin/env node
-import { Command } from "commander";
-import { createTwoFilesPatch } from "diff";
-import { access, constants, readFile, realpath, stat } from "node:fs/promises";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
+import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { format, lint, ruleRegistry } from "../core/engine.js";
 import { loadConfig } from "../config/load.js";
-import { resolveConfig } from "../config/resolve.js";
-import { discover, vaultFor, writeAtomic } from "../workspace/files.js";
-import { enclosingVault, vaultOf } from "../workspace/vault.js";
-import { excludeSelection } from "../workspace/selection.js";
-import { createWorkspace } from "../workspace/index.js";
-import { pathError, refusal, refusalText } from "../workspace/access.js";
+import { dialectAliases, dialects, resolveConfig } from "../config/resolve.js";
+import { isIgnoredInput, replacementFailure, replacementProblem, skippedMessage, writeFormatted, } from "../workspace/files.js";
+import { assumedDialect, checkRoot, discoverFrom } from "../workspace/discovery.js";
+import { enclosingVault } from "../workspace/vault.js";
+import { refusal, refusalText } from "../workspace/access.js";
+import { decodeText, NotUtf8Error } from "../workspace/encoding.js";
+import { unifiedDiff } from "./diff.js";
 const manifest = JSON.parse(await readFile(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8"));
+// Subcommands inherit these settings, so they come before the commands.
 const program = new Command()
     .name("mdtools")
     .description("Lint and format Markdown with explicit dialects and configurable rules.")
-    .version(manifest.version);
-function common(command) {
+    .version(manifest.version, "-V, --version", "Print the version")
+    .helpOption("-h, --help", "Print help for the command")
+    .helpCommand("help [command]", "Print help for a command")
+    // Commander starts its messages with "error: ", the tool with its name.
+    .configureOutput({
+    outputError: (text, write) => write(`mdtools: ${text.replace(/^error: /, "")}`),
+})
+    // Throw instead of exiting, so that a usage error can end with code 2.
+    .exitOverride();
+const configOption = [
+    "--config <file>",
+    "Use this JSON, JSONC, or JavaScript configuration file instead of searching for one",
+];
+/** The dialects, each with its other names, as in "forgejo (alias: codeberg)". */
+const dialectList = dialects
+    .map((dialect) => {
+    const aliases = Object.entries(dialectAliases).flatMap(([name, of]) => of === dialect ? [name] : []);
+    return aliases.length ? `${dialect} (alias: ${aliases.join(", ")})` : dialect;
+})
+    .join(", ");
+/** The options that choose the configuration, the workspace, and the dialect. */
+function workspaceOptions(command) {
     return command
-        .option("--config <file>", "Explicit JSON, JSONC, or .mjs configuration")
-        .option("--root <directory>", "Workspace root (default: configuration directory or cwd)")
-        .option("--dialect <dialect>", "commonmark, github, forgejo (alias: codeberg), gitea, or obsidian (when none is named: github, or obsidian inside a vault)")
-        .option("--exclude <path>", "Exclude an exact file or directory (repeatable)", (value, previous) => [...previous, value], [])
+        .option(...configOption)
+        .option("--root <directory>", "Workspace root (default: the configuration file's directory; without one, the Git repository or vault where the search stopped, else the current directory)")
+        .option("--dialect <dialect>", `${dialectList} (when none is named: github, or obsidian inside a vault)`, (value) => {
+        if (!Object.hasOwn(dialectAliases, value) && !dialects.includes(value))
+            throw new InvalidArgumentError(`The dialects are ${dialectList}.`);
+        return value;
+    });
+}
+function common(command) {
+    return (workspaceOptions(command)
+        .option("--exclude <path>", "Exclude an exact file or directory (repeatable)", (value, previous = []) => [...previous, value])
         .option("--json", "Machine-readable output")
+        .option("--quiet", "Report errors only: leave warnings out of the report and its counts")
+        .option("--no-warn-ignored", "Do not warn about named files and directories that are skipped as ignored")
         .option("--stdin-filepath <file>", "Filename context for stdin")
         .option("--max-warnings <count>", "Fail when warning count exceeds this nonnegative integer", (value) => {
         const number = Number(value);
         if (!Number.isInteger(number) || number < 0)
             throw new Error("--max-warnings must be a nonnegative integer.");
         return number;
-    });
+    })
+        // Not an option: `run` answers it with the option that does what it asks for.
+        .addOption(new Option("--fix").hideHelp()));
 }
 /**
- * The dialect to assume for a document when nothing names one, or undefined for
- * the library's own default. An Obsidian vault shows a single line break as a
- * line break and holds wikilinks, both of which any other dialect lets reflow
- * change, so a document that a vault holds is read as a note.
+ * The configuration and workspace root that the options name. `--dialect` is
+ * applied to a copy, because an .mjs configuration may export a frozen object.
  */
-function assumedDialect(vault) {
-    return vault ? "obsidian" : undefined;
+async function workspace(flags) {
+    // Without this check the first thing to fail would be the search for a
+    // configuration file in the root, with a message about a file the user never named.
+    if (flags.root !== undefined)
+        await checkRoot(flags.root);
+    const loaded = await loadConfig(path.resolve(flags.root ?? "."), flags.config);
+    return {
+        ...loaded,
+        root: path.resolve(flags.root ?? loaded.root),
+        config: flags.dialect ? { ...loaded.config, dialect: flags.dialect } : loaded.config,
+    };
 }
 /**
- * Stops when the folder given as `--root` cannot serve as a workspace root.
- * Without this check the first thing to fail would be the search for a
- * configuration file in it, with a message about a file the user never named.
+ * The real path of `file`, which need not exist: the real path of the nearest
+ * directory above it that does, with the rest of `file` appended.
  */
-async function checkRoot(given) {
-    if (given === undefined)
-        return;
-    const root = path.resolve(given);
-    try {
-        if (!(await stat(root)).isDirectory())
-            throw new Error(`Workspace root is not a directory: ${root}`);
-        await access(root, constants.R_OK | constants.X_OK);
-    }
-    catch (error) {
-        throw pathError("Workspace root", root, error);
+async function located(file) {
+    const rest = [];
+    for (let current = path.resolve(file);;) {
+        try {
+            return path.join(await realpath(current), ...rest);
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(file);
+            rest.unshift(path.basename(current));
+            current = parent;
+        }
     }
 }
+/**
+ * The path of `file`, which need not exist, from the workspace root, with
+ * forward slashes, or undefined when it lies outside. Both are located through
+ * their real paths, as discovery locates files, so that a root reached through
+ * a link still holds the files below it.
+ */
+async function workspacePath(root, file) {
+    const actual = await realpath(root).catch(() => root);
+    const name = path
+        .relative(actual, await located(file))
+        .split(path.sep)
+        .join("/");
+    return name === ".." || name.startsWith("../") || path.isAbsolute(name) ? undefined : name;
+}
+/** The library's diagnostics for a document that it could not process as configured. */
+const failures = new Set(["engine/unsafe-format", "engine/rule-error"]);
 async function run(mode, inputs, flags) {
+    // ESLint and markdownlint-cli2 fix with --fix, Prettier with --write.
+    if (flags.fix)
+        throw new Error(mode === "lint"
+            ? "unknown option '--fix': lint never changes files; 'mdtools format --write' applies the fixes."
+            : "unknown option '--fix': format writes its changes with --write.");
     if ([flags.check, flags.diff, flags.write].filter(Boolean).length > 1)
         throw new Error("Choose only one of --check, --diff, and --write.");
     if (inputs.includes("-") && flags.exclude?.length)
         throw new Error("--exclude cannot be combined with stdin.");
-    await checkRoot(flags.root);
-    const loaded = await loadConfig(path.resolve(flags.root ?? "."), flags.config);
-    const root = path.resolve(flags.root ?? loaded.root);
-    if (flags.dialect)
-        loaded.config.dialect = flags.dialect;
-    // Which files to leave out does not depend on a document's dialect.
-    const resolved = resolveConfig(loaded.config, "document.md", loaded.plugins);
+    const { root, ...loaded } = await workspace(flags);
     const stdin = inputs.includes("-");
     if (stdin && (inputs.length !== 1 || flags.write))
         throw new Error("stdin must be the only input and cannot be combined with --write.");
-    const set = await discover(root, stdin ? [] : inputs, resolved.ignore, resolved.resolve);
-    set.selected = await excludeSelection(set.root, set.selected, flags.exclude ?? []);
-    /** The vault of the document read from stdin, found by a search of its own. */
-    let named;
+    /** The text read from stdin, by the name it is given in the workspace. */
+    let documents;
     if (stdin) {
-        const name = path
-            .relative(root, path.resolve(flags.stdinFilepath ?? path.join(root, "stdin.md")))
-            .split(path.sep)
-            .join("/");
-        if (name.startsWith("../") || path.isAbsolute(name))
+        const name = await workspacePath(root, flags.stdinFilepath ?? path.join(root, "stdin.md"));
+        if (name === undefined)
             throw new Error("--stdin-filepath must be within the workspace.");
-        let source = "";
-        process.stdin.setEncoding("utf8");
+        const chunks = [];
         for await (const chunk of process.stdin)
-            source += String(chunk);
-        set.files[name] = source;
-        set.selected = [name];
-        // The name can lead into a folder that discovery did not visit.
-        named = await vaultFor(set, name);
+            chunks.push(chunk);
+        try {
+            documents = { [name]: decodeText(Buffer.concat(chunks), "stdin") };
+        }
+        catch (error) {
+            // There is no file to report it for, and nothing else to process.
+            if (error instanceof NotUtf8Error)
+                throw new Error(`stdin is not UTF-8 text (${error.reason})`, { cause: error });
+            throw error;
+        }
     }
-    // Links into a directory that could not be read are reported as unchecked, not as missing.
-    const unreadable = set.skipped.flatMap((item) => (item.type === "directory" ? [item.path] : []));
+    // Paths on the command line are relative to the working directory, and no
+    // path selects the whole workspace; stdin is the only document then. Ignore
+    // rules apply to the path that `--stdin-filepath` names, as to a named file,
+    // and not to the default name.
+    const discovery = await discoverFrom({
+        root,
+        ...(stdin ? { inputs: [] } : inputs.length ? { inputs } : {}),
+        exclude: flags.exclude ?? [],
+        config: loaded.config,
+        plugins: loaded.plugins,
+        ...(documents ? { documents } : {}),
+    }, process.cwd(), flags.stdinFilepath !== undefined);
     const reports = [];
     const changes = [];
-    // Selected files that the system refused to let the tool read.
+    // Selected files that the system refused to let the tool read, or that are not UTF-8 text.
     const unread = [];
-    // The vault that the root is a folder of, if it is one: links may lead out of sight.
-    const enclosing = set.vaults.find((item) => item.rootInVault);
-    // One index per active dialect; build lazily for mixed documentation workspaces.
-    const indexes = new Map();
-    // The same index with the line-break setting of each vault that has documents in it.
-    const views = new Map();
-    for (const name of set.selected) {
-        const vault = stdin ? named : vaultOf(set.vaults, name);
-        const assumed = assumedDialect(vault);
-        const config = resolveConfig(loaded.config, name, loaded.plugins, assumed);
-        let workspace = indexes.get(config.dialect);
-        if (!workspace)
-            indexes.set(config.dialect, (workspace = createWorkspace(set.files, {
-                dialect: config.dialect,
-                directories: set.directories,
-                unreadable,
-                // The vault at or above the root holds the whole workspace and needs no entry.
-                vaults: set.vaults.flatMap((item) => (item.path ? [item.path] : [])),
-                ...(enclosing?.rootInVault ? { rootInVault: enclosing.rootInVault } : {}),
-            })));
-        // Whether a note may be reflowed is a setting of its own vault.
-        if (vault?.strictLineBreaks !== undefined) {
-            let ofDialect = views.get(config.dialect);
-            if (!ofDialect)
-                views.set(config.dialect, (ofDialect = new Map()));
-            const index = workspace;
-            workspace = ofDialect.get(vault);
-            if (!workspace)
-                ofDialect.set(vault, (workspace = { ...index, strictLineBreaks: vault.strictLineBreaks }));
-        }
-        const options = {
-            path: name,
-            config: loaded.config,
-            plugins: loaded.plugins,
-            workspace,
-            ...(assumed ? { defaultDialect: assumed } : {}),
-        };
-        const value = set.files[name];
+    for (const name of discovery.selected) {
+        const options = discovery.options(name);
         let source;
         try {
-            source = typeof value === "function" ? value() : value;
+            source = discovery.read(name);
         }
         catch (error) {
             // Report the file and carry on with the others; any other error is a fault.
             const code = refusal(error);
-            if (!code)
+            const problem = code
+                ? `could not be read (${refusalText(code)})`
+                : error instanceof NotUtf8Error
+                    ? `is not UTF-8 text (${error.reason})`
+                    : undefined;
+            if (!problem)
                 throw error;
             unread.push(name);
             reports.push({
@@ -154,7 +187,7 @@ async function run(mode, inputs, flags) {
                 diagnostics: [
                     {
                         start: 0,
-                        message: `The file could not be read (${refusalText(code)}) and was not ${mode === "lint" ? "linted" : "formatted"}.`,
+                        message: `The file ${problem} and was not ${mode === "lint" ? "linted" : "formatted"}.`,
                         rule: "engine/unreadable-file",
                         severity: "error",
                         line: 1,
@@ -164,8 +197,6 @@ async function run(mode, inputs, flags) {
             });
             continue;
         }
-        if (source === null)
-            continue;
         if (mode === "lint")
             reports.push({ path: name, diagnostics: lint(source, options) });
         else {
@@ -180,89 +211,178 @@ async function run(mode, inputs, flags) {
                 changes.push({ file: name, before: source, after: result.output });
         }
     }
-    // A file that could not be formatted safely, or not be read at all, is a failure
-    // to operate: nothing of the batch is written, and the run ends with status 2.
+    // A document that could not be read, had a rule refused or failing on it, or
+    // could not be written is a failure to operate, reported for its own file,
+    // and the run ends with status 2. Files do not depend on one another's
+    // content, so every other changed document is still written, and so is the
+    // result of one with a refused or failing rule, which the engine checked.
+    const failed = unread.length > 0 ||
+        reports.some((report) => report.diagnostics.some((item) => failures.has(item.rule)));
+    // Changed files that could not be written, each reported for its file.
+    const unwritten = [];
+    const refuse = (file, message) => {
+        unwritten.push(file);
+        reports
+            .find((report) => report.path === file)
+            .diagnostics.unshift({
+            start: 0,
+            message: `${message}.`,
+            rule: "engine/unwritable-file",
+            severity: "error",
+            line: 1,
+            column: 1,
+        });
+    };
+    // The files that were written, in the order of the report.
+    const written = [];
+    if (flags.write)
+        for (const change of changes) {
+            const file = path.join(discovery.root, change.file);
+            // A file that may not be written, such as a read-only one, is left alone.
+            const problem = await replacementProblem(file);
+            if (problem) {
+                refuse(change.file, `${problem}; the file is unchanged`);
+                continue;
+            }
+            try {
+                await writeFormatted(file, change.before, change.after);
+                written.push(change.file);
+            }
+            catch (error) {
+                const failure = replacementFailure(error);
+                if (!failure)
+                    throw error;
+                refuse(change.file, failure);
+            }
+        }
+    // As in ESLint, --quiet leaves warnings out of the report and of what counts them.
+    if (flags.quiet)
+        for (const report of reports)
+            report.diagnostics = report.diagnostics.filter((item) => item.severity !== "warn");
     const diagnostics = reports.flatMap((report) => report.diagnostics);
     const count = (severity) => diagnostics.filter((item) => item.severity === severity).length;
-    const unsafe = unread.length > 0 ||
-        reports.some((report) => report.diagnostics.some((item) => item.rule === "engine/unsafe-format"));
-    if (flags.write && !unsafe)
-        for (const change of changes)
-            await writeAtomic(path.join(set.root, change.file), change.before, change.after);
     if (flags.json)
         process.stdout.write(JSON.stringify({
             version: manifest.version,
             mode,
+            // The files' paths are relative to it, for programs to join.
+            root,
             files: reports,
-            written: flags.write === true && !unsafe,
-            ...(set.skipped.length ? { skipped: set.skipped } : {}),
+            written,
+            ...(discovery.skipped.length ? { skipped: discovery.skipped } : {}),
         }, null, 2) + "\n");
     else {
+        // Text names documents from the current directory, as Prettier does, so
+        // that a terminal or an editor opens them from where the command ran.
+        const here = await realpath(process.cwd()).catch(() => process.cwd());
+        const shown = (name) => path.relative(here, path.join(discovery.root, name)).split(path.sep).join("/");
         // Warnings about the run, not about a document: they do not change the exit status.
-        for (const item of set.skipped)
-            process.stderr.write(`mdtools: warning: ${item.message}\n`);
+        // A caller that passes every changed file can leave out those about ignored ones.
+        for (const item of discovery.skipped)
+            if (flags.warnIgnored !== false || !isIgnoredInput(item))
+                process.stderr.write(`mdtools: warning: ${skippedMessage(item, shown)}\n`);
+        // An ignored document from stdin comes back unchanged, as in Prettier, so
+        // that an editor that replaces its text with the output loses nothing.
         if (stdin && mode === "format" && !flags.check && !flags.diff)
-            process.stdout.write(reports[0]?.output ?? "");
+            process.stdout.write(reports[0]?.output ?? Object.values(documents ?? {})[0] ?? "");
         else if (mode === "format" && !flags.check && !flags.write)
             for (const change of changes)
-                process.stdout.write(createTwoFilesPatch(`a/${change.file}`, `b/${change.file}`, change.before, change.after));
+                process.stdout.write(unifiedDiff(`a/${shown(change.file)}`, `b/${shown(change.file)}`, change.before, change.after));
         for (const report of reports)
             for (const item of report.diagnostics)
-                process.stderr.write(`${report.path}:${item.line}:${item.column}: ${item.severity} ${item.rule}: ${item.message}\n`);
+                process.stderr.write(`${shown(report.path)}:${item.line}:${item.column}: ${item.severity} ${item.rule}: ${item.message}\n`);
+        // The files to fix when a check fails, as Prettier's --check lists them.
+        if (mode === "format" && flags.check && !stdin)
+            for (const change of changes)
+                process.stderr.write(`${shown(change.file)}\n`);
         if (!stdin) {
             // Lint changes nothing, so its summary counts what it reported instead.
             const outcome = mode === "lint"
                 ? `${count("error")} error(s), ${count("warn")} warning(s)`
-                : `${changes.length} ${flags.write && !unsafe ? "written" : "would change"}`;
-            process.stderr.write(`${set.selected.length - unread.length} file(s) ${mode === "lint" ? "linted" : "processed"}; ${outcome}${unread.length ? `; ${unread.length} could not be read` : ""}.\n`);
+                : flags.write
+                    ? `${written.length} written`
+                    : `${changes.length} would change`;
+            process.stderr.write(`${discovery.selected.length - unread.length} file(s) ${mode === "lint" ? "linted" : "processed"}; ${outcome}${unread.length ? `; ${unread.length} could not be read` : ""}${unwritten.length ? `; ${unwritten.length} could not be written` : ""}.\n`);
         }
     }
     const errors = count("error") > 0;
     const tooManyWarnings = flags.maxWarnings !== undefined && count("warn") > flags.maxWarnings;
-    process.exitCode = unsafe
-        ? 2
-        : errors || tooManyWarnings || (flags.check && changes.length > 0)
-            ? 1
-            : 0;
+    process.exitCode =
+        failed || unwritten.length > 0
+            ? 2
+            : errors || tooManyWarnings || (flags.check && changes.length > 0)
+                ? 1
+                : 0;
 }
-common(program.command("lint").argument("[paths...]", "Markdown files/directories, or - for stdin")).action((inputs, flags) => run("lint", inputs, flags));
-common(program.command("format").argument("[paths...]", "Markdown files/directories, or - for stdin"))
-    .option("--check", "Fail if formatting changes would be needed")
+common(program
+    .command("lint")
+    .argument("[paths...]", "Files, directories, or glob patterns to select, or - for stdin"))
+    .description("Report the findings of the enabled rules; never writes")
+    .action((inputs, flags) => run("lint", inputs, flags));
+common(program
+    .command("format")
+    .argument("[paths...]", "Files, directories, or glob patterns to select, or - for stdin"))
+    .description("Format documents: print a diff (the default), check, or write")
+    .option("--check", "Fail if formatting changes would be needed, and name the files")
     .option("--diff", "Preview the complete diff (default for file inputs)")
     .option("--write", "Write validated formatting changes")
     .action((inputs, flags) => run("format", inputs, flags));
-common(program.command("config").description("Inspect effective configuration"))
-    .command("explain <file>")
-    .action(async (file, _flags, command) => {
-    const flags = command.parent.opts();
-    await checkRoot(flags.root);
-    const loaded = await loadConfig(path.resolve(flags.root ?? "."), flags.config);
-    if (flags.dialect)
-        loaded.config.dialect = flags.dialect;
-    const root = path.resolve(flags.root ?? loaded.root);
-    const name = path.relative(root, path.resolve(file)).split(path.sep).join("/");
-    // The file need not exist. It is located through the root's real path, as
-    // discovery locates it, so that a root reached through a link is searched
-    // upward from where it really is.
+// The options belong to `config`, which reads them before or after `explain`;
+// `explain` repeats them so that its help lists them.
+workspaceOptions(workspaceOptions(program.command("config").description("Inspect the configuration"))
+    .command("explain")
+    .description("Print, as JSON, the configuration in effect for one document")
+    .argument("<file>", "The document, which need not exist")).action(async (file, _flags, command) => {
+    const flags = command.optsWithGlobals();
+    const { root, config, plugins, file: source } = await workspace(flags);
+    const name = await workspacePath(root, file);
+    if (name === undefined)
+        throw new Error(`Input is outside the workspace: ${file}`);
+    // The search for the document's vault starts from the root's real path too.
     const actual = await realpath(root).catch(() => root);
     process.stdout.write(JSON.stringify({
         root,
-        file: loaded.file ?? null,
-        effective: resolveConfig(loaded.config, name, loaded.plugins, assumedDialect(await enclosingVault(path.join(actual, name)))),
+        config: source ?? null,
+        path: name,
+        effective: resolveConfig({
+            config,
+            path: name,
+            plugins,
+            defaultDialect: assumedDialect(await enclosingVault(path.join(actual, name))),
+        }),
     }, null, 2) + "\n");
 });
 program
     .command("rules")
-    .description("List built-in rules")
-    .action(() => {
-    for (const [name, rule] of Object.entries(ruleRegistry()))
-        process.stdout.write(`${name}\t${rule.kind}\t${rule.description}\n`);
+    .description("List the built-in rules and those of the configuration's plugins")
+    .option(...configOption)
+    .option("--json", "Print the list as JSON")
+    .action(async (flags) => {
+    const { plugins } = await loadConfig(path.resolve("."), flags.config);
+    const rules = Object.entries(ruleRegistry(plugins)).map(([id, rule]) => ({
+        id,
+        kind: rule.kind,
+        description: rule.description,
+    }));
+    if (flags.json)
+        process.stdout.write(JSON.stringify({ rules }, null, 2) + "\n");
+    else
+        for (const rule of rules)
+            // One line per rule, even when a plugin's description has line breaks or tabs.
+            process.stdout.write(`${rule.id}\t${rule.kind}\t${rule.description.replace(/\s+/g, " ")}\n`);
 });
 try {
     await program.parseAsync();
 }
 catch (error) {
-    process.stderr.write(`mdtools: ${error instanceof Error ? error.message : String(error)}\n`);
-    process.exitCode = 2;
+    // Commander has printed the help, the version, or what is wrong with the
+    // command line. Help and the version succeed; a usage error ends with code 2,
+    // as in ESLint and Prettier, so that it does not pass for findings.
+    if (error instanceof CommanderError)
+        process.exitCode = error.exitCode === 0 ? 0 : 2;
+    else {
+        process.stderr.write(`mdtools: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 2;
+    }
 }
 //# sourceMappingURL=main.js.map