markuplint 5.0.0-rc.2 → 5.0.0-rc.5

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Bug Fixes
+
+- **markuplint:** report post-fix violations for exit code and suppressions ([03855d6](https://github.com/markuplint/markuplint/commit/03855d6641ae736b65994fa6123e91779d2eb41e)), closes [#3890](https://github.com/markuplint/markuplint/issues/3890)
+- **markuplint:** stop repeating config-error messages once per file ([#4007](https://github.com/markuplint/markuplint/issues/4007)) ([466193d](https://github.com/markuplint/markuplint/commit/466193d286628f69e0d99fc8b2f66028523025aa)), closes [#4006](https://github.com/markuplint/markuplint/issues/4006)
+- **pretenders:** resolve same-named components via imports, not scan order ([#3957](https://github.com/markuplint/markuplint/issues/3957)) ([d46a514](https://github.com/markuplint/markuplint/commit/d46a5148c4d7afb156962f4ed795f40a9324e6c5)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+- **rules:** surface disallowed-element reason via reasonOnly (close [#3815](https://github.com/markuplint/markuplint/issues/3815)) ([#3986](https://github.com/markuplint/markuplint/issues/3986)) ([0142cec](https://github.com/markuplint/markuplint/commit/0142cec667f70fee086f2a6e06d7a26e66bda380))
+- **types): strict charset=utf-8; feat(rules:** usemap-references-map ([#3969](https://github.com/markuplint/markuplint/issues/3969)) ([c63070e](https://github.com/markuplint/markuplint/commit/c63070e29ccb283da7468b2fc67db372ebfcf42a)), closes [#3945](https://github.com/markuplint/markuplint/issues/3945) [#3966](https://github.com/markuplint/markuplint/issues/3966) [#3966](https://github.com/markuplint/markuplint/issues/3966) [#3928](https://github.com/markuplint/markuplint/issues/3928)
+
+### Code Refactoring
+
+- **rules:** redesign v5 rule system — naming, splits, specConformance ([#3989](https://github.com/markuplint/markuplint/issues/3989)) ([e925565](https://github.com/markuplint/markuplint/commit/e925565ce537848d7d1573369723cbce724a841b)), closes [#4](https://github.com/markuplint/markuplint/issues/4) [#aside-conditional-role-mapping-aria-13](https://github.com/markuplint/markuplint/issues/aside-conditional-role-mapping-aria-13)
+
+- feat(markuplint)!: stop forcing severity.parseError default in CLI ([79ff00b](https://github.com/markuplint/markuplint/commit/79ff00b5d068802f4d7e0d8d30ee63e55b8bc7f1)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+
+### Features
+
+- add `pretenders.auto` for on-demand import-graph resolution ([#3962](https://github.com/markuplint/markuplint/issues/3962)) ([5870671](https://github.com/markuplint/markuplint/commit/58706711a20c12cff080d49359f3f6443345eca3)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+- **config-presets:** forbid <base> after <link> or <script> in <head> ([#3925](https://github.com/markuplint/markuplint/issues/3925)) ([ceb892d](https://github.com/markuplint/markuplint/commit/ceb892d64772d459a6bd9564684218e3afbdec2e))
+- **rules:** add form-attr-references-form rule ([6b541f0](https://github.com/markuplint/markuplint/commit/6b541f032b76c3712c99ea35596b6b0aa79b6137))
+- **rules:** add input-button-non-empty-value rule ([2cc73dd](https://github.com/markuplint/markuplint/commit/2cc73ddd0f874fae9faf005f498d73fa364b682c))
+- **rules:** add input-file-empty-value rule ([228cbd7](https://github.com/markuplint/markuplint/commit/228cbd752956d3df8f525e4f19f9278a44d87160))
+- **rules:** add input-list-references-datalist rule ([#3931](https://github.com/markuplint/markuplint/issues/3931)) ([bf4ef54](https://github.com/markuplint/markuplint/commit/bf4ef54a1b2937ecbe05fbe5121ddfe199781a95))
+- **rules:** add label-for-references-labelable rule ([#3932](https://github.com/markuplint/markuplint/issues/3932)) ([3713e6b](https://github.com/markuplint/markuplint/commit/3713e6b435a76fe03a941a36a5e33c0ab06c9a80)), closes [#3918](https://github.com/markuplint/markuplint/issues/3918)
+- **rules:** add label-no-multiple-controls rule ([5da3f85](https://github.com/markuplint/markuplint/commit/5da3f8523dd6ffd9f44ea73d9012952aad85d821))
+- **rules:** add map-id-name-match rule ([1472daf](https://github.com/markuplint/markuplint/commit/1472daf62470bf56c4cb326ab47dc43ba87a8cb3))
+- **rules:** add no-extra-selected-options rule ([3ea75ac](https://github.com/markuplint/markuplint/commit/3ea75ac0b6850c36d5419924b18c1002dfb864a9))
+- **rules:** add progress-value-bounds rule ([#3926](https://github.com/markuplint/markuplint/issues/3926)) ([1e259ec](https://github.com/markuplint/markuplint/commit/1e259ec9929ceb3c7ac5864ce2807420646e9602))
+- **rules:** add wai-aria-tab-requires-tabpanel rule ([#3955](https://github.com/markuplint/markuplint/issues/3955)) ([eac9abe](https://github.com/markuplint/markuplint/commit/eac9abef20ef304c3da2114849686b9cf0733942))
+- **rules:** surface parse5-silent HTML LS parse errors (close nu-only umbrella [#3943](https://github.com/markuplint/markuplint/issues/3943)) ([#3980](https://github.com/markuplint/markuplint/issues/3980)) ([89951fa](https://github.com/markuplint/markuplint/commit/89951fa274007d56370510cb0cf11aead808ce13))
+- wire script-content into preset, bench, and default-rules ([dd0507a](https://github.com/markuplint/markuplint/commit/dd0507a9f54fcff25dba666a1c8fbc082489bdc8))
+
+### BREAKING CHANGES
+
+- **rules:** with no alias coverage.
+- CLI invocations that previously relied on the implicit
+  \`severity.parseError: 'error'\` default for _fatal_ parser errors are
+  unaffected — fatal errors continue to emit at \`'error'\` regardless. But
+  projects that lint malformed HTML and expected non-fatal parse5 events to
+  show up by default must now pass \`--severity-parse-error error\` (or set
+  \`severity.parseError\` in their config).
+
+# [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
+
+**Note:** Version bump only for package markuplint
+
+# [5.0.0-rc.3](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.2...v5.0.0-rc.3) (2026-04-19)
+
+**Note:** Version bump only for package markuplint
+
 # [5.0.0-rc.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
 
 ### Bug Fixes

package/README.md

@@ -25,7 +25,7 @@
 $ npx markuplint target.html
 ```
 
-Supported for _Node.js_ `v22.0.0` or later.
+Supported for _Node.js_ `v24.0.0` or later.
 
 ## Usage
 
@@ -138,7 +138,7 @@ $ markuplint --prune-suppressions "src/**/*.html"
 ```json
 {
   "src/index.html": {
-    "attr-duplication": { "count": 3, "scope": "#main-nav > ul" }
+    "no-duplicate-attr": { "count": 3, "scope": "#main-nav > ul" }
   }
 }
 ```
@@ -158,7 +158,7 @@ See [ESLint's Bulk Suppressions](https://eslint.org/docs/latest/use/suppressions
 
 ## Editor Extensions
 
-- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=yusukehirao.vscode-markuplint)
+- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=markuplint.vscode-markuplint)
 
 ## License
 

package/lib/api/ml-engine.d.ts

@@ -70,6 +70,22 @@ export declare class MLEngine extends Emitter<MLEngineEventMap> {
      * @param enable - Whether to enable watch mode
      */
     watchMode(enable: boolean): void;
+    /**
+     * Resolves the configuration set for the target file.
+     *
+     * Public — unlike the other resolution steps, which are private —
+     * because the CLI's `--show-config` needs the computed configuration
+     * without running a lint.
+     *
+     * Precedence contract (highest first): the inline `config` option,
+     * then the explicit `configFile` path, then auto-discovered config files
+     * (search is skipped when `noSearchConfig` or `configFile` is set),
+     * then `defaultConfig`. `markuplint:recommended` applies only when none
+     * of these are provided.
+     *
+     * @param cache - Whether to reuse previously loaded config files
+     * @returns The resolved configuration set
+     */
     resolveConfig(cache: boolean): Promise<ConfigSet>;
 }
 export {};

package/lib/api/ml-engine.js

@@ -1,6 +1,7 @@
-import { ConfigProvider, resolveFiles, resolveParser, resolvePretenders, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
-import { mergeConfig } from '@markuplint/ml-config';
+import { ConfigProvider, disambiguatePretendersForFile, invalidatePretenderResolutionCaches, resolveFiles, resolveParser, resolvePretenders, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
+import { applyRuleAliasesToConfig, mergeConfig } from '@markuplint/ml-config';
 import { MLCore, convertRuleset } from '@markuplint/ml-core';
+import { ruleAliasTable } from '@markuplint/rules';
 import { isFatalError } from '@markuplint/shared';
 import { FSWatcher } from 'chokidar';
 import { Emitter } from 'strict-event-emitter';
@@ -256,7 +257,7 @@ export class MLEngine extends Emitter {
             ...configSet.config.severity,
             ...this.#options?.severity,
         };
-        const pretenders = await this.#resolvePretenders(configSet);
+        const pretenders = await this.#resolvePretenders(configSet, cache);
         fileLog('Resolved pretenders: %O', pretenders);
         const ruleset = this.#resolveRuleset(configSet);
         fileLog('Resolved ruleset: %O', ruleset);
@@ -293,6 +294,22 @@ export class MLEngine extends Emitter {
             configErrors: configSet.errs,
         };
     }
+    /**
+     * Resolves the configuration set for the target file.
+     *
+     * Public — unlike the other resolution steps, which are private —
+     * because the CLI's `--show-config` needs the computed configuration
+     * without running a lint.
+     *
+     * Precedence contract (highest first): the inline `config` option,
+     * then the explicit `configFile` path, then auto-discovered config files
+     * (search is skipped when `noSearchConfig` or `configFile` is set),
+     * then `defaultConfig`. `markuplint:recommended` applies only when none
+     * of these are provided.
+     *
+     * @param cache - Whether to reuse previously loaded config files
+     * @returns The resolved configuration set
+     */
     async resolveConfig(cache) {
         this.emit('log', 'resolveConfig', JSON.stringify(this.#configProvider, null, 2));
         configLog('configProvider: %s', this.#configProvider);
@@ -317,7 +334,25 @@ export class MLEngine extends Emitter {
         }
         configLog('defaultRecommended: %s', defaultRecommended ?? 'N/A');
         this.emit('log', 'defaultRecommended', defaultRecommended ?? 'N/A');
-        const configSet = await this.#configProvider.resolve(this.#file, [configFilePathsFromTarget, this.#options?.configFile, configKey, defaultRecommended], cache);
+        const resolvedConfigSet = await this.#configProvider.resolve(this.#file, [configFilePathsFromTarget, this.#options?.configFile, configKey, defaultRecommended], cache);
+        // Rewrite deprecated rule names (v5 rule-system redesign, #3989) to
+        // their current replacement(s) so old configurations keep working.
+        // Applied once, here, after `extends` is fully merged — everything
+        // downstream (Ruleset, rule resolution, `--show-config`) sees only
+        // current rule names. Covers all three places a rule name can appear:
+        // the top-level `rules` map, and each `nodeRules`/`childNodeRules`
+        // entry's own `rules`.
+        const { config: aliasedConfig, warnings: ruleAliasWarnings } = applyRuleAliasesToConfig(resolvedConfigSet.config, ruleAliasTable);
+        const configSet = ruleAliasWarnings.length === 0
+            ? resolvedConfigSet
+            : {
+                ...resolvedConfigSet,
+                config: aliasedConfig,
+                errs: [
+                    ...resolvedConfigSet.errs,
+                    ...ruleAliasWarnings.map(({ deprecatedName, replacedBy }) => new Error(`Rule "${deprecatedName}" is deprecated and will be removed in v6. Use ${replacedBy.join(', ')} instead.`)),
+                ],
+            };
         this.emit('config', this.#file.path, configSet);
         if (this.#options?.watch) {
             // It doesn't watch the main HTML file because it may is watched and managed by a language server or text editor or more.
@@ -335,10 +370,22 @@ export class MLEngine extends Emitter {
     }
     async #resolvePretenders(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    configSet) {
-        const pretenders = await resolvePretenders(configSet.config.pretenders);
-        fileLog('Resolved pretenders: %O', pretenders);
-        return pretenders;
+    configSet, cache) {
+        if (!cache) {
+            // A cache-busting re-resolve (e.g. watch mode after a file change) must also
+            // invalidate `@markuplint/pretenders`' own module-level resolution caches —
+            // otherwise a renamed export or a newly valid tsconfig `paths` alias keeps
+            // resolving as it did before the change for the rest of the process's lifetime.
+            await invalidatePretenderResolutionCaches();
+        }
+        const sourceCode = await this.#file.getCode();
+        const pretenders = await resolvePretenders(configSet.config.pretenders, {
+            filePath: this.#file.path,
+            sourceCode,
+        });
+        const disambiguated = await disambiguatePretendersForFile(this.#file.path, sourceCode, pretenders);
+        fileLog('Resolved pretenders: %O', disambiguated);
+        return disambiguated;
     }
     async #resolveRules(plugins, ruleset) {
         const rules = await resolveRules(plugins, ruleset, this.#options?.importPresetRules ?? true);

package/lib/cli/bootstrap.d.ts

@@ -1,13 +1,5 @@
 import type { ReadonlyDeep } from 'type-fest';
-/**
- * Help text displayed when the CLI is invoked with `--help` or without arguments.
- * Documents all available options, flags, and usage examples.
- */
-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                 Specifies the severity level of parse errors. Supports \"error\", \"warning\", and \"off\". Default: \"error\".\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--progressive-output                   Output results immediately after processing each file. Default: false.\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";
-/**
- * The parsed CLI instance created by `meow`, providing access to
- * positional arguments (`cli.input`) and parsed flags (`cli.flags`).
- */
+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--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 cli: import("meow").Result<{
     config: {
         type: "string";
@@ -81,7 +73,6 @@ export declare const cli: import("meow").Result<{
     };
     severityParseError: {
         type: "string";
-        default: string;
     };
     maxCount: {
         type: "number";
@@ -93,7 +84,7 @@ export declare const cli: import("meow").Result<{
     };
     progressiveOutput: {
         type: "boolean";
-        default: false;
+        default: true;
     };
     suppress: {
         type: "boolean";
@@ -110,8 +101,4 @@ export declare const cli: import("meow").Result<{
         type: "string";
     };
 }>;
-/**
- * Deeply read-only type representing the parsed CLI flags.
- * Derived from the `meow` flag definitions in {@link cli}.
- */
 export type CLIOptions = ReadonlyDeep<typeof cli.flags>;

package/lib/cli/bootstrap.js

@@ -1,8 +1,4 @@
 import meow from 'meow';
-/**
- * Help text displayed when the CLI is invoked with `--help` or without arguments.
- * Documents all available options, flags, and usage examples.
- */
 export const help = `
 Usage
 	$ markuplint <HTML file paths (glob format)>
@@ -24,10 +20,10 @@ 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-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).
 	--max-count                            Limit the number of violations shown. 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.
@@ -44,10 +40,6 @@ Examples
 	$ markuplint verifyee.html --config path/to/.markuplintrc
 	$ cat verifyee.html | markuplint
 `;
-/**
- * The parsed CLI instance created by `meow`, providing access to
- * positional arguments (`cli.input`) and parsed flags (`cli.flags`).
- */
 export const cli = meow(help, {
     importMeta: import.meta,
     flags: {
@@ -123,7 +115,6 @@ export const cli = meow(help, {
         },
         severityParseError: {
             type: 'string',
-            default: 'error',
         },
         maxCount: {
             type: 'number',
@@ -135,8 +126,7 @@ export const cli = meow(help, {
         },
         progressiveOutput: {
             type: 'boolean',
-            // TODO: It will be changed to `true` in the next major version.
-            default: false,
+            default: true,
         },
         suppress: {
             type: 'boolean',

package/lib/cli/command.d.ts

@@ -1,16 +1,4 @@
 import type { CLIOptions } from './bootstrap.js';
 import type { APIOptions } from '../api/types.js';
 import type { Target } from '@markuplint/file-resolver';
-/**
- * Executes the markuplint linting command against the given files.
- *
- * Resolves file targets, creates an {@link MLEngine} for each file, collects
- * violations, and outputs results in the requested format. When the `--fix`
- * flag is set, overwrites files with their auto-fixed content.
- *
- * @param files - The list of file targets (paths or inline source code) to lint.
- * @param options - CLI options controlling output format, fix mode, locale, and other behaviors.
- * @param apiOptions - Optional overrides for the underlying API (e.g., custom rules or config).
- * @returns `true` if any errors were found (or warnings exceeded the limit), `false` otherwise.
- */
 export declare function command(files: readonly Readonly<Target>[], options: CLIOptions, apiOptions?: APIOptions): Promise<boolean>;

package/lib/cli/command.js

@@ -8,18 +8,6 @@ import { log } from '../debug.js';
 import { applySuppressions, generateSuppressions, mergeSuppressions, pruneSuppressions, readSuppressionsFile, resolveSuppressionsPath, writeSuppressionsFile, } from '../suppressions/index.js';
 import { outputDryRunDiff } from './dry-run-output.js';
 import { output, outputSummary } from './output.js';
-/**
- * Executes the markuplint linting command against the given files.
- *
- * Resolves file targets, creates an {@link MLEngine} for each file, collects
- * violations, and outputs results in the requested format. When the `--fix`
- * flag is set, overwrites files with their auto-fixed content.
- *
- * @param files - The list of file targets (paths or inline source code) to lint.
- * @param options - CLI options controlling output format, fix mode, locale, and other behaviors.
- * @param apiOptions - Optional overrides for the underlying API (e.g., custom rules or config).
- * @returns `true` if any errors were found (or warnings exceeded the limit), `false` otherwise.
- */
 export async function command(files, options, apiOptions) {
     const fixDryRun = options.fixDryRun;
     if (options.fix && fixDryRun) {
@@ -30,9 +18,6 @@ export async function command(files, options, apiOptions) {
     // Mutual exclusion checks for suppressions flags
     const isSuppressMode = options.suppress || options.suppressRule != null;
     const isPruneMode = options.pruneSuppressions;
-    if (isSuppressMode && fix) {
-        process.stderr.write('Warning: --suppress counts violations from the original code, not from the fixed result. Consider running --fix first, then --suppress.\n');
-    }
     if (isSuppressMode && isPruneMode) {
         process.stderr.write('Error: --suppress/--suppress-rule and --prune-suppressions cannot be used together.\n');
         return true;
@@ -62,14 +47,43 @@ export async function command(files, options, apiOptions) {
     const collector = new ViolationCollector(options.maxCount);
     const processedFiles = [];
     const skippedFiles = [];
+    // `config-error` violations (deprecated rule names, unresolved rule
+    // references, ...) come from resolving this run's config, so the same
+    // message is identical across every file. Track messages already
+    // reported once so a run over many files doesn't repeat the same lines
+    // per file — the config is one thing, not N things.
+    const seenConfigMessages = new Set();
     const filesContent = new Map();
     const engines = new Map();
-    const severityParseError = options.severityParseError.toLowerCase();
-    const severity = {
-        parseError: ['error', 'warning', 'off'].includes(severityParseError)
-            ? severityParseError
-            : true,
-    };
+    const severityParseError = options.severityParseError?.toLowerCase();
+    const severity = severityParseError != null && ['error', 'warning', 'off'].includes(severityParseError)
+        ? { parseError: severityParseError }
+        : {};
+    // 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.
+    let progressiveOutput = options.progressiveOutput;
+    if (progressiveOutput && options.maxCount > 0) {
+        progressiveOutput = false;
+    }
+    if (progressiveOutput && !isSuppressMode && !isPruneMode) {
+        const suppressionsFilePathForCheck = resolveSuppressionsPath(options.suppressionsLocation);
+        const existingSuppressions = await readSuppressionsFile(suppressionsFilePathForCheck);
+        if (Object.keys(existingSuppressions).length > 0) {
+            progressiveOutput = false;
+        }
+    }
     for (const file of fileList) {
         // Check if collector is already locked (max-count reached)
         if (collector.isLocked()) {
@@ -121,11 +135,33 @@ export async function command(files, options, apiOptions) {
         });
         // Store engine for scope computation in suppressions
         engines.set(result.filePath, engine);
+        // In fix mode, report the violations remaining in the FIXED code
+        // (re-verified by ml-core) instead of the pre-fix violations, so that
+        // the exit code and suppressions reflect the written output.
+        // With --fix-dry-run the file is NOT modified, so keep the first-pass
+        // violations, which match the file on disk.
+        const violationsBeforeDedupe = fixDryRun
+            ? result.violations
+            : (result.fixSummary?.finalPassViolations ?? result.violations);
+        // `config-error` is regenerated fresh per file (config resolution is
+        // not shared across a run), so an identical message would otherwise
+        // repeat once per file. Keep only the first occurrence across this run.
+        const reportedViolations = violationsBeforeDedupe.filter(violation => {
+            if (violation.ruleId !== 'config-error') {
+                return true;
+            }
+            const key = `${violation.ruleId} ${violation.message}`;
+            if (seenConfigMessages.has(key)) {
+                return false;
+            }
+            seenConfigMessages.add(key);
+            return true;
+        });
         // Progressive出力が有効でJSON形式でない場合
-        if (options.progressiveOutput && format !== 'json') {
+        if (progressiveOutput && format !== 'json') {
             // 即座に出力
             output({
-                violations: result.violations,
+                violations: reportedViolations,
                 filePath: result.filePath,
                 sourceCode: result.sourceCode,
                 fixedCode: result.fixedCode,
@@ -133,9 +169,9 @@ export async function command(files, options, apiOptions) {
             }, options);
         }
         // Add violations to collector
-        collector.pushWithFile(result.filePath, ...result.violations);
-        const errorCount = result.violations.filter(v => v.severity === 'error').length;
-        const warningCount = result.violations.filter(v => v.severity === 'warning').length;
+        collector.pushWithFile(result.filePath, ...reportedViolations);
+        const errorCount = reportedViolations.filter(v => v.severity === 'error').length;
+        const warningCount = reportedViolations.filter(v => v.severity === 'warning').length;
         // Track total warning count across all files
         totalWarningCount += warningCount;
         if (!hasError && (errorCount > 0 || (warningCount > 0 && !options.allowWarnings))) {
@@ -250,7 +286,7 @@ export async function command(files, options, apiOptions) {
         return false;
     }
     // Progressive出力が無効の場合のみループ後に出力
-    if (!options.progressiveOutput) {
+    if (!progressiveOutput) {
         // Output per file - include processed files without violations
         for (const filePath of processedFiles) {
             const violations = outputViolationsByFile.get(filePath) || [];
@@ -290,7 +326,10 @@ export async function command(files, options, apiOptions) {
     let failedFileCount = 0;
     for (const filePath of processedFiles) {
         const violations = outputViolationsByFile.get(filePath) || [];
-        if (violations.length > 0) {
+        // A file whose only violations are `config-error` 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 particular file.
+        if (violations.some(violation => violation.ruleId !== 'config-error')) {
             failedFileCount++;
         }
         for (const violation of violations) {

package/lib/cli/dry-run-output.d.ts

@@ -1,9 +1 @@
-/**
- * Outputs a unified diff showing what --fix would change.
- * Writes the diff to stdout if there are differences.
- *
- * @param filePath - File path for the diff header
- * @param original - Original source code
- * @param fixed - Fixed source code after applying fixes
- */
 export declare function outputDryRunDiff(filePath: string, original: string, fixed: string): void;

package/lib/cli/dry-run-output.js

@@ -1,12 +1,4 @@
 import { unifiedDiff } from '@markuplint/cli-utils';
-/**
- * Outputs a unified diff showing what --fix would change.
- * Writes the diff to stdout if there are differences.
- *
- * @param filePath - File path for the diff header
- * @param original - Original source code
- * @param fixed - Fixed source code after applying fixes
- */
 export function outputDryRunDiff(filePath, original, fixed) {
     const diff = unifiedDiff(filePath, original, fixed);
     if (diff) {

package/lib/cli/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * @module cli
  *
- * CLI entry point for markuplint.
- * Parses command-line arguments, dispatches to the appropriate handler
- * (lint, init, search, or help), and manages the process exit code.
+ * Convention: all error reporting in the CLI layer must go through
+ * `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).
  */
 export {};

package/lib/cli/index.js

@@ -1,9 +1,10 @@
 /**
  * @module cli
  *
- * CLI entry point for markuplint.
- * Parses command-line arguments, dispatches to the appropriate handler
- * (lint, init, search, or help), and manages the process exit code.
+ * Convention: all error reporting in the CLI layer must go through
+ * `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).
  */
 import { text } from 'node:stream/consumers';
 import { verbosely } from '../debug.js';

package/lib/cli/init/create-config.d.ts

@@ -1,20 +1,4 @@
 import type { DefaultRules, Langs, RuleSettingMode } from './types.js';
 import type { Config } from '@markuplint/ml-config';
-/**
- * Human-readable display names for each supported template language/framework,
- * shown in the interactive init wizard prompts.
- */
 export declare const langs: Record<Langs, string>;
-/**
- * Builds a markuplint configuration object based on the user's init wizard selections.
- *
- * Configures parsers and spec modules for the selected template languages,
- * and populates rules based on the chosen rule-setting mode (custom categories,
- * recommended preset, or all defaults).
- *
- * @param langs - The template languages/frameworks selected by the user.
- * @param mode - The rule selection mode: an array of categories, `'recommended'`, or `'none'`.
- * @param defaultRules - The full set of available default rules with their categories and values.
- * @returns A complete markuplint `Config` object ready to be serialized to a file.
- */
 export declare function createConfig(langs: readonly Langs[], mode: RuleSettingMode, defaultRules: DefaultRules): Config;

package/lib/cli/init/create-config.js

@@ -1,7 +1,3 @@
-/**
- * Maps each supported language/framework to a file-extension regular expression
- * used in the generated configuration's `parser` field.
- */
 const extRExp = {
     jsx: '\\.[jt]sx?$',
     vue: '\\.vue$',
@@ -18,10 +14,6 @@ const extRExp = {
     nunjucks: '\\.nunjucks$',
     liquid: '\\.liquid$',
 };
-/**
- * Human-readable display names for each supported template language/framework,
- * shown in the interactive init wizard prompts.
- */
 export const langs = {
     jsx: 'React (JSX)',
     vue: 'Vue',
@@ -38,18 +30,6 @@ export const langs = {
     nunjucks: 'Nunjucks',
     liquid: 'liquid (Shopify)',
 };
-/**
- * Builds a markuplint configuration object based on the user's init wizard selections.
- *
- * Configures parsers and spec modules for the selected template languages,
- * and populates rules based on the chosen rule-setting mode (custom categories,
- * recommended preset, or all defaults).
- *
- * @param langs - The template languages/frameworks selected by the user.
- * @param mode - The rule selection mode: an array of categories, `'recommended'`, or `'none'`.
- * @param defaultRules - The full set of available default rules with their categories and values.
- * @returns A complete markuplint `Config` object ready to be serialized to a file.
- */
 export function createConfig(langs, mode, defaultRules) {
     let config = {};
     const parser = { ...config.parser };

package/lib/cli/init/get-default-rules.d.ts

@@ -1,12 +1,3 @@
-/**
- * Collects all built-in rules that have a defined category and returns them
- * as a record of rule name to rule metadata.
- *
- * Rules with `'warning'` default severity are disabled by default (`false`),
- * while all others use their defined default value or `true`.
- *
- * @returns A read-only mapping from rule names to their category and default configuration value.
- */
 export declare function getDefaultRules(): {
     [x: string]: import("./types.js").Rule;
 };

package/lib/cli/init/get-default-rules.js

@@ -1,13 +1,4 @@
 import builtinRules from '@markuplint/rules';
-/**
- * Collects all built-in rules that have a defined category and returns them
- * as a record of rule name to rule metadata.
- *
- * Rules with `'warning'` default severity are disabled by default (`false`),
- * while all others use their defined default value or `true`.
- *
- * @returns A read-only mapping from rule names to their category and default configuration value.
- */
 export function getDefaultRules() {
     const rules = {};
     for (const [ruleName, rule] of Object.entries(builtinRules)) {

package/lib/cli/init/index.d.ts

@@ -1,15 +1 @@
-/**
- * @module cli/init
- *
- * Interactive initialization wizard for markuplint.
- * Guides the user through selecting template engines, rule categories,
- * and dependency installation, then writes a `.markuplintrc` config file.
- */
-/**
- * Runs the interactive initialization flow.
- *
- * Prompts the user to select template engines, choose rule categories or the
- * recommended preset, generates a `.markuplintrc` configuration file in the
- * current working directory, and optionally installs the required npm packages.
- */
 export declare function initialize(): Promise<void>;