markuplint 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.5.0](https://github.com/markuplint/markuplint/compare/v5.4.0...v5.5.0) (2026-11-10)
+
+### Bug Fixes
+
+* **markuplint:** exit with the lint verdict under --format json ([3c02102](https://github.com/markuplint/markuplint/commit/3c02102e939565e628447b7c25490e4346db0f20)), closes [#4551](https://github.com/markuplint/markuplint/issues/4551)
+* **markuplint:** keep the whole report on a pipe by not calling process.exit() ([6d98027](https://github.com/markuplint/markuplint/commit/6d98027684cdcd0a3f30d45bebac81813a5a9fc7)), closes [#4554](https://github.com/markuplint/markuplint/issues/4554)
+* **markuplint:** reject the options that act on a file when the source is stdin ([f980686](https://github.com/markuplint/markuplint/commit/f9806863a1e12c3a4d78ef30b739a65ce0318ee6)), closes [#4560](https://github.com/markuplint/markuplint/issues/4560)
+* **markuplint:** report a failure to resolve pretenders as a config-error of the file ([6178627](https://github.com/markuplint/markuplint/commit/61786271a4be989a91e8757c455dbeec9ffe4e9e))
+* **markuplint:** search every tree with --search ([a2e8955](https://github.com/markuplint/markuplint/commit/a2e89552b430e3473c6e7c00c273d05de9b9cdec))
+* **markuplint:** stop --max-count from changing the exit decision ([8dd1b8a](https://github.com/markuplint/markuplint/commit/8dd1b8a86e86c3b0e1410fc22d708baa0282e853)), closes [#4556](https://github.com/markuplint/markuplint/issues/4556)
+* **markuplint:** take configFile as a value of extends is ([789a487](https://github.com/markuplint/markuplint/commit/789a487d3efd257e9e13969674aed9f002b7ee93))
+
+### Features
+
+* **markuplint:** describe the parse errors of framework parsers in the parseError option ([095b21a](https://github.com/markuplint/markuplint/commit/095b21af53ec0cc03a7e87a9dd9a26669978b74d))
+
+
 # [5.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
 
 ### Bug Fixes

package/README.md

@@ -69,11 +69,13 @@ $ npx markuplint --help
 
 Usage
 	$ markuplint <HTML file paths (glob format)>
-	$ <stdout> | markuplint
+	$ <stdout> | markuplint                Read the source from the standard input when the output is a terminal. Not with --search, --fix or the suppressions options.
+	$ <stdout> | markuplint -              Read the source from the standard input. Not with file paths, --search, --fix or the suppressions options.
 
 Options
 	--config,                -c FILE_PATH  A configuration file path.
 	--fix,                                 Fix HTML.
+	--fix-dry-run                          Show what --fix would change without writing files.
 	--format,                -f FORMAT     Output format. Support "JSON", "Simple", "GitHub" and "Standard". Default: "Standard".
 	--no-search-config                     No search a configure file automatically.
 	--ignore-ext                           Evaluate files that are received even though the type of extension.
@@ -86,11 +88,11 @@ Options
 	--show-config                          Output computed configuration of the target file. Supports "details" and empty. Default: empty.
 	--verbose                              Output with detailed information.
 	--include-node-modules                 Include files in node_modules directory. Default: false.
-	--severity-parse-error                 Specifies the severity level of parse errors. Supports "error", "warning", and "off". Default: "error".
-	--severity-deprecation                 Specifies the severity level of deprecated rule name notices. Supports "error", "warning", and "off". Default: "warning".
-	--max-count                            Limit the number of violations shown. Default: 0 (no limit).
+	--severity-parse-error                 Severity for the built-in parse-error channel. Supports "error", "warning", and "off". Unset by default: fatal ParserErrors emit at "error" and non-fatal parse5 and framework parser events are off (opt-in per code via config).
+	--severity-deprecation                 Severity for the built-in rule-deprecation channel (deprecated rule names). Supports "error", "warning", and "off". Default: "warning".
+	--max-count                            Limit the number of violations shown, not the exit code. Default: 0 (no limit).
 	--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).
-	--progressive-output                   Output results immediately after processing each file. Default: false.
+	--no-progressive-output                Wait until every file is processed before outputting results. Default: false (output progressively).
 
 	--suppress                             [Experimental] Generate/update suppressions file for all current errors.
 	--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.
@@ -105,8 +107,8 @@ Options
 
 Examples
 	$ markuplint verifyee.html --config path/to/.markuplintrc
-	$ markuplint "**/*.html" --max-count=10
 	$ cat verifyee.html | markuplint
+	$ cat verifyee.html | markuplint - --format JSON | jq
 ```
 
 ### Bulk Suppressions (Experimental)

package/lib/api/ml-engine.js

@@ -509,10 +509,18 @@ export class MLEngine extends Emitter {
      * of `@markuplint/shared`'s `errors/index.ts`): any non-fatal error thrown by
      * the resolution, or a `ConfigLoadError` collected into the config set's
      * `errs`, fails the file. Tier 1 errors — markuplint's own bugs
-     * (`isFatalError()`) — are not caught here. The other `errs` (a rule or a
-     * plugin that is not found, an invalid selector, a circular `extends`)
-     * leave the rest of the config usable, so they stay `config-error` warnings
-     * that `MLCore.verify()` reports.
+     * (`isFatalError()`) — are not caught here.
+     *
+     * The pretenders that the config asks for are resolved here as well, and
+     * fail the file in the same way. `@markuplint/pretenders` is an optional
+     * peer, so a config that needs it fails with how to install it when it is
+     * missing; any other non-fatal failure of the resolution, a component that
+     * cannot be read for one, is reported as a `config-error` too, instead of
+     * rejecting {@link exec} and ending a run that has other files to lint.
+     *
+     * The other `errs` (a rule or a plugin that is not found, an invalid
+     * selector, a circular `extends`) leave the rest of the config usable, so
+     * they stay `config-error` warnings that `MLCore.verify()` reports.
      */
     async #provide(cache = true) {
         this.#configFailure = null;
@@ -556,7 +564,19 @@ export class MLEngine extends Emitter {
             ...configSet.config.severity,
             ...this.#options?.severity,
         };
-        const pretenders = await this.#resolvePretenders(configSet, cache);
+        let pretenders;
+        try {
+            pretenders = await this.#resolvePretenders(configSet, cache);
+        }
+        catch (error) {
+            // What the configuration asks of pretenders cannot be resolved: `@markuplint/pretenders`, an optional
+            // peer, is not installed, or a component it reads is unreadable. As with the config itself, that fails
+            // this file, not the run.
+            if (isFatalError(error) || !(error instanceof Error)) {
+                throw error;
+            }
+            return this.#failConfig(error);
+        }
         fileLog('Resolved pretenders: %O', pretenders);
         const ruleset = this.#resolveRuleset(configSet);
         fileLog('Resolved ruleset: %O', ruleset);

package/lib/api/types.d.ts

@@ -6,6 +6,11 @@ import type { AnyMLRule, FixSummary, MLSchema, Ruleset } from '@markuplint/ml-co
  * Options for the markuplint API, controlling configuration, locale, rules, and behavior.
  */
 export type APIOptions = {
+    /**
+     * The configuration file to use; the search for one is skipped. Resolved as a value of
+     * `extends` is: a module name is loaded as such, and a relative path is based on the working
+     * directory, as a relative path in `config` and `defaultConfig` is.
+     */
     readonly configFile?: string;
     readonly config?: Config;
     readonly defaultConfig?: Config;

package/lib/cli/bootstrap.d.ts

@@ -1,5 +1,5 @@
 import type { ReadonlyDeep } from 'type-fest';
-export declare const help = "\nUsage\n\t$ markuplint <HTML file paths (glob format)>\n\t$ <stdout> | markuplint\n\nOptions\n\t--config,                -c FILE_PATH  A configuration file path.\n\t--fix,                                 Fix HTML.\n\t--fix-dry-run                          Show what --fix would change without writing files.\n\t--format,                -f FORMAT     Output format. Support \"JSON\", \"Simple\", \"GitHub\" and \"Standard\". Default: \"Standard\".\n\t--no-search-config                     No search a configure file automatically.\n\t--ignore-ext                           Evaluate files that are received even though the type of extension.\n\t--no-import-preset-rules               No import preset rules.\n\t--locale                               Locale of the message of violation. Default is an OS setting.\n\t--no-color,                            Output no color.\n\t--problem-only,          -p            Output only problems, without passeds.\n\t--no-allow-warnings                    Return status code 1 even if there are warnings.\n\t--allow-empty-input                    Return status code 1 even if there are no input files.\n\t--show-config                          Output computed configuration of the target file. Supports \"details\" and empty. Default: empty.\n\t--verbose                              Output with detailed information.\n\t--include-node-modules                 Include files in node_modules directory. Default: false.\n\t--severity-parse-error                 Severity for the built-in parse-error channel. Supports \"error\", \"warning\", and \"off\". Unset by default: fatal ParserErrors emit at \"error\" and non-fatal parse5 events are off (opt-in per code via config).\n\t--severity-deprecation                 Severity for the built-in rule-deprecation channel (deprecated rule names). Supports \"error\", \"warning\", and \"off\". Default: \"warning\".\n\t--max-count                            Limit the number of violations shown. Default: 0 (no limit).\n\t--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).\n\t--no-progressive-output                Wait until every file is processed before outputting results. Default: false (output progressively).\n\n\t--suppress                             [Experimental] Generate/update suppressions file for all current errors.\n\t--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.\n\t--prune-suppressions                   [Experimental] Remove stale entries from the suppressions file.\n\t--suppressions-location PATH           [Experimental] Custom path for the suppressions file. Default: \"markuplint-suppressions.json\".\n\n\t--init                                 Initialize settings interactively.\n\t--search                               Search lines of codes that include the target element by selectors.\n\n\t--help,                  -h            Show help.\n\t--version,               -v            Show version.\n\nExamples\n\t$ markuplint verifyee.html --config path/to/.markuplintrc\n\t$ cat verifyee.html | markuplint\n";
+export declare const help = "\nUsage\n\t$ markuplint <HTML file paths (glob format)>\n\t$ <stdout> | markuplint                Read the source from the standard input when the output is a terminal. Not with --search, --fix or the suppressions options.\n\t$ <stdout> | markuplint -              Read the source from the standard input. Not with file paths, --search, --fix or the suppressions options.\n\nOptions\n\t--config,                -c FILE_PATH  A configuration file path.\n\t--fix,                                 Fix HTML.\n\t--fix-dry-run                          Show what --fix would change without writing files.\n\t--format,                -f FORMAT     Output format. Support \"JSON\", \"Simple\", \"GitHub\" and \"Standard\". Default: \"Standard\".\n\t--no-search-config                     No search a configure file automatically.\n\t--ignore-ext                           Evaluate files that are received even though the type of extension.\n\t--no-import-preset-rules               No import preset rules.\n\t--locale                               Locale of the message of violation. Default is an OS setting.\n\t--no-color,                            Output no color.\n\t--problem-only,          -p            Output only problems, without passeds.\n\t--no-allow-warnings                    Return status code 1 even if there are warnings.\n\t--allow-empty-input                    Return status code 1 even if there are no input files.\n\t--show-config                          Output computed configuration of the target file. Supports \"details\" and empty. Default: empty.\n\t--verbose                              Output with detailed information.\n\t--include-node-modules                 Include files in node_modules directory. Default: false.\n\t--severity-parse-error                 Severity for the built-in parse-error channel. Supports \"error\", \"warning\", and \"off\". Unset by default: fatal ParserErrors emit at \"error\" and non-fatal parse5 and framework parser events are off (opt-in per code via config).\n\t--severity-deprecation                 Severity for the built-in rule-deprecation channel (deprecated rule names). Supports \"error\", \"warning\", and \"off\". Default: \"warning\".\n\t--max-count                            Limit the number of violations shown, not the exit code. Default: 0 (no limit).\n\t--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).\n\t--no-progressive-output                Wait until every file is processed before outputting results. Default: false (output progressively).\n\n\t--suppress                             [Experimental] Generate/update suppressions file for all current errors.\n\t--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.\n\t--prune-suppressions                   [Experimental] Remove stale entries from the suppressions file.\n\t--suppressions-location PATH           [Experimental] Custom path for the suppressions file. Default: \"markuplint-suppressions.json\".\n\n\t--init                                 Initialize settings interactively.\n\t--search                               Search lines of codes that include the target element by selectors.\n\n\t--help,                  -h            Show help.\n\t--version,               -v            Show version.\n\nExamples\n\t$ markuplint verifyee.html --config path/to/.markuplintrc\n\t$ cat verifyee.html | markuplint\n\t$ cat verifyee.html | markuplint - --format JSON | jq\n";
 export declare const cli: import("meow").Result<{
     config: {
         type: "string";

package/lib/cli/bootstrap.js

@@ -2,7 +2,8 @@ import meow from 'meow';
 export const help = `
 Usage
 	$ markuplint <HTML file paths (glob format)>
-	$ <stdout> | markuplint
+	$ <stdout> | markuplint                Read the source from the standard input when the output is a terminal. Not with --search, --fix or the suppressions options.
+	$ <stdout> | markuplint -              Read the source from the standard input. Not with file paths, --search, --fix or the suppressions options.
 
 Options
 	--config,                -c FILE_PATH  A configuration file path.
@@ -20,9 +21,9 @@ Options
 	--show-config                          Output computed configuration of the target file. Supports "details" and empty. Default: empty.
 	--verbose                              Output with detailed information.
 	--include-node-modules                 Include files in node_modules directory. Default: false.
-	--severity-parse-error                 Severity for the built-in parse-error channel. Supports "error", "warning", and "off". Unset by default: fatal ParserErrors emit at "error" and non-fatal parse5 events are off (opt-in per code via config).
+	--severity-parse-error                 Severity for the built-in parse-error channel. Supports "error", "warning", and "off". Unset by default: fatal ParserErrors emit at "error" and non-fatal parse5 and framework parser events are off (opt-in per code via config).
 	--severity-deprecation                 Severity for the built-in rule-deprecation channel (deprecated rule names). Supports "error", "warning", and "off". Default: "warning".
-	--max-count                            Limit the number of violations shown. Default: 0 (no limit).
+	--max-count                            Limit the number of violations shown, not the exit code. Default: 0 (no limit).
 	--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).
 	--no-progressive-output                Wait until every file is processed before outputting results. Default: false (output progressively).
 
@@ -40,9 +41,13 @@ Options
 Examples
 	$ markuplint verifyee.html --config path/to/.markuplintrc
 	$ cat verifyee.html | markuplint
+	$ cat verifyee.html | markuplint - --format JSON | jq
 `;
 export const cli = meow(help, {
     importMeta: import.meta,
+    // `index.ts` prints them: meow ends the process with `process.exit()`, which drops a pending write.
+    autoHelp: false,
+    autoVersion: false,
     flags: {
         config: {
             type: 'string',

package/lib/cli/command.d.ts

@@ -1,4 +1,22 @@
 import type { CLIOptions } from './bootstrap.js';
 import type { APIOptions } from '../api/types.js';
 import type { Target } from '@markuplint/file-resolver';
+/**
+ * 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 declare function command(files: readonly Readonly<Target>[], options: CLIOptions, apiOptions?: APIOptions): Promise<boolean>;

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,39 @@ 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
                 // 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 +264,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 +289,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 +336,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 +362,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 +419,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 +452,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>;

package/lib/cli/main.js

@@ -0,0 +1,171 @@
+/**
+ * @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.
+ */
+import { text } from 'node:stream/consumers';
+import { isFatalError } from '@markuplint/shared';
+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';
+/** The operand that means standard input. */
+const STDIN_OPERAND = '-';
+/**
+ * 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 async function main() {
+    // Same condition as meow's automatic handling: the flag has to be the only argument.
+    const isSoleArgument = cli.input.length === 0 && process.argv.length === 3;
+    if (cli.flags.v || (isSoleArgument && cli.flags.version === true)) {
+        return showVersion();
+    }
+    if (cli.flags.h || (isSoleArgument && cli.flags.help === true)) {
+        return showHelp(0);
+    }
+    if (cli.flags.verbose) {
+        verbosely();
+    }
+    if (cli.flags.init) {
+        try {
+            await initialize();
+        }
+        catch (error) {
+            if (isFatalError(error)) {
+                throw error;
+            }
+            process.stderr.write(error + '\n');
+            return 1;
+        }
+        return 0;
+    }
+    if (cli.flags.createRule) {
+        process.stderr.write("Use to run 'npx @markuplint/create-rule' instead of 'markuplint --create-rule'.\n");
+        return 1;
+    }
+    const files = cli.input;
+    if (files.includes(STDIN_OPERAND)) {
+        const fileFlags = givenFileFlags();
+        if (files.length > 1 || fileFlags.length > 0) {
+            const conflicts = files.length > 1 ? ['file paths', ...fileFlags] : fileFlags;
+            process.stderr.write(`The \`${STDIN_OPERAND}\` operand (standard input) cannot be combined with ${conflicts.join(', ')}.\n`);
+            return 1;
+        }
+        const stdin = await readStdin();
+        if (stdin === null) {
+            return 1;
+        }
+        // An empty input is an empty source, as `markuplint empty.html` is.
+        return lintStdin(stdin);
+    }
+    if (files.length > 0) {
+        if (cli.flags.search) {
+            try {
+                await search(files, cli.flags, cli.flags.search);
+            }
+            catch (error) {
+                if (isFatalError(error)) {
+                    throw error;
+                }
+                process.stderr.write(error + '\n');
+                return 1;
+            }
+            return 0;
+        }
+        return lint(files, cli.flags);
+    }
+    if (usePipe()) {
+        const fileFlags = givenFileFlags();
+        if (fileFlags.length > 0) {
+            process.stderr.write(`Standard input cannot be combined with ${fileFlags.join(', ')}.\n`);
+            return 1;
+        }
+        const stdin = await readStdin();
+        if (stdin === null) {
+            return 1;
+        }
+        if (!stdin) {
+            // result is empty
+            return showHelp(1);
+        }
+        return lintStdin(stdin);
+    }
+    // No arguments
+    return showHelp(1);
+}
+/**
+ * The options that act on a file that are given, by their names: `--fix` writes the fixed source
+ * to it (with nothing to write to, it created a file named `<AnonymousFile>`, #4560), `--search`
+ * and the suppressions options report or record by file. The standard input has none, so both
+ * ways of reading it (the `-` operand and the no-operand pipe) reject them, and name them in the
+ * message, from this one list: an option that acts on a file is added here, and nowhere else.
+ * `--fix-dry-run` is not one: it writes nothing and prints the diff.
+ */
+function givenFileFlags() {
+    const { search, fix, suppress, suppressRule, pruneSuppressions } = cli.flags;
+    // Each is given by the condition of the code that consumes it, not by one shared test:
+    // `--search` is a search when it is not empty (the file branch below tests it so), and
+    // `--suppress-rule` turns the suppressions mode on when it is set at all (`command.ts`).
+    const given = [
+        ['--search', Boolean(search)],
+        ['--fix', Boolean(fix)],
+        ['--suppress', Boolean(suppress)],
+        ['--suppress-rule', suppressRule != null],
+        ['--prune-suppressions', Boolean(pruneSuppressions)],
+    ];
+    return given.filter(([, isGiven]) => isGiven).map(([name]) => name);
+}
+function usePipe() {
+    return !process.stdin.isTTY && process.stdout.isTTY;
+}
+/**
+ * Reports a read failure on stderr and returns `null` instead of throwing,
+ * so the caller can return the exit code.
+ */
+async function readStdin() {
+    try {
+        return await text(process.stdin);
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        process.stderr.write(error + '\n');
+        return null;
+    }
+}
+function lintStdin(sourceCode) {
+    return lint([{ sourceCode }], { ...cli.flags, ignoreExt: true });
+}
+/**
+ * Runs `command()` and resolves to its exit code. A failure that is not fatal is reported on
+ * stderr with exit code 1, whatever the input is (file paths or the standard input).
+ */
+async function lint(...args) {
+    try {
+        return (await command(...args)) ? 1 : 0;
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        process.stderr.write(error + '\n');
+        return 1;
+    }
+}
+/** Prints what meow's `showVersion()` printed (`console.log` of the version). */
+function showVersion() {
+    process.stdout.write(cli.pkg.version + '\n');
+    return 0;
+}
+/** Prints what meow's `showHelp()` printed (`console.log` of the help, which ends with a newline). */
+function showHelp(exitCode) {
+    process.stdout.write(cli.help + '\n');
+    return exitCode;
+}

package/lib/cli/output.js

@@ -28,6 +28,8 @@ export function output(results, options) {
     let msg = `${out.join('\n')}\n`;
     msg = options.color ? msg : stripAnsi(msg);
     // If it has errors, Write to `stderr` and failure and exit.
+    // `index.ts` overwrites this `exitCode` with the verdict `command()` returns, which is the one
+    // that counts (warnings are written here too, yet only `--no-allow-warnings` fails on them).
     if (results.violations.length > 0) {
         process.stderr.write(msg);
         process.exitCode = 1;
@@ -78,7 +80,7 @@ function createSummaryLines(summary) {
         out.push(`${logger('✖')} ${problemCount} problem${problemCount === 1 ? '' : 's'} (${problemDetail}) in ${pluralize(summary.checkedFileCount, 'file')}`, `${pluralize(summary.checkedFileCount, 'file')} checked: ${passedFileCount} passed, ${summary.failedFileCount} failed`);
     }
     if (summary.skippedFileCount > 0) {
-        out.push(`${font.yellow('⚠')} ${pluralize(summary.skippedFileCount, 'file')} skipped because --max-count was reached`);
+        out.push(`${font.yellow('⚠')} ${pluralize(summary.skippedFileCount, 'file')} not reported because --max-count was reached (violations in ${summary.skippedFileCount === 1 ? 'it' : 'them'} still count toward the exit code)`);
     }
     return out;
 }

package/lib/cli/search/index.js

@@ -13,7 +13,8 @@ export async function search(files, options, selectors) {
                 name,
                 ...createRule({
                     verify({ document }) {
-                        const nodes = document.querySelectorAll(selectors);
+                        // Every tree is searched: what is in the content of a `template` element is found too
+                        const nodes = document.deepQuerySelectorAll(selectors);
                         locations.push(...[...nodes].map(node => {
                             return {
                                 file: document.filename ?? '_NO_FILE_',

package/lib/suppressions/compute-scope.d.ts

@@ -57,7 +57,7 @@ export interface PositionedNode extends ScopedNode {
  * (the one `CSS.escape()` is specified by), in which a code point that is not an ident code point of CSS
  * Syntax is escaped, so the output is always one identifier. A NUL is written as U+FFFD, as the algorithm
  * has it, so it does not read back as NUL. A scope is a CSS selector, and CSS lets any code point be part
- * of an identifier by escaping it, "even ones that CSS uses in its syntax". So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
+ * of an identifier by escaping it, even one that CSS uses in its syntax. So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
  * `Tabs` with the class `Root`, `py-1.5` is `py-1\.5`, `hover:bg-x` is `hover\:bg-x`, `2xl:flex` is
  * `\32 xl\:flex`, and a class that ends with `:nth-of-type(2)` is no position. What this writes and what
  * {@link unescapeIdentifier} reads are one form, so a scope matches the element it was made for.
@@ -69,7 +69,12 @@ export interface PositionedNode extends ScopedNode {
  * with `:nth-of-type(n)` (`div.a:nth-of-type(2)`) never matched, and is still read as a position. A `\`
  * that such a file holds is read as CSS reads it: `\ba` is the hex escape U+00BA.
  *
+ * CSS Syntax says of an identifier:
+ *
+ * > You can include any code point at all, even ones that CSS uses in its syntax, by escaping it.
+ *
  * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export declare function serializeIdentifier(name: string): string;
 /**
@@ -104,7 +109,7 @@ export declare function splitScopeAttr(segment: string): {
  * class `a\` at the position 2, and `a\:nth-of-type(2)` is the class `a:nth-of-type(2)`. The escapes
  * are scanned from the start, as {@link splitScopeIdents} does.
  *
- * @see https://www.w3.org/TR/css-syntax-3/#escaping
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export declare function splitScopeNth(segment: string): {
     readonly base: string;

package/lib/suppressions/compute-scope.js

@@ -40,7 +40,7 @@ const NON_ASCII_IDENT_CODE_POINT = /^[\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u0
  * (the one `CSS.escape()` is specified by), in which a code point that is not an ident code point of CSS
  * Syntax is escaped, so the output is always one identifier. A NUL is written as U+FFFD, as the algorithm
  * has it, so it does not read back as NUL. A scope is a CSS selector, and CSS lets any code point be part
- * of an identifier by escaping it, "even ones that CSS uses in its syntax". So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
+ * of an identifier by escaping it, even one that CSS uses in its syntax. So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
  * `Tabs` with the class `Root`, `py-1.5` is `py-1\.5`, `hover:bg-x` is `hover\:bg-x`, `2xl:flex` is
  * `\32 xl\:flex`, and a class that ends with `:nth-of-type(2)` is no position. What this writes and what
  * {@link unescapeIdentifier} reads are one form, so a scope matches the element it was made for.
@@ -52,7 +52,12 @@ const NON_ASCII_IDENT_CODE_POINT = /^[\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u0
  * with `:nth-of-type(n)` (`div.a:nth-of-type(2)`) never matched, and is still read as a position. A `\`
  * that such a file holds is read as CSS reads it: `\ba` is the hex escape U+00BA.
  *
+ * CSS Syntax says of an identifier:
+ *
+ * > You can include any code point at all, even ones that CSS uses in its syntax, by escaping it.
+ *
  * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export function serializeIdentifier(name) {
     let result = '';
@@ -187,7 +192,7 @@ export function splitScopeAttr(segment) {
  * class `a\` at the position 2, and `a\:nth-of-type(2)` is the class `a:nth-of-type(2)`. The escapes
  * are scanned from the start, as {@link splitScopeIdents} does.
  *
- * @see https://www.w3.org/TR/css-syntax-3/#escaping
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export function splitScopeNth(segment) {
     // Only an unescaped `:` is looked at: an escaped one is read with its `\` before it, as one character

package/lib/suppressions/suppressions-file.d.ts

@@ -12,6 +12,11 @@ export declare function resolveSuppressionsPath(customPath?: string): string;
  * Reads and parses a suppressions JSON file.
  * Returns an empty object if the file does not exist.
  *
+ * Only the top level is checked: valid JSON that is not an object (`null`, an
+ * array, a string, a number) is not suppressions data and fails like
+ * unparsable JSON does, so that every caller gets the same readable error
+ * instead of a `TypeError` from the first `Object.keys` on it.
+ *
  * @param filePath - Absolute path to the suppressions file.
  * @returns The parsed suppressions data, or an empty object if the file does not exist.
  */

package/lib/suppressions/suppressions-file.js

@@ -20,13 +20,22 @@ export function resolveSuppressionsPath(customPath) {
  * Reads and parses a suppressions JSON file.
  * Returns an empty object if the file does not exist.
  *
+ * Only the top level is checked: valid JSON that is not an object (`null`, an
+ * array, a string, a number) is not suppressions data and fails like
+ * unparsable JSON does, so that every caller gets the same readable error
+ * instead of a `TypeError` from the first `Object.keys` on it.
+ *
  * @param filePath - Absolute path to the suppressions file.
  * @returns The parsed suppressions data, or an empty object if the file does not exist.
  */
 export async function readSuppressionsFile(filePath) {
     try {
         const content = await fs.readFile(filePath, 'utf8');
-        return JSON.parse(content);
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`Failed to parse suppressions file "${filePath}": the top level must be a JSON object`);
+        }
+        return parsed;
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "markuplint",
-	"version": "5.4.0",
+	"version": "5.5.0",
 	"description": "An HTML linter for all markup developers",
 	"author": "Yusuke Hirao",
 	"license": "MIT",
@@ -33,20 +33,28 @@
 		"dev": "tsc --watch --project tsconfig.build.json",
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
+	"devDependencies": {
+		"@markuplint/astro-parser": "5.5.0",
+		"@markuplint/jsx-parser": "5.5.0",
+		"@markuplint/mdx-parser": "5.5.0",
+		"@markuplint/pretenders": "5.5.0",
+		"@markuplint/svelte-parser": "5.5.0",
+		"@markuplint/vue-parser": "5.5.0"
+	},
 	"dependencies": {
 		"@markuplint/cli-utils": "5.3.0",
-		"@markuplint/file-resolver": "5.4.0",
-		"@markuplint/html-parser": "5.4.0",
-		"@markuplint/html-spec": "5.4.0",
-		"@markuplint/i18n": "5.3.0",
-		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-config": "5.4.0",
-		"@markuplint/ml-core": "5.4.0",
-		"@markuplint/ml-spec": "5.4.0",
-		"@markuplint/rules": "5.4.0",
-		"@markuplint/shared": "5.4.0",
+		"@markuplint/file-resolver": "5.5.0",
+		"@markuplint/html-parser": "5.5.0",
+		"@markuplint/html-spec": "5.5.0",
+		"@markuplint/i18n": "5.5.0",
+		"@markuplint/ml-ast": "5.5.0",
+		"@markuplint/ml-config": "5.5.0",
+		"@markuplint/ml-core": "5.5.0",
+		"@markuplint/ml-spec": "5.5.0",
+		"@markuplint/rules": "5.5.0",
+		"@markuplint/shared": "5.5.0",
 		"@types/debug": "^4.1.13",
-		"chokidar": "^5.0.0",
+		"chokidar": "^6.0.0",
 		"debug": "^4.4.3",
 		"meow": "^14.1.0",
 		"os-locale": "^8.0.0",
@@ -54,5 +62,33 @@
 		"strip-ansi": "^7.2.0",
 		"type-fest": "^5.10.0"
 	},
-	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
+	"peerDependencies": {
+		"@markuplint/astro-parser": "^5.4.0",
+		"@markuplint/jsx-parser": "^5.4.0",
+		"@markuplint/mdx-parser": "^5.4.0",
+		"@markuplint/pretenders": "^5.4.0",
+		"@markuplint/svelte-parser": "^5.4.0",
+		"@markuplint/vue-parser": "^5.4.0"
+	},
+	"peerDependenciesMeta": {
+		"@markuplint/astro-parser": {
+			"optional": true
+		},
+		"@markuplint/jsx-parser": {
+			"optional": true
+		},
+		"@markuplint/mdx-parser": {
+			"optional": true
+		},
+		"@markuplint/pretenders": {
+			"optional": true
+		},
+		"@markuplint/svelte-parser": {
+			"optional": true
+		},
+		"@markuplint/vue-parser": {
+			"optional": true
+		}
+	},
+	"gitHead": "fedebcfd56eaec4642e68643b2f9e10750d810e1"
 }