markuplint 5.4.0 → 5.6.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.6.0](https://github.com/markuplint/markuplint/compare/v5.5.0...v5.6.0) (2026-11-12)
+
+### Bug Fixes
+
+* **markuplint:** keep the scope of the suppressions ([4f2409d](https://github.com/markuplint/markuplint/commit/4f2409d1d9c98cefbbe91f7c0f084f5855fafeb5)), closes [#4592](https://github.com/markuplint/markuplint/issues/4592)
+
+
+# [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)
@@ -134,6 +136,7 @@ $ markuplint --prune-suppressions "src/**/*.html"
 - Only `error`-severity violations are suppressed; `warning` and `info` always pass through.
 - If the number of violations for a file+rule pair **exceeds** the suppressed count, **all** violations for that pair are reported.
 - `--suppress` always exits with code 0 (success).
+- Running `--suppress` again keeps the entries it does not record, scope included, and gives the ones it records the newly computed scope.
 - When a DOM tree is available, each suppression entry includes a **scope selector** (computed via LCA) to narrow suppression to a specific subtree. Entries without `scope` apply to the entire file.
 
 ```json

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>;