markuplint 5.4.0 → 5.6.0

package/lib/cli/command.js

@@ -2,10 +2,9 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { ConfigProvider, resolveFiles } from '@markuplint/file-resolver';
 import { ViolationCollector } from '@markuplint/ml-core';
-import { isFatalError } from '@markuplint/shared';
 import { MLEngine } from '../api/index.js';
 import { log } from '../debug.js';
-import { applySuppressions, generateSuppressions, mergeSuppressions, pruneSuppressions, readSuppressionsFile, resolveSuppressionsPath, writeSuppressionsFile, } from '../suppressions/index.js';
+import { applySuppressions, generateSuppressions, mergeSuppressions, pruneSuppressions, readSuppressionsFile, resolveSuppressionsPath, toAbsolutePath, toRelativePath, writeSuppressionsFile, } from '../suppressions/index.js';
 import { CONFIG_LEVEL_RULE_IDS, dedupeConfigLevelViolations } from '../dedupe-config-violations.js';
 import { outputDryRunDiff } from './dry-run-output.js';
 import { output, outputSummary } from './output.js';
@@ -25,6 +24,53 @@ function parseSeverityFlag(value) {
     }
     return undefined;
 }
+/**
+ * Applies the suppressions of one file to that file's violations.
+ *
+ * Suppression is count-based per (file, rule), so it has to see every
+ * violation the file has, never a list `--max-count` already cut short:
+ * cut short, an entry would cover violations it does not cover in full, and
+ * would be called unused when what it covers was only left out of the
+ * report.
+ *
+ * @param filePath Absolute path of the linted file.
+ * @param violations Every violation of the file.
+ * @param suppressions The suppressions data read at the start of the run.
+ * @param suppressionsFilePath Absolute path of the suppressions file.
+ * @param nodeList The file's document node list, for scope-aware entries.
+ * @returns The violations the entries of the file do not suppress, and the
+ * entries of the file that suppressed nothing (`"<path>:<ruleId>"`).
+ */
+function applyFileSuppressions(filePath, violations, suppressions, suppressionsFilePath, nodeList) {
+    const relPath = toRelativePath(filePath, suppressionsFilePath);
+    const fileSuppressions = suppressions[relPath];
+    if (!fileSuppressions) {
+        return { kept: violations, unusedEntries: [] };
+    }
+    // An entry that cannot be applied fails the run: treating it as "suppresses
+    // nothing" would fail the build on violations the file is meant to
+    // suppress, with no word on why.
+    const { filtered, unusedEntries } = applySuppressions(new Map([[filePath, violations]]), { [relPath]: fileSuppressions }, suppressionsFilePath, { nodeLists: nodeList ? new Map([[filePath, nodeList]]) : undefined });
+    return { kept: filtered.get(filePath) ?? [], unusedEntries };
+}
+/**
+ * Runs the CLI over the given targets and writes the report in the format
+ * `--format` selects.
+ *
+ * @param files Files or source code to lint.
+ * @param options The parsed CLI flags.
+ * @param apiOptions Options passed through to every `MLEngine`.
+ * @returns `true` when the process must exit with `1`: an error, a warning
+ * with `--no-allow-warnings`, more warnings than `--max-warnings`, or a
+ * usage error such as no target files. The decision does not depend on
+ * `--format`: CI reads the exit code whatever format the report is in. Nor
+ * does it depend on `--max-count`, which only decides what the report shows:
+ * a violation the limit hides, and every violation of a file after the
+ * limit, still counts. (`--fix`, `--suppress` and `--prune-suppressions`
+ * ignore the limit altogether; see `maxCount` below.)
+ * `--show-config`, `--suppress` and `--prune-suppressions` do not lint for
+ * a verdict, so they return `false` whatever violations exist.
+ */
 export async function command(files, options, apiOptions) {
     const fixDryRun = options.fixDryRun;
     if (options.fix && fixDryRun) {
@@ -39,8 +85,12 @@ export async function command(files, options, apiOptions) {
         process.stderr.write('Error: --suppress/--suppress-rule and --prune-suppressions cannot be used together.\n');
         return true;
     }
-    const configFile = options.config &&
-        (path.isAbsolute(options.config) ? options.config : path.resolve(process.cwd(), options.config));
+    // `--max-count` limits what a lint report shows. `--fix` has to reach every
+    // file, and `--suppress` / `--prune-suppressions` write what the whole run
+    // found: a cut-short run would record too few violations, and would prune
+    // the entries of the files it never reached.
+    const maxCount = isSuppressMode || isPruneMode || fix ? 0 : options.maxCount;
+    const configFile = options.config;
     const locale = options.locale;
     const searchConfig = options.searchConfig;
     const ignoreExt = options.ignoreExt;
@@ -61,41 +111,44 @@ export async function command(files, options, apiOptions) {
     const format = options.format?.toLowerCase().trim();
     let hasError = false;
     let totalWarningCount = 0;
-    const collector = new ViolationCollector(options.maxCount);
+    const collector = new ViolationCollector(maxCount);
     const processedFiles = [];
     const skippedFiles = [];
+    // Targets the engine returned no result for (excluded by the config).
+    // They have no violations because they are not linted, which is what
+    // `--prune-suppressions` needs to see for their entries.
+    const ignoredFiles = [];
     // See `dedupeConfigLevelViolations` for why this Set needs to persist
     // across the whole run (not per file).
     const seenConfigMessages = new Set();
+    // The same for the files after the `--max-count` limit, which are not
+    // reported: they start from what the reported files already showed, so a
+    // config-level message counts once for the run's verdict, not once per
+    // skipped file, and the report's own Set is left as it is.
+    let seenConfigMessagesOfSkipped;
     const filesContent = new Map();
     // Suppressions scope computation is the only consumer of the parsed
-    // documents, so a document is retained past its file's own iteration only
-    // when that computation will run (--suppress, or a non-empty suppressions
-    // file in a normal run). Retaining every file's document otherwise keeps N
-    // DOM trees reachable until the command ends.
+    // documents. A normal run applies a file's suppressions while that file is
+    // processed, so its document is not kept past the iteration; only
+    // --suppress, which generates scopes for the whole run once it is over,
+    // retains them. Retaining every file's document otherwise keeps N DOM
+    // trees reachable until the command ends.
     //
     // A normal run reads the suppressions file exactly once, here, and applies
-    // that same snapshot at the end: deciding retention from one read and
-    // applying from a later one could disagree if the file changed mid-run,
-    // leaving `applySuppressions` without the node lists it needs.
+    // that same snapshot to every file. A file that cannot be read or parsed
+    // fails the run in every output mode: which mode prints the report must
+    // not decide whether a broken suppressions file is noticed.
     const suppressionsFilePath = resolveSuppressionsPath(options.suppressionsLocation);
     let normalRunSuppressions = {};
-    let suppressionsReadError;
     if (!isSuppressMode && !isPruneMode) {
-        try {
-            normalRunSuppressions = await readSuppressionsFile(suppressionsFilePath);
-        }
-        catch (error) {
-            if (isFatalError(error)) {
-                throw error;
-            }
-            // Proceed as if there were no suppressions; only the progressive
-            // output check below treats an unreadable file as an error.
-            suppressionsReadError = error;
-        }
+        normalRunSuppressions = await readSuppressionsFile(suppressionsFilePath);
     }
     const needsScope = isSuppressMode || Object.keys(normalRunSuppressions).length > 0;
     const nodeLists = new Map();
+    // Entries of the suppressions file that suppressed nothing in a file this
+    // run linted. A file the run did not lint (outside the targets) cannot be
+    // judged, so its entries are never listed.
+    const unusedSuppressionEntries = [];
     // Shared across every file in this run so its config cache — keyed by
     // resolved config `names`, not by target file — actually helps: config
     // loading/merging/plugin-resolution is done once per distinct config,
@@ -108,39 +161,28 @@ export async function command(files, options, apiOptions) {
         ...(parsedSeverityDeprecation != null && { deprecation: parsedSeverityDeprecation }),
     };
     // Progressive output prints each file's own violations as soon as that
-    // file is processed, ahead of the two whole-run passes that batch output
-    // waits for: suppressions (applied once at the end, below, via
-    // `applySuppressions`, since scope resolution and the "unused entry"
-    // report need the complete result set) and `--max-count` truncation
-    // (enforced by `collector.pushWithFile`'s running total across files,
-    // including which file the limit is hit within and which later files are
-    // skipped entirely). Printing per file ahead of either pass would show
-    // violations, or omit a skipped-file notice, that the run's own summary
-    // and exit code then contradict. Rather than duplicate that truncation
-    // and suppression logic in the progressive branch, fall back to batch
-    // output for the whole run whenever either is in play; --suppress and
-    // --prune-suppressions manage the suppressions file directly and are
-    // unaffected.
+    // file is processed. A file's suppressions are applied right there, so
+    // what is printed is what the run keeps. `--max-count` truncation is the
+    // one whole-run pass it cannot join: it is enforced by
+    // `collector.pushWithFile`'s running total across files, including which
+    // file the limit is hit within and which later files are skipped
+    // entirely. Printing per file ahead of it would show violations, or omit
+    // a skipped-file notice, that the run's own summary then contradicts, so
+    // the whole run falls back to batch output whenever it is in play.
     let progressiveOutput = options.progressiveOutput;
-    if (progressiveOutput && options.maxCount > 0) {
+    if (progressiveOutput && maxCount > 0) {
         progressiveOutput = false;
     }
-    if (progressiveOutput && !isSuppressMode && !isPruneMode) {
-        if (suppressionsReadError != null) {
-            throw suppressionsReadError;
-        }
-        if (needsScope) {
-            progressiveOutput = false;
-        }
-    }
     for (const file of fileList) {
-        // Check if collector is already locked (max-count reached)
-        if (collector.isLocked()) {
-            log('Skipping file due to max-count limit: %s', file.path);
+        // A file after the `--max-count` limit is not reported, but it is still
+        // linted: the limit only decides what the report shows, and a skipped
+        // file's errors must reach the exit decision like any other file's.
+        const skipped = collector.isLocked();
+        if (skipped) {
+            log('Not reporting file due to max-count limit: %s', file.path);
             skippedFiles.push(file.path);
-            continue;
         }
-        const engine = new MLEngine(file, {
+        const engineOptions = {
             configFile,
             fix,
             locale,
@@ -151,7 +193,8 @@ export async function command(files, options, apiOptions) {
             severity,
             ...apiOptions,
             configProvider,
-        });
+        };
+        const engine = new MLEngine(file, engineOptions);
         if (options.showConfig != null) {
             const isDetails = options.showConfig === 'details';
             const configSet = await engine.resolveConfig(false);
@@ -178,21 +221,40 @@ export async function command(files, options, apiOptions) {
         }
         const result = await engine.exec();
         if (!result) {
+            ignoredFiles.push(file.path);
             continue;
         }
-        processedFiles.push(result.filePath);
-        filesContent.set(result.filePath, {
-            sourceCode: result.sourceCode,
-            fixedCode: result.fixedCode,
-        });
+        if (!skipped) {
+            processedFiles.push(result.filePath);
+            filesContent.set(result.filePath, {
+                sourceCode: result.sourceCode,
+                fixedCode: result.fixedCode,
+            });
+        }
+        let nodeList;
         if (needsScope) {
-            const doc = engine.document;
+            // `exec()` leaves the engine on the pre-fix document, but with --fix the
+            // violations below are those of the fixed code (see `violationsBeforeDedupe`),
+            // and a scope is found by their line and column. The node list has to be
+            // that of the fixed code, which a file-based engine cannot be moved onto
+            // (its file is read-only), so the fixed code is parsed by an engine of its own.
+            let scopeEngine = engine;
+            if (!fixDryRun && result.fixSummary?.finalPassViolations) {
+                const [fixedFile] = await resolveFiles([{ sourceCode: result.fixedCode, name: result.filePath }]);
+                scopeEngine = new MLEngine(fixedFile, { ...engineOptions, fix: false });
+                await scopeEngine.exec();
+            }
+            const doc = scopeEngine.document;
             if (doc) {
-                // MLNode structurally satisfies PositionedNode (startLine, startCol, localName,
-                // id, classList, parentElement, children are all present). The double cast is
+                // MLNode structurally satisfies PositionedNode (startLine, startCol, endLine, endCol,
+                // localName, id, classList, parentElement, children, and closeTag on an element,
+                // are all present). The double cast is
                 // needed because TypeScript can't verify structural compatibility between the
                 // generic MLNode<T,O> and the plain PositionedNode interface at compile time.
-                nodeLists.set(result.filePath, doc.nodeList);
+                nodeList = doc.nodeList;
+                if (isSuppressMode) {
+                    nodeLists.set(result.filePath, nodeList);
+                }
             }
         }
         // In fix mode, report the violations remaining in the FIXED code
@@ -203,12 +265,24 @@ export async function command(files, options, apiOptions) {
         const violationsBeforeDedupe = fixDryRun
             ? result.violations
             : (result.fixSummary?.finalPassViolations ?? result.violations);
-        const reportedViolations = dedupeConfigLevelViolations(violationsBeforeDedupe, seenConfigMessages);
+        // Once the limit is hit every later file is skipped, so the seed below
+        // is complete: nothing adds to `seenConfigMessages` after this point.
+        const seen = skipped ? (seenConfigMessagesOfSkipped ??= new Set(seenConfigMessages)) : seenConfigMessages;
+        const reportedViolations = dedupeConfigLevelViolations(violationsBeforeDedupe, seen);
+        // Suppressions apply to the file's whole violation list, before the
+        // collector sees it. Count-based matching needs every violation of
+        // the file; the `--max-count` budget must be spent on violations
+        // that will be reported; and the exit decision counts `keptViolations`
+        // of every linted file, so the report's truncation never decides it.
+        const { kept: keptViolations, unusedEntries } = isSuppressMode || isPruneMode
+            ? { kept: reportedViolations, unusedEntries: [] }
+            : applyFileSuppressions(result.filePath, reportedViolations, normalRunSuppressions, suppressionsFilePath, nodeList);
+        unusedSuppressionEntries.push(...unusedEntries);
         // Progressive出力が有効でJSON形式でない場合
         if (progressiveOutput && format !== 'json') {
             // 即座に出力
             output({
-                violations: reportedViolations,
+                violations: [...keptViolations],
                 filePath: result.filePath,
                 sourceCode: result.sourceCode,
                 fixedCode: result.fixedCode,
@@ -216,9 +290,11 @@ export async function command(files, options, apiOptions) {
             }, options);
         }
         // Add violations to collector
-        collector.pushWithFile(result.filePath, ...reportedViolations);
-        const errorCount = reportedViolations.filter(v => v.severity === 'error').length;
-        const warningCount = reportedViolations.filter(v => v.severity === 'warning').length;
+        if (!skipped) {
+            collector.pushWithFile(result.filePath, ...keptViolations);
+        }
+        const errorCount = keptViolations.filter(v => v.severity === 'error').length;
+        const warningCount = keptViolations.filter(v => v.severity === 'warning').length;
         // Track total warning count across all files
         totalWarningCount += warningCount;
         if (!hasError && (errorCount > 0 || (warningCount > 0 && !options.allowWarnings))) {
@@ -261,7 +337,25 @@ export async function command(files, options, apiOptions) {
             process.stderr.write('No suppressions file found. Nothing to prune.\n');
             return false;
         }
-        const pruned = pruneSuppressions(collectedViolationsByFile, existing, suppressionsFilePath);
+        // The collected violations are the whole truth only for the files this
+        // run had as targets; a file outside the targets has no violations
+        // here because it was never checked, not because it is clean. Only the
+        // entries of target files (linted, or excluded by the config, which
+        // leaves them without violations) are judged, and so are those of a
+        // file that no longer exists, which has none either; the others are
+        // kept as they are.
+        const lintedPaths = new Set([...processedFiles, ...ignoredFiles].map(filePath => toRelativePath(filePath, suppressionsFilePath)));
+        const lintedEntries = {};
+        const unlintedEntries = {};
+        for (const [relPath, rules] of Object.entries(existing)) {
+            const judged = lintedPaths.has(relPath) ||
+                !(await fs.access(toAbsolutePath(relPath, suppressionsFilePath)).then(() => true, () => false));
+            (judged ? lintedEntries : unlintedEntries)[relPath] = rules;
+        }
+        const pruned = {
+            ...unlintedEntries,
+            ...pruneSuppressions(collectedViolationsByFile, lintedEntries, suppressionsFilePath),
+        };
         await writeSuppressionsFile(suppressionsFilePath, pruned);
         const existingCount = Object.values(existing).reduce((sum, rules) => sum + Object.keys(rules).length, 0);
         const prunedCount = Object.values(pruned).reduce((sum, rules) => sum + Object.keys(rules).length, 0);
@@ -269,59 +363,28 @@ export async function command(files, options, apiOptions) {
         process.stderr.write(`[Experimental] Suppressions pruned: ${removedCount} entry/entries removed, ${prunedCount} remaining.\n`);
         return false;
     }
-    // Normal lint mode: apply suppressions if file exists
-    let outputViolationsByFile = collectedViolationsByFile;
-    let suppressionsApplied = false;
-    try {
-        if (needsScope) {
-            const { filtered, unusedEntries } = applySuppressions(collectedViolationsByFile, normalRunSuppressions, suppressionsFilePath, { nodeLists });
-            outputViolationsByFile = filtered;
-            suppressionsApplied = true;
-            if (unusedEntries.length > 0) {
-                process.stderr.write(`[Experimental] ${unusedEntries.length} unused suppression entry/entries found. Run with --prune-suppressions to clean up.\n`);
-            }
-            // Recalculate hasError and totalWarningCount from filtered violations
-            hasError = false;
-            totalWarningCount = 0;
-            for (const violations of filtered.values()) {
-                const errorCount = violations.filter(v => v.severity === 'error').length;
-                const warningCount = violations.filter(v => v.severity === 'warning').length;
-                totalWarningCount += warningCount;
-                if (errorCount > 0 || (warningCount > 0 && !options.allowWarnings)) {
-                    hasError = true;
-                }
-            }
-        }
+    // Normal lint mode: the collector already holds the violations the
+    // suppressions leave, cut to `--max-count`; `hasError` and
+    // `totalWarningCount` were counted before that cut.
+    if (unusedSuppressionEntries.length > 0) {
+        process.stderr.write(`[Experimental] ${unusedSuppressionEntries.length} unused suppression entry/entries found. Run with --prune-suppressions to clean up.\n`);
     }
-    catch (error) {
-        if (isFatalError(error)) {
-            throw error;
-        }
-        // Suppressions file does not exist or is unreadable, proceed normally
+    // Check if max-warnings limit is exceeded (ESLint compatible)
+    if (!hasError && options.maxWarnings >= 0 && totalWarningCount > options.maxWarnings) {
+        hasError = true;
     }
-    // Output results
+    // Output results. The JSON branch returns early but with the same
+    // `hasError` as the other formats; see the `@returns` of this function.
     if (format === 'json') {
-        if (suppressionsApplied) {
-            // Build filtered array with filePath
-            const jsonOutput = [];
-            for (const [filePath, violations] of outputViolationsByFile) {
-                for (const violation of violations) {
-                    jsonOutput.push({ ...violation, filePath });
-                }
-            }
-            process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
-        }
-        else {
-            const jsonOutput = collector.toArray();
-            process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
-        }
-        return false;
+        const jsonOutput = collector.toArray();
+        process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
+        return hasError;
     }
     // Progressive出力が無効の場合のみループ後に出力
     if (!progressiveOutput) {
         // Output per file - include processed files without violations
         for (const filePath of processedFiles) {
-            const violations = outputViolationsByFile.get(filePath) || [];
+            const violations = collectedViolationsByFile.get(filePath) || [];
             const content = filesContent.get(filePath) || { sourceCode: '', fixedCode: '' };
             if (violations.length === 0 && !options.problemOnly) {
                 log('Output reports');
@@ -357,7 +420,7 @@ export async function command(files, options, apiOptions) {
     let noticeCount = 0;
     let failedFileCount = 0;
     for (const filePath of processedFiles) {
-        const violations = outputViolationsByFile.get(filePath) || [];
+        const violations = collectedViolationsByFile.get(filePath) || [];
         // A file whose only violations are config-level (`CONFIG_LEVEL_RULE_IDS`)
         // didn't fail on its own content — the config issue is reported once
         // for the whole run (see the dedupe above), not attributable to this
@@ -390,9 +453,5 @@ export async function command(files, options, apiOptions) {
         warningCount,
         noticeCount,
     }, options);
-    // Check if max-warnings limit is exceeded (ESLint compatible)
-    if (!hasError && options.maxWarnings >= 0 && totalWarningCount > options.maxWarnings) {
-        hasError = true;
-    }
     return hasError;
 }

package/lib/cli/index.d.ts

@@ -5,5 +5,41 @@
  * `process.stderr.write()` — never `console.warn`/`console.error`/
  * `console.log` — so stdout stays reserved for lint results
  * (e.g. `--format JSON` output that may be piped to other tools).
+ *
+ * The process ends by setting `process.exitCode` and returning from `main()`,
+ * never by `process.exit()`. On POSIX a pipe is written asynchronously, and
+ * `process.exit()` drops what is still queued: a report larger than the pipe
+ * buffer reached `| jq` cut off at its first 128 KiB (#4554). Node.js says
+ * `process.exit()` forces the exit "even if there are still asynchronous
+ * operations pending that have not yet completed fully, including I/O
+ * operations to `process.stdout`", and asks to "set the `process.exitCode`
+ * and allow the process to exit naturally" instead
+ * (https://nodejs.org/docs/latest-v24.x/api/process.html#processexitcode).
+ * meow's own `--help` / `--version` handling calls `process.exit()` as well,
+ * so it is turned off (`autoHelp` / `autoVersion` in `bootstrap.ts`) and done
+ * here. Keep it that way: a new `process.exit()` in this layer brings the
+ * truncation back for whatever it follows.
+ *
+ * Standard input is read in two ways. The `-` operand reads it whatever
+ * stdout is (POSIX Utility Syntax Guidelines, Guideline 13: "the '-' operand
+ * should be used to mean only standard input" for operands that represent
+ * files to be opened for reading), which is what lets
+ * `cat a.html | markuplint - --format json | jq` work with both ends piped.
+ * With no operand it is read only when stdout is a TTY: without that
+ * condition a parent that starts the CLI with no arguments and does not close
+ * stdin (a child process spawned with an inherited, never-closed stdin) would
+ * wait for it forever. An empty stdin is answered with the help and exit code
+ * 1 in that case, and linted as an empty source with the `-` operand.
+ * Neither way takes the options that act on a file (`--fix`, `--search` and the
+ * suppressions options): there is no file to write or record for, and `--fix`
+ * once created one named `<AnonymousFile>` (#4560). Both reject them before the
+ * standard input is read, so an empty input gets that error, not the help.
+ * `--fix-dry-run` is not among them: it writes nothing and only prints the diff.
+ *
+ * The flags that end the run early (`--help`, `--version`, `--init`,
+ * `--create-rule`) are evaluated before the operands, so `-` next to them is
+ * ignored. A failure that is not fatal (`isFatalError()`) is reported on stderr
+ * with exit code 1; a fatal one is rethrown, and the top-level `await` ends the
+ * process with exit code 1 and the stack.
  */
 export {};

package/lib/cli/index.js

@@ -5,70 +5,42 @@
  * `process.stderr.write()` — never `console.warn`/`console.error`/
  * `console.log` — so stdout stays reserved for lint results
  * (e.g. `--format JSON` output that may be piped to other tools).
+ *
+ * The process ends by setting `process.exitCode` and returning from `main()`,
+ * never by `process.exit()`. On POSIX a pipe is written asynchronously, and
+ * `process.exit()` drops what is still queued: a report larger than the pipe
+ * buffer reached `| jq` cut off at its first 128 KiB (#4554). Node.js says
+ * `process.exit()` forces the exit "even if there are still asynchronous
+ * operations pending that have not yet completed fully, including I/O
+ * operations to `process.stdout`", and asks to "set the `process.exitCode`
+ * and allow the process to exit naturally" instead
+ * (https://nodejs.org/docs/latest-v24.x/api/process.html#processexitcode).
+ * meow's own `--help` / `--version` handling calls `process.exit()` as well,
+ * so it is turned off (`autoHelp` / `autoVersion` in `bootstrap.ts`) and done
+ * here. Keep it that way: a new `process.exit()` in this layer brings the
+ * truncation back for whatever it follows.
+ *
+ * Standard input is read in two ways. The `-` operand reads it whatever
+ * stdout is (POSIX Utility Syntax Guidelines, Guideline 13: "the '-' operand
+ * should be used to mean only standard input" for operands that represent
+ * files to be opened for reading), which is what lets
+ * `cat a.html | markuplint - --format json | jq` work with both ends piped.
+ * With no operand it is read only when stdout is a TTY: without that
+ * condition a parent that starts the CLI with no arguments and does not close
+ * stdin (a child process spawned with an inherited, never-closed stdin) would
+ * wait for it forever. An empty stdin is answered with the help and exit code
+ * 1 in that case, and linted as an empty source with the `-` operand.
+ * Neither way takes the options that act on a file (`--fix`, `--search` and the
+ * suppressions options): there is no file to write or record for, and `--fix`
+ * once created one named `<AnonymousFile>` (#4560). Both reject them before the
+ * standard input is read, so an empty input gets that error, not the help.
+ * `--fix-dry-run` is not among them: it writes nothing and only prints the diff.
+ *
+ * The flags that end the run early (`--help`, `--version`, `--init`,
+ * `--create-rule`) are evaluated before the operands, so `-` next to them is
+ * ignored. A failure that is not fatal (`isFatalError()`) is reported on stderr
+ * with exit code 1; a fatal one is rethrown, and the top-level `await` ends the
+ * process with exit code 1 and the stack.
  */
-import { text } from 'node:stream/consumers';
-import { verbosely } from '../debug.js';
-import { cli } from './bootstrap.js';
-import { command } from './command.js';
-import { initialize } from './init/index.js';
-import { search } from './search/index.js';
-/* eslint-disable unicorn/no-process-exit */
-if (cli.flags.v) {
-    cli.showVersion(); // And exit successfully.
-}
-if (cli.flags.h) {
-    cli.showHelp(0); // And exit successfully.
-}
-if (cli.flags.verbose) {
-    verbosely();
-}
-if (cli.flags.init) {
-    await initialize().catch(error => {
-        process.stderr.write(error + '\n');
-        process.exit(1);
-    });
-    process.exit(0);
-}
-if (cli.flags.createRule) {
-    process.stderr.write("Use to run 'npx @markuplint/create-rule' instead of 'markuplint --create-rule'.\n");
-    process.exit(1);
-}
-const files = cli.input;
-if (files.length > 0) {
-    if (cli.flags.search) {
-        await search(files, cli.flags, cli.flags.search).catch(error => {
-            process.stderr.write(error + '\n');
-            process.exit(1);
-        });
-        process.exit(0);
-    }
-    const hasError = await command(files, cli.flags).catch(error => {
-        throw error;
-    });
-    process.exit(hasError ? 1 : 0);
-}
-if (usePipe()) {
-    const stdin = await text(process.stdin).catch(error => {
-        // eslint-disable-next-line no-console
-        console.warn(error);
-        process.exit(1);
-    });
-    if (!stdin) {
-        // result is empty
-        cli.showHelp(1);
-    }
-    const hasError = await command([{ sourceCode: stdin }], {
-        ...cli.flags,
-        ignoreExt: true,
-    }).catch(error => {
-        process.stderr.write(error + '\n');
-        process.exit(1);
-    });
-    process.exit(hasError ? 1 : 0);
-}
-// No arguments
-cli.showHelp(1);
-/* eslint-enable unicorn/no-process-exit */
-function usePipe() {
-    return !process.stdin.isTTY && process.stdout.isTTY;
-}
+import { main } from './main.js';
+process.exitCode = await main();

package/lib/cli/init/index.js

@@ -71,10 +71,10 @@ export async function initialize() {
     if (autoInstall) {
         process.stdout.write('Install the dependencies automatically\n');
         const modules = selectModules(selectedLangs);
-        const result = await installModule(modules, true).catch(error_ => new Error(error_));
+        const result = await installModule(modules, true).catch(error_ => error_ instanceof Error ? error_ : new Error(String(error_)));
         if (result instanceof Error) {
-            // eslint-disable-next-line unicorn/no-process-exit
-            process.exit(1);
+            // `index.ts` reports it on stderr and returns exit code 1; see its module JSDoc.
+            throw result;
         }
         if (result.alreadyExists) {
             process.stdout.write('Modules are installed already.\n');

package/lib/cli/main.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module cli/main
+ *
+ * The CLI run itself. `index.ts` is the entry point and owns the process boundary
+ * (the exit code and why `process.exit()` is not used); this module is separate so a spec
+ * can call `main()` without starting the process.
+ */
+/**
+ * Runs the CLI and resolves to its exit code.
+ *
+ * Every branch returns a number: a branch that forgets to leaves `undefined`,
+ * and the `process.exitCode` that `output.ts` set (1) would leak out.
+ */
+export declare function main(): Promise<number>;