markuplint 5.0.0-dev.5 → 5.0.0-rc.1

package/ARCHITECTURE.ja.md

@@ -146,7 +146,7 @@ flowchart TD
     ExcludeCheck -->|No| ResolveParser["resolveParser()\n パーサーモジュール選択"]
     ResolveParser --> ExtCheck{"拡張子が一致?\n(--ignore-ext でなければ)"}
     ExtCheck -->|No| ReturnNull3["null を返却"]
-    ExtCheck -->|Yes| ResolvePretenders["resolvePretenders()"]
+    ExtCheck -->|Yes| ResolvePretenders["resolvePretenders()\n files + imports + data + scan"]
     ResolvePretenders --> ResolveRuleset["resolveRuleset()\n convertRuleset()"]
     ResolveRuleset --> ResolveSchemas["resolveSchemas()"]
     ResolveSchemas --> ResolveRules["resolveRules()\n プラグイン + カスタムルール"]

package/ARCHITECTURE.md

@@ -146,7 +146,7 @@ flowchart TD
     ExcludeCheck -->|No| ResolveParser["resolveParser()\n parser module selection"]
     ResolveParser --> ExtCheck{"extension matched?\n(unless --ignore-ext)"}
     ExtCheck -->|No| ReturnNull3["Return null"]
-    ExtCheck -->|Yes| ResolvePretenders["resolvePretenders()"]
+    ExtCheck -->|Yes| ResolvePretenders["resolvePretenders()\n files + imports + data + scan"]
     ResolvePretenders --> ResolveRuleset["resolveRuleset()\n convertRuleset()"]
     ResolveRuleset --> ResolveSchemas["resolveSchemas()"]
     ResolveSchemas --> ResolveRules["resolveRules()\n plugins + custom rules"]

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 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.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
+
+- **markuplint:** guard Error.stack access for Deno source map compat ([40508a3](https://github.com/markuplint/markuplint/commit/40508a3e25a9ed84f84f63adc95cc524628b9468))
+
 # [5.0.0-alpha.3](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.2...v5.0.0-alpha.3) (2026-02-26)
 
 ### Features

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)
@@ -130,11 +173,8 @@ Examples
 ### Personal Supporters
 
 [<img width="36" src="https://avatars.githubusercontent.com/u/91733847" alt="Tokitake" />](https://github.com/Tokitake)
-[<img width="36" src="https://avatars.githubusercontent.com/u/1996642" alt="Okuto Oyama" />](https://github.com/yamanoku)
-[<img width="36" src="https://avatars.githubusercontent.com/u/6581173" alt="miita" />](https://github.com/mikimhk)
 [<img width="36" src="https://avatars.githubusercontent.com/u/111797" alt="Yasuo Fukuda" />](https://github.com/sigwyg)
 [<img width="36" src="https://avatars.githubusercontent.com/u/91047157" alt="shamokit" />](https://github.com/shamokit)
-[<img width="36" src="https://avatars.githubusercontent.com/u/18516475" alt="takanorip" />](https://github.com/takanorip)
 
 Need [Sponsors❤️‍🔥](https://github.com/sponsors/markuplint)
 

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;
             }
@@ -104,7 +108,15 @@ export class MLEngine extends Emitter {
         const sourceCode = await this.#file.getCode();
         if (verifyResult instanceof Error) {
             this.emit('lint-error', this.#file.path, sourceCode, verifyResult);
-            const errMessage = verifyResult.stack ?? verifyResult.message;
+            // Accessing `.stack` can throw in Deno when source map resolution
+            // encounters invalid mappings (e.g., negative column values).
+            let errMessage;
+            try {
+                errMessage = verifyResult.stack ?? verifyResult.message;
+            }
+            catch {
+                errMessage = verifyResult.message;
+            }
             log('exec: error %O', errMessage);
             return {
                 violations: [

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,8 +2,10 @@ 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';
 /**
@@ -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,8 @@ export async function command(files, options, apiOptions) {
         if (!result) {
             continue;
         }
+        // Store engine for scope computation in suppressions
+        engines.set(result.filePath, engine);
         // Progressive出力が有効でJSON形式でない場合
         if (options.progressiveOutput && format !== 'json') {
             // 即座に出力
@@ -137,19 +152,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');

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;

package/lib/suppressions/apply-suppressions.js

@@ -0,0 +1,221 @@
+import { findNodeAtPosition } from './compute-scope.js';
+import { toRelativePath } from './suppressions-file.js';
+/**
+ * Checks whether a violation at (line, col) is within the subtree of a node
+ * that matches the scope selector. Walks the violation node's ancestors
+ * to find a match.
+ */
+function isViolationInScope(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+nodeList, violation, scope) {
+    const violationNode = findNodeAtPosition(nodeList, violation.line, violation.col);
+    if (!violationNode) {
+        return false;
+    }
+    // Check the node itself and walk up ancestors
+    if (matchesScopeSelector(violationNode, scope)) {
+        return true;
+    }
+    let current = violationNode.parentElement;
+    while (current) {
+        if (matchesScopeSelector(current, scope)) {
+            return true;
+        }
+        current = current.parentElement;
+    }
+    return false;
+}
+/**
+ * Simple scope selector matching. Checks if a node matches a scope selector
+ * by matching segments right-to-left against the node and its ancestors.
+ *
+ * Supports: `#id`, `tag.class`, `tag`, and ancestor paths like `#id > tag`.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function matchesScopeSelector(node, scope) {
+    const segments = scope.split(' > ');
+    let current = node;
+    // Match segments from right (most specific) to left (ancestors)
+    for (let i = segments.length - 1; i >= 0; i--) {
+        if (!current) {
+            return false;
+        }
+        if (!matchesSegment(current, segments[i])) {
+            return false;
+        }
+        current = current.parentElement;
+    }
+    return true;
+}
+/**
+ * Matches a single selector segment against a node.
+ * Supports: `#id`, `tag[attr="value"]`, `tag.classA.classB`,
+ * `tag:nth-of-type(n)`, `tag`
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function matchesSegment(node, segment) {
+    if (segment.length === 0) {
+        return false;
+    }
+    // #id
+    if (segment.startsWith('#')) {
+        const id = segment.slice(1);
+        return id.length > 0 && node.id === id;
+    }
+    // tag[attr="value"]
+    const attrMatch = /^([a-z-]+)\[([a-z-]+)="([^"]+)"\]$/.exec(segment);
+    if (attrMatch) {
+        const [, tag, attrName, attrValue] = attrMatch;
+        if (node.localName !== tag) {
+            return false;
+        }
+        for (const attr of node.attributes) {
+            if (attr.name === attrName && attr.value === attrValue) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // Extract :nth-of-type(n) if present
+    const nthMatch = /:nth-of-type\((\d+)\)$/.exec(segment);
+    const baseSegment = nthMatch ? segment.slice(0, nthMatch.index) : segment;
+    // tag.classA.classB
+    const dotIndex = baseSegment.indexOf('.');
+    let tagMatches;
+    if (dotIndex === -1) {
+        // tag only
+        tagMatches = node.localName === baseSegment;
+    }
+    else {
+        const tag = baseSegment.slice(0, dotIndex);
+        const classes = baseSegment.slice(dotIndex + 1).split('.');
+        tagMatches = node.localName === tag && classes.every(cls => node.classList.contains(cls));
+    }
+    if (!tagMatches) {
+        return false;
+    }
+    // Check nth-of-type position
+    if (nthMatch) {
+        const expectedPosition = Number.parseInt(nthMatch[1], 10);
+        const parent = node.parentElement;
+        if (!parent) {
+            return false;
+        }
+        let position = 0;
+        for (const sibling of parent.children) {
+            if (sibling.localName === node.localName) {
+                position++;
+                if (sibling === node) {
+                    return position === expectedPosition;
+                }
+            }
+        }
+        return false;
+    }
+    return true;
+}
+/**
+ * @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 function applySuppressions(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+violationsByFile, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+suppressions, suppressionsFilePath, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+options) {
+    const filtered = new Map();
+    const usedEntries = new Set();
+    const nodeLists = options?.nodeLists;
+    for (const [absolutePath, violations] of violationsByFile) {
+        const relPath = toRelativePath(absolutePath, suppressionsFilePath);
+        const fileSuppressions = suppressions[relPath];
+        if (!fileSuppressions) {
+            filtered.set(absolutePath, [...violations]);
+            continue;
+        }
+        const nodeList = nodeLists?.get(absolutePath);
+        // Build a set of suppressed rules and their scoped violation indices.
+        // For scope-aware entries, we track WHICH specific violations are in scope
+        // so we can suppress only those, not all violations of the same ruleId.
+        const suppressedViolationIndices = new Set();
+        for (const [ruleId, entry] of Object.entries(fileSuppressions)) {
+            const { count: scopedCount, indices } = getScopedErrorInfo(violations, ruleId, entry, nodeList);
+            if (scopedCount > 0 && scopedCount <= entry.count) {
+                // Scoped count within threshold — suppress these specific violations
+                for (const idx of indices) {
+                    suppressedViolationIndices.add(idx);
+                }
+            }
+            if (scopedCount > 0) {
+                usedEntries.add(`${relPath}:${ruleId}`);
+            }
+        }
+        // Filter violations — only remove specifically identified violations
+        const fileFiltered = [];
+        for (const [i, violation] of violations.entries()) {
+            if (suppressedViolationIndices.has(i)) {
+                continue;
+            }
+            fileFiltered.push(violation);
+        }
+        filtered.set(absolutePath, fileFiltered);
+    }
+    // Find unused entries
+    const unusedEntries = [];
+    for (const [relPath, rules] of Object.entries(suppressions)) {
+        for (const ruleId of Object.keys(rules)) {
+            const key = `${relPath}:${ruleId}`;
+            if (!usedEntries.has(key)) {
+                unusedEntries.push(key);
+            }
+        }
+    }
+    return { filtered, unusedEntries };
+}
+/**
+ * Gets the scoped error count and indices for a rule.
+ * When scope is present and nodeList is available, only counts/tracks violations
+ * within the scope subtree. Otherwise counts all error violations for the rule.
+ *
+ * @returns The count and array indices of matching violations.
+ */
+function getScopedErrorInfo(violations, ruleId, entry, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+nodeList) {
+    let count = 0;
+    const indices = [];
+    for (const [i, violation] of violations.entries()) {
+        const v = violation;
+        if (v.severity !== 'error' || v.ruleId !== ruleId) {
+            continue;
+        }
+        if (entry.scope && nodeList) {
+            if (isViolationInScope(nodeList, v, entry.scope)) {
+                count++;
+                indices.push(i);
+            }
+        }
+        else {
+            count++;
+            indices.push(i);
+        }
+    }
+    return { count, indices };
+}