markuplint 5.0.0-rc.0 → 5.0.0-rc.2

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 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.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
+
+### Bug Fixes
+
+- **markuplint:** add default export condition and re-export isFatalError ([55a990a](https://github.com/markuplint/markuplint/commit/55a990affeec62c23a96cf15b42327fcb867e809))
+- **markuplint:** add missing status property to github-reporter test data ([bb7ba62](https://github.com/markuplint/markuplint/commit/bb7ba62e9350c173987f76de2741aaeb3ba0997b))
+
+- build!: remove ESLint and replace with oxlint ([1e0a337](https://github.com/markuplint/markuplint/commit/1e0a337707f76b903b16beeeb8c4d4fc0d8fc9e4))
+- feat(markuplint)!: remove deprecated autoLoad option and MLResultInfo_v1 interface ([4eb1d05](https://github.com/markuplint/markuplint/commit/4eb1d05eb2829019cd4073afa153a512b1c4c8fa))
+
+### Features
+
+- **config-presets:** add document uniqueness rules to html-standard preset ([6ed848b](https://github.com/markuplint/markuplint/commit/6ed848bd800416d1220b9de95ece7a3d752d881f))
+- **markuplint:** add CLI summary output ([4743ba0](https://github.com/markuplint/markuplint/commit/4743ba0be7311288ea2b28fb9345567cf97c1a23))
+- **markuplint:** add suppressions subpath export and editor severity downgrade ([362adef](https://github.com/markuplint/markuplint/commit/362adef1a040c66fec36c01bd8d8fcbe9a66c453))
+- **vscode:** add suppressed message prefix and blame parser tests ([cd80a80](https://github.com/markuplint/markuplint/commit/cd80a802c3bad29a8a1d510d2160a21a6f0a2682))
+
+### BREAKING CHANGES
+
+- ESLint is no longer used. Use oxlint instead.
+- The autoLoad option has been removed from APIOptions.
+  Rules are now always auto-loaded unconditionally.
+  The MLResultInfo_v1 interface has also been removed.
+
+# [5.0.0-rc.1](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.0...v5.0.0-rc.1) (2026-03-27)
+
+### Bug Fixes
+
+- add isFatalError guard to MLEngine.exec and fix accname Deno crash ([c4b20de](https://github.com/markuplint/markuplint/commit/c4b20de128b2cfee582b3588e5004cb90065825b))
+- **markuplint:** use platform-native paths in suppressions round-trip test ([df4b6a5](https://github.com/markuplint/markuplint/commit/df4b6a5f83b0fed3f74afba72cccd7bc2dbf8606))
+
+### Features
+
+- **markuplint:** add experimental bulk suppressions ([bd3ab72](https://github.com/markuplint/markuplint/commit/bd3ab7204870dd6061e8e4ccbeaacd751d069a73)), closes [#3503](https://github.com/markuplint/markuplint/issues/3503)
+- **markuplint:** add selector scope (LCA) to bulk suppressions ([84cf73d](https://github.com/markuplint/markuplint/commit/84cf73dd92db49f1f93ff6a5c9b71c7807ce31e9)), closes [#3509](https://github.com/markuplint/markuplint/issues/3509)
+
 # [5.0.0-rc.0](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.3...v5.0.0-rc.0) (2026-03-12)
 
 ### Bug Fixes

package/README.md

@@ -89,6 +89,12 @@ Options
 	--severity-parse-error                 Specifies the severity level of parse errors. Supports "error", "warning", and "off". Default: "error".
 	--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.
+
+	--suppress                             [Experimental] Generate/update suppressions file for all current errors.
+	--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.
+	--prune-suppressions                   [Experimental] Remove stale entries from the suppressions file.
+	--suppressions-location PATH           [Experimental] Custom path for the suppressions file. Default: "markuplint-suppressions.json".
 
 	--init                                 Initialize settings interactively.
 	--search                               Search lines of codes that include the target element by selectors.
@@ -102,6 +108,43 @@ Examples
 	$ cat verifyee.html | markuplint
 ```
 
+### Bulk Suppressions (Experimental)
+
+> **This feature is experimental and may change in future releases.**
+
+When introducing new rules to an existing project, you can suppress current violations and enforce rules only on new code.
+
+**Typical workflow:**
+
+```bash
+# 1. Enable new rules in your config, then suppress all current errors
+$ markuplint --suppress "src/**/*.html"
+
+# 2. Commit the generated suppressions file to your repository
+$ git add markuplint-suppressions.json
+
+# 3. From now on, only new violations are reported
+$ markuplint "src/**/*.html"
+
+# 4. As you fix existing violations, clean up stale entries
+$ 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).
+- 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
+{
+  "src/index.html": {
+    "attr-duplication": { "count": 3, "scope": "#main-nav > ul" }
+  }
+}
+```
+
+See [ESLint's Bulk Suppressions](https://eslint.org/docs/latest/use/suppressions) for the reference design. Tracking issues: [#3503](https://github.com/markuplint/markuplint/issues/3503), [#3509](https://github.com/markuplint/markuplint/issues/3509).
+
 ## Documentation
 
 - [Getting Started](https://markuplint.dev/getting-started)

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 { MLCore, convertRuleset } from '@markuplint/ml-core';
+import { isFatalError } from '@markuplint/shared';
 import { FSWatcher } from 'chokidar';
 import { Emitter } from 'strict-event-emitter';
 import { log as coreLog, verbosely } from '../debug.js';
@@ -96,6 +97,9 @@ export class MLEngine extends Emitter {
             return null;
         }
         const verifyResult = await core.verify({ fix: this.#options?.fix ?? false }).catch(error => {
+            if (isFatalError(error)) {
+                throw error;
+            }
             if (error instanceof Error) {
                 return error;
             }
@@ -337,7 +341,7 @@ export class MLEngine extends Emitter {
         return pretenders;
     }
     async #resolveRules(plugins, ruleset) {
-        const rules = await resolveRules(plugins, ruleset, this.#options?.importPresetRules ?? true, this.#options?.autoLoad ?? true);
+        const rules = await resolveRules(plugins, ruleset, this.#options?.importPresetRules ?? true);
         if (this.#options?.rules) {
             rules.push(...this.#options.rules);
         }

package/lib/api/types.d.ts

@@ -18,10 +18,6 @@ export type APIOptions = {
     readonly rules?: readonly Readonly<AnyMLRule>[];
     readonly importPresetRules?: boolean;
     readonly severity?: SeverityOptions;
-    /**
-     * @deprecated
-     */
-    readonly autoLoad?: boolean;
 };
 /**
  * Event map for the {@link MLEngine}, defining all emitted events and their payload types.

package/lib/cli/bootstrap.d.ts

@@ -3,7 +3,7 @@ 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--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\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`).
@@ -95,6 +95,20 @@ export declare const cli: import("meow").Result<{
         type: "boolean";
         default: false;
     };
+    suppress: {
+        type: "boolean";
+        default: false;
+    };
+    suppressRule: {
+        type: "string";
+    };
+    pruneSuppressions: {
+        type: "boolean";
+        default: false;
+    };
+    suppressionsLocation: {
+        type: "string";
+    };
 }>;
 /**
  * Deeply read-only type representing the parsed CLI flags.

package/lib/cli/bootstrap.js

@@ -29,6 +29,11 @@ Options
 	--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.
 
+	--suppress                             [Experimental] Generate/update suppressions file for all current errors.
+	--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.
+	--prune-suppressions                   [Experimental] Remove stale entries from the suppressions file.
+	--suppressions-location PATH           [Experimental] Custom path for the suppressions file. Default: "markuplint-suppressions.json".
+
 	--init                                 Initialize settings interactively.
 	--search                               Search lines of codes that include the target element by selectors.
 
@@ -133,5 +138,19 @@ export const cli = meow(help, {
             // TODO: It will be changed to `true` in the next major version.
             default: false,
         },
+        suppress: {
+            type: 'boolean',
+            default: false,
+        },
+        suppressRule: {
+            type: 'string',
+        },
+        pruneSuppressions: {
+            type: 'boolean',
+            default: false,
+        },
+        suppressionsLocation: {
+            type: 'string',
+        },
     },
 });

package/lib/cli/command.js

@@ -2,10 +2,12 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { 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 { outputDryRunDiff } from './dry-run-output.js';
-import { output } from './output.js';
+import { output, outputSummary } from './output.js';
 /**
  * Executes the markuplint linting command against the given files.
  *
@@ -25,6 +27,16 @@ export async function command(files, options, apiOptions) {
         process.stderr.write('Warning: --fix-dry-run takes precedence over --fix. Files will not be modified.\n');
     }
     const fix = options.fix || fixDryRun;
+    // 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;
+    }
     const configFile = options.config &&
         (path.isAbsolute(options.config) ? options.config : path.resolve(process.cwd(), options.config));
     const locale = options.locale;
@@ -51,6 +63,7 @@ export async function command(files, options, apiOptions) {
     const processedFiles = [];
     const skippedFiles = [];
     const filesContent = new Map();
+    const engines = new Map();
     const severityParseError = options.severityParseError.toLowerCase();
     const severity = {
         parseError: ['error', 'warning', 'off'].includes(severityParseError)
@@ -101,6 +114,13 @@ export async function command(files, options, apiOptions) {
         if (!result) {
             continue;
         }
+        processedFiles.push(result.filePath);
+        filesContent.set(result.filePath, {
+            sourceCode: result.sourceCode,
+            fixedCode: result.fixedCode,
+        });
+        // Store engine for scope computation in suppressions
+        engines.set(result.filePath, engine);
         // Progressive出力が有効でJSON形式でない場合
         if (options.progressiveOutput && format !== 'json') {
             // 即座に出力
@@ -112,14 +132,6 @@ export async function command(files, options, apiOptions) {
                 status: 'processed',
             }, options);
         }
-        else {
-            // 従来の動作：メモリに蓄積
-            processedFiles.push(result.filePath);
-            filesContent.set(result.filePath, {
-                sourceCode: result.sourceCode,
-                fixedCode: result.fixedCode,
-            });
-        }
         // Add violations to collector
         collector.pushWithFile(result.filePath, ...result.violations);
         const errorCount = result.violations.filter(v => v.severity === 'error').length;
@@ -137,19 +149,111 @@ export async function command(files, options, apiOptions) {
             outputDryRunDiff(result.filePath, result.sourceCode, result.fixedCode);
         }
     }
+    // --- Suppressions handling ---
+    const suppressionsFilePath = resolveSuppressionsPath(options.suppressionsLocation);
+    const collectedViolationsByFile = collector.groupByFile();
+    // Build nodeLists map from engines for scope computation
+    const nodeLists = new Map();
+    for (const [filePath, engine] of engines) {
+        const doc = engine.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(filePath, doc.nodeList);
+        }
+    }
+    if (isSuppressMode) {
+        // Suppress mode: generate/update suppressions file
+        const existing = await readSuppressionsFile(suppressionsFilePath);
+        const generated = generateSuppressions(collectedViolationsByFile, suppressionsFilePath, {
+            filterRule: options.suppressRule,
+            nodeLists,
+        });
+        const merged = mergeSuppressions(existing, generated);
+        await writeSuppressionsFile(suppressionsFilePath, merged);
+        let totalSuppressed = 0;
+        let totalRules = 0;
+        for (const rules of Object.values(generated)) {
+            for (const entry of Object.values(rules)) {
+                totalSuppressed += entry.count;
+                totalRules++;
+            }
+        }
+        process.stderr.write(`[Experimental] ${totalSuppressed} violation(s) for ${totalRules} rule(s) suppressed in ${path.relative(process.cwd(), suppressionsFilePath)}\n`);
+        return false;
+    }
+    if (isPruneMode) {
+        // Prune mode: remove stale entries
+        const existing = await readSuppressionsFile(suppressionsFilePath);
+        if (Object.keys(existing).length === 0) {
+            process.stderr.write('No suppressions file found. Nothing to prune.\n');
+            return false;
+        }
+        const pruned = pruneSuppressions(collectedViolationsByFile, existing, 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);
+        const removedCount = existingCount - prunedCount;
+        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 {
+        await fs.access(suppressionsFilePath);
+        const suppressionsData = await readSuppressionsFile(suppressionsFilePath);
+        if (Object.keys(suppressionsData).length > 0) {
+            const { filtered, unusedEntries } = applySuppressions(collectedViolationsByFile, suppressionsData, 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;
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        // Suppressions file does not exist or is unreadable, proceed normally
+    }
     // Output results
     if (format === 'json') {
-        const jsonOutput = collector.toArray();
-        process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
+        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;
     }
     // Progressive出力が無効の場合のみループ後に出力
     if (!options.progressiveOutput) {
-        // For standard/simple/github output, group violations by file
-        const violationsByFile = collector.groupByFile();
         // Output per file - include processed files without violations
         for (const filePath of processedFiles) {
-            const violations = violationsByFile.get(filePath) || [];
+            const violations = outputViolationsByFile.get(filePath) || [];
             const content = filesContent.get(filePath) || { sourceCode: '', fixedCode: '' };
             if (violations.length === 0 && !options.problemOnly) {
                 log('Output reports');
@@ -180,6 +284,40 @@ export async function command(files, options, apiOptions) {
             }
         }
     }
+    let errorCount = 0;
+    let warningCount = 0;
+    let noticeCount = 0;
+    let failedFileCount = 0;
+    for (const filePath of processedFiles) {
+        const violations = outputViolationsByFile.get(filePath) || [];
+        if (violations.length > 0) {
+            failedFileCount++;
+        }
+        for (const violation of violations) {
+            switch (violation.severity) {
+                case 'error': {
+                    errorCount++;
+                    break;
+                }
+                case 'warning': {
+                    warningCount++;
+                    break;
+                }
+                case 'info': {
+                    noticeCount++;
+                    break;
+                }
+            }
+        }
+    }
+    outputSummary({
+        checkedFileCount: processedFiles.length,
+        failedFileCount,
+        skippedFileCount: skippedFiles.length,
+        errorCount,
+        warningCount,
+        noticeCount,
+    }, options);
     // Check if max-warnings limit is exceeded (ESLint compatible)
     if (!hasError && options.maxWarnings >= 0 && totalWarningCount > options.maxWarnings) {
         hasError = true;

package/lib/cli/output.d.ts

@@ -1,5 +1,13 @@
 import type { CLIOptions } from './bootstrap.js';
 import type { MLResultInfo } from '../types.js';
+export interface SummaryInfo {
+    readonly checkedFileCount: number;
+    readonly failedFileCount: number;
+    readonly skippedFileCount: number;
+    readonly errorCount: number;
+    readonly warningCount: number;
+    readonly noticeCount: number;
+}
 /**
  * Writes lint results to stdout or stderr using the reporter selected by `--format`.
  *
@@ -12,3 +20,14 @@ import type { MLResultInfo } from '../types.js';
  * @param options - CLI options that control the output format and color.
  */
 export declare function output(results: MLResultInfo, options: CLIOptions): void;
+/**
+ * Writes an aggregated lint summary after all file outputs have been emitted.
+ *
+ * Summary output is enabled for the standard and simple formats only.
+ * JSON and GitHub formats are left unchanged because they are intended for
+ * machine-readable output.
+ *
+ * @param summary - Aggregated counts across all linted files.
+ * @param options - CLI options that control the output format and color.
+ */
+export declare function outputSummary(summary: SummaryInfo, options: CLIOptions): void;

package/lib/cli/output.js

@@ -1,5 +1,8 @@
+import { font, xterm } from '@markuplint/cli-utils';
 import stripAnsi from 'strip-ansi';
 import { simpleReporter, standardReporter, githubReporter } from '../reporter/index.js';
+const loggerError = font.red;
+const loggerWarning = xterm(208);
 /**
  * Writes lint results to stdout or stderr using the reporter selected by `--format`.
  *
@@ -43,3 +46,63 @@ export function output(results, options) {
     }
     process.stdout.write(msg);
 }
+/**
+ * Writes an aggregated lint summary after all file outputs have been emitted.
+ *
+ * Summary output is enabled for the standard and simple formats only.
+ * JSON and GitHub formats are left unchanged because they are intended for
+ * machine-readable output.
+ *
+ * @param summary - Aggregated counts across all linted files.
+ * @param options - CLI options that control the output format and color.
+ */
+export function outputSummary(summary, options) {
+    const format = options.format?.toLowerCase() ?? 'standard';
+    if (format === 'json' || format === 'github') {
+        return;
+    }
+    if (summary.checkedFileCount === 0 && summary.skippedFileCount === 0) {
+        return;
+    }
+    const problemCount = summary.errorCount + summary.warningCount + summary.noticeCount;
+    if (options.problemOnly && problemCount === 0) {
+        return;
+    }
+    const out = createSummaryLines(summary);
+    if (out.length === 0) {
+        return;
+    }
+    let msg = `\n${out.join('\n')}\n`;
+    msg = options.color ? msg : stripAnsi(msg);
+    if (problemCount > 0) {
+        process.stderr.write(msg);
+        return;
+    }
+    process.stdout.write(msg);
+}
+function createSummaryLines(summary) {
+    const out = [];
+    const problemCount = summary.errorCount + summary.warningCount + summary.noticeCount;
+    const passedFileCount = summary.checkedFileCount - summary.failedFileCount;
+    if (problemCount === 0) {
+        out.push(`${font.green('✔')} ${pluralize(summary.checkedFileCount, 'file')} checked, 0 problems`);
+    }
+    else {
+        const problemDetail = [
+            `${summary.errorCount} error${summary.errorCount === 1 ? '' : 's'}`,
+            `${summary.warningCount} warning${summary.warningCount === 1 ? '' : 's'}`,
+            summary.noticeCount > 0 ? `${summary.noticeCount} notice${summary.noticeCount === 1 ? '' : 's'}` : null,
+        ]
+            .filter(Boolean)
+            .join(', ');
+        const logger = summary.errorCount > 0 ? loggerError : loggerWarning;
+        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`);
+    }
+    return out;
+}
+function pluralize(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}

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

@@ -0,0 +1,45 @@
+import type { Violation } from '@markuplint/ml-config';
+import type { PositionedNode } from './compute-scope.js';
+import type { SuppressionsData } from './types.js';
+/**
+ * @experimental
+ * Result of applying suppressions to violations.
+ */
+export type ApplySuppressionsResult = {
+    /** Violations after filtering out suppressed ones. */
+    readonly filtered: Map<string, Violation[]>;
+    /** List of unused suppression entries (as "filePath:ruleId" strings). */
+    readonly unusedEntries: readonly string[];
+};
+/**
+ * @experimental
+ * Options for applying suppressions.
+ */
+export type ApplySuppressionsOptions = {
+    /**
+     * Map of absolute file paths to their document node lists.
+     * When provided, scope-aware filtering is used.
+     * When absent, scope is ignored (Phase 1 compatible).
+     */
+    readonly nodeLists?: ReadonlyMap<string, readonly PositionedNode[]>;
+};
+/**
+ * @experimental
+ * Applies suppressions to collected violations.
+ *
+ * For each file+ruleId pair:
+ * - If the entry has a `scope`, only violations within that scope subtree are
+ *   counted AND filtered. Violations outside the scope are always passed through.
+ * - If current scoped error count <= suppressed count: scoped error violations are removed.
+ * - If current scoped error count > suppressed count: ALL scoped violations are kept.
+ *
+ * Warning and info violations always pass through unmodified.
+ * When `options.nodeLists` is not provided, scope is ignored (Phase 1 compatible).
+ *
+ * @param violationsByFile - Map of absolute file paths to violations.
+ * @param suppressions - The loaded suppressions data.
+ * @param suppressionsFilePath - Absolute path to the suppressions file.
+ * @param options - Optional options including document node lists for scope-aware filtering.
+ * @returns Filtered violations and a list of unused suppression entries.
+ */
+export declare function applySuppressions(violationsByFile: ReadonlyMap<string, readonly Violation[]>, suppressions: SuppressionsData, suppressionsFilePath: string, options?: ApplySuppressionsOptions): ApplySuppressionsResult;