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

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

@@ -0,0 +1,96 @@
+/**
+ * @experimental
+ * Scope computation for bulk suppressions (Phase 2).
+ * Computes the Lowest Common Ancestor (LCA) of violation nodes and generates
+ * a minimal CSS selector to identify the subtree containing all violations.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3509
+ */
+import type { Violation } from '@markuplint/ml-config';
+/**
+ * @experimental
+ * Minimal node interface for scope computation.
+ * Defined as a standalone interface (rather than importing `SelectorElement`
+ * from `@markuplint/selector`) to avoid coupling the `markuplint` package
+ * to the selector package's internal types. Both `SelectorElement` and
+ * `MLElement` satisfy this interface via structural typing.
+ */
+export interface ScopedNode {
+    readonly nodeType: number;
+    readonly localName: string;
+    readonly id: string;
+    readonly classList: Iterable<string> & {
+        contains(className: string): boolean;
+    };
+    readonly attributes: Iterable<{
+        readonly name: string;
+        readonly value: string;
+    }>;
+    readonly parentElement: ScopedNode | null;
+    readonly children: Iterable<ScopedNode>;
+}
+/**
+ * @experimental
+ * Node with position information for reverse-lookup from violations.
+ */
+export interface PositionedNode extends ScopedNode {
+    readonly startLine: number;
+    readonly startCol: number;
+}
+/**
+ * @experimental
+ * Returns the ancestor chain from the node's parent up to (but not including) the root.
+ * Only includes element nodes.
+ *
+ * @param node - The starting node.
+ * @returns Array of ancestor elements, closest first.
+ */
+export declare function getAncestorChain(node: ScopedNode): ScopedNode[];
+/**
+ * @experimental
+ * Computes the Lowest Common Ancestor (LCA) of a set of nodes.
+ * Returns null if the LCA is `body`, `html`, or the input is empty.
+ *
+ * @param nodes - The nodes to find the LCA for.
+ * @returns The LCA node, or null if it falls back to file-level.
+ */
+export declare function computeLCA(nodes: readonly ScopedNode[]): ScopedNode | null;
+/**
+ * @experimental
+ * Generates a minimal CSS selector that uniquely identifies the given node.
+ *
+ * Strategy:
+ * 1. If the node has an `id`, use `#id` (most unique)
+ * 2. If the node has classes, use `tag.class`
+ * 3. Otherwise, build an ancestor path using `>` combinators, stopping at
+ *    the first ancestor with an `id`
+ *
+ * Returns `undefined` for `body` or `html` nodes (file-level fallback).
+ *
+ * @param node - The node to generate a selector for.
+ * @returns A CSS selector string, or undefined for file-level scope.
+ */
+export declare function generateUniqueSelector(node: ScopedNode): string | undefined;
+/**
+ * @experimental
+ * Finds the element node at the given line/col position in the node list.
+ * If the position matches a non-element node (e.g., attribute), walks up
+ * to the nearest parent element.
+ *
+ * @param nodeList - Flat list of all nodes in the document.
+ * @param line - 1-based line number.
+ * @param col - 1-based column number.
+ * @returns The element node at the position, or null if not found.
+ */
+export declare function findNodeAtPosition(nodeList: readonly PositionedNode[], line: number, col: number): ScopedNode | null;
+/**
+ * @experimental
+ * Computes the scope selector for a set of violations within a document.
+ * Only considers error-severity violations. Returns `undefined` when
+ * the LCA falls back to file-level (body/html) or when nodes cannot be found.
+ *
+ * @param nodeList - Flat list of all nodes in the document.
+ * @param violations - The violations to compute scope for.
+ * @returns A CSS selector string, or undefined for file-level scope.
+ */
+export declare function computeScopeForViolations(nodeList: readonly PositionedNode[], violations: readonly Violation[]): string | undefined;

package/lib/suppressions/compute-scope.js

@@ -0,0 +1,244 @@
+/**
+ * @experimental
+ * Scope computation for bulk suppressions (Phase 2).
+ * Computes the Lowest Common Ancestor (LCA) of violation nodes and generates
+ * a minimal CSS selector to identify the subtree containing all violations.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3509
+ */
+const BODY_HTML_TAGS = new Set(['body', 'html']);
+/**
+ * @experimental
+ * Returns the ancestor chain from the node's parent up to (but not including) the root.
+ * Only includes element nodes.
+ *
+ * @param node - The starting node.
+ * @returns Array of ancestor elements, closest first.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+export function getAncestorChain(node) {
+    const chain = [];
+    let current = node.parentElement;
+    while (current) {
+        chain.push(current);
+        current = current.parentElement;
+    }
+    return chain;
+}
+/**
+ * @experimental
+ * Computes the Lowest Common Ancestor (LCA) of a set of nodes.
+ * Returns null if the LCA is `body`, `html`, or the input is empty.
+ *
+ * @param nodes - The nodes to find the LCA for.
+ * @returns The LCA node, or null if it falls back to file-level.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+export function computeLCA(nodes) {
+    if (nodes.length === 0) {
+        return null;
+    }
+    if (nodes.length === 1) {
+        const parent = nodes[0].parentElement;
+        if (!parent || BODY_HTML_TAGS.has(parent.localName)) {
+            return null;
+        }
+        return parent;
+    }
+    // Get ancestor chains for all nodes (including the node itself)
+    const chains = nodes.map(node => {
+        const chain = [node, ...getAncestorChain(node)];
+        // Reverse so root is first
+        chain.reverse();
+        return chain;
+    });
+    // Walk from root, find deepest common ancestor
+    const minLength = Math.min(...chains.map(c => c.length));
+    let lca = null;
+    for (let i = 0; i < minLength; i++) {
+        const candidate = chains[0][i];
+        if (chains.every(chain => chain[i] === candidate)) {
+            lca = candidate;
+        }
+        else {
+            break;
+        }
+    }
+    if (!lca || BODY_HTML_TAGS.has(lca.localName)) {
+        return null;
+    }
+    return lca;
+}
+/**
+ * @experimental
+ * Generates a minimal CSS selector that uniquely identifies the given node.
+ *
+ * Strategy:
+ * 1. If the node has an `id`, use `#id` (most unique)
+ * 2. If the node has classes, use `tag.class`
+ * 3. Otherwise, build an ancestor path using `>` combinators, stopping at
+ *    the first ancestor with an `id`
+ *
+ * Returns `undefined` for `body` or `html` nodes (file-level fallback).
+ *
+ * @param node - The node to generate a selector for.
+ * @returns A CSS selector string, or undefined for file-level scope.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+export function generateUniqueSelector(node) {
+    if (BODY_HTML_TAGS.has(node.localName)) {
+        return undefined;
+    }
+    // If this node has an id, just use it
+    if (node.id) {
+        return `#${node.id}`;
+    }
+    // If this node has classes, use tag.classA.classB (all classes)
+    const classes = [...node.classList];
+    if (classes.length > 0) {
+        return `${node.localName}.${classes.join('.')}`;
+    }
+    // If this node has a distinguishing attribute (role, or type for input),
+    // use tag[attr="value"] — more readable than nth-of-type and more stable
+    const attrSelector = getDistinguishingAttrSelector(node);
+    if (attrSelector) {
+        return attrSelector;
+    }
+    // Build ancestor path with nth-of-type for disambiguation, stopping at
+    // an id, class, or distinguishing attribute
+    const parts = [buildSegmentWithNth(node)];
+    let current = node.parentElement;
+    while (current && !BODY_HTML_TAGS.has(current.localName)) {
+        if (current.id) {
+            parts.unshift(`#${current.id}`);
+            break;
+        }
+        const currentClasses = [...current.classList];
+        if (currentClasses.length > 0) {
+            parts.unshift(`${current.localName}.${currentClasses.join('.')}`);
+            break;
+        }
+        const currentAttr = getDistinguishingAttrSelector(current);
+        if (currentAttr) {
+            parts.unshift(currentAttr);
+            break;
+        }
+        parts.unshift(buildSegmentWithNth(current));
+        current = current.parentElement;
+    }
+    return parts.join(' > ');
+}
+/**
+ * Attributes that serve as distinguishing selectors.
+ * - `role`: Universally applicable — identifies landmark/widget semantics
+ * - `type`: Only for `<input>` — distinguishes text/checkbox/radio/etc.
+ */
+const DISTINGUISHING_ATTRS = new Map([
+    [null, ['role']], // applicable to any element
+    ['input', ['type']], // only for <input>
+]);
+/**
+ * Returns a `tag[attr="value"]` selector if the node has a distinguishing
+ * attribute (e.g., `role` or `type` for input). Returns `undefined` otherwise.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function getDistinguishingAttrSelector(node) {
+    const universalAttrs = DISTINGUISHING_ATTRS.get(null) ?? [];
+    const elementAttrs = DISTINGUISHING_ATTRS.get(node.localName) ?? [];
+    const attrsToCheck = [...universalAttrs, ...elementAttrs];
+    for (const attrName of attrsToCheck) {
+        for (const attr of node.attributes) {
+            if (attr.name === attrName && attr.value) {
+                return `${node.localName}[${attrName}="${attr.value}"]`;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Builds a selector segment for a node, adding `:nth-of-type(n)` when the
+ * node has same-tag siblings to ensure uniqueness.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function buildSegmentWithNth(node) {
+    const parent = node.parentElement;
+    if (!parent) {
+        return node.localName;
+    }
+    // Count same-tag siblings and find this node's position
+    let sameTagCount = 0;
+    let position = 0;
+    for (const sibling of parent.children) {
+        if (sibling.localName === node.localName) {
+            sameTagCount++;
+            if (sibling === node) {
+                position = sameTagCount;
+            }
+        }
+    }
+    if (sameTagCount > 1) {
+        return `${node.localName}:nth-of-type(${position})`;
+    }
+    return node.localName;
+}
+/**
+ * @experimental
+ * Finds the element node at the given line/col position in the node list.
+ * If the position matches a non-element node (e.g., attribute), walks up
+ * to the nearest parent element.
+ *
+ * @param nodeList - Flat list of all nodes in the document.
+ * @param line - 1-based line number.
+ * @param col - 1-based column number.
+ * @returns The element node at the position, or null if not found.
+ */
+export function findNodeAtPosition(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+nodeList, line, col) {
+    for (const node of nodeList) {
+        if (node.startLine === line && node.startCol === col) {
+            if (node.nodeType === 1) {
+                return node;
+            }
+            // Non-element (e.g., attribute) — walk up to parent element
+            let parent = node.parentElement;
+            while (parent && parent.nodeType !== 1) {
+                parent = parent.parentElement;
+            }
+            return parent;
+        }
+    }
+    return null;
+}
+/**
+ * @experimental
+ * Computes the scope selector for a set of violations within a document.
+ * Only considers error-severity violations. Returns `undefined` when
+ * the LCA falls back to file-level (body/html) or when nodes cannot be found.
+ *
+ * @param nodeList - Flat list of all nodes in the document.
+ * @param violations - The violations to compute scope for.
+ * @returns A CSS selector string, or undefined for file-level scope.
+ */
+export function computeScopeForViolations(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+nodeList, violations) {
+    const nodes = [];
+    for (const v of violations) {
+        if (v.severity !== 'error') {
+            continue;
+        }
+        const node = findNodeAtPosition(nodeList, v.line, v.col);
+        if (node) {
+            nodes.push(node);
+        }
+    }
+    if (nodes.length === 0) {
+        return undefined;
+    }
+    const lca = computeLCA(nodes);
+    if (!lca) {
+        return undefined;
+    }
+    return generateUniqueSelector(lca);
+}

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

@@ -0,0 +1,32 @@
+import type { Violation } from '@markuplint/ml-config';
+import type { PositionedNode } from './compute-scope.js';
+import type { SuppressionsData } from './types.js';
+/**
+ * @experimental
+ * Options for suppressions generation.
+ */
+export type GenerateSuppressionsOptions = {
+    /** If provided, only count violations for this specific ruleId. */
+    readonly filterRule?: string;
+    /**
+     * Map of absolute file paths to their document node lists.
+     * When provided, scope selectors are computed via LCA.
+     * When absent, file-level suppressions are generated (Phase 1 compatible).
+     */
+    readonly nodeLists?: ReadonlyMap<string, readonly PositionedNode[]>;
+};
+/**
+ * @experimental
+ * Generates suppressions data from collected violations.
+ * Only error-severity violations are counted.
+ *
+ * When `options.nodeLists` is provided, computes a scope selector for each
+ * rule's violations via LCA (Lowest Common Ancestor). Otherwise, generates
+ * file-level suppressions (Phase 1 compatible).
+ *
+ * @param violationsByFile - Map of absolute file paths to their violations.
+ * @param suppressionsFilePath - Absolute path to the suppressions file (used for relative path calculation).
+ * @param options - Optional generation options.
+ * @returns The generated suppressions data.
+ */
+export declare function generateSuppressions(violationsByFile: ReadonlyMap<string, readonly Violation[]>, suppressionsFilePath: string, options?: GenerateSuppressionsOptions): SuppressionsData;

package/lib/suppressions/generate-suppressions.js

@@ -0,0 +1,55 @@
+import { computeScopeForViolations } from './compute-scope.js';
+import { toRelativePath } from './suppressions-file.js';
+/**
+ * @experimental
+ * Generates suppressions data from collected violations.
+ * Only error-severity violations are counted.
+ *
+ * When `options.nodeLists` is provided, computes a scope selector for each
+ * rule's violations via LCA (Lowest Common Ancestor). Otherwise, generates
+ * file-level suppressions (Phase 1 compatible).
+ *
+ * @param violationsByFile - Map of absolute file paths to their violations.
+ * @param suppressionsFilePath - Absolute path to the suppressions file (used for relative path calculation).
+ * @param options - Optional generation options.
+ * @returns The generated suppressions data.
+ */
+export function generateSuppressions(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+violationsByFile, suppressionsFilePath, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+options) {
+    const filterRule = options?.filterRule;
+    const nodeLists = options?.nodeLists;
+    const data = {};
+    for (const [absolutePath, violations] of violationsByFile) {
+        // Group error violations by ruleId
+        const byRule = new Map();
+        for (const v of violations) {
+            if (v.severity !== 'error') {
+                continue;
+            }
+            if (filterRule && v.ruleId !== filterRule) {
+                continue;
+            }
+            const list = byRule.get(v.ruleId);
+            if (list) {
+                list.push(v);
+            }
+            else {
+                byRule.set(v.ruleId, [v]);
+            }
+        }
+        if (byRule.size > 0) {
+            const relPath = toRelativePath(absolutePath, suppressionsFilePath);
+            const nodeList = nodeLists?.get(absolutePath);
+            const rules = {};
+            for (const [ruleId, ruleViolations] of byRule) {
+                const scope = nodeList ? computeScopeForViolations(nodeList, ruleViolations) : undefined;
+                rules[ruleId] = scope ? { count: ruleViolations.length, scope } : { count: ruleViolations.length };
+            }
+            data[relPath] = rules;
+        }
+    }
+    return data;
+}

package/lib/suppressions/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @experimental Bulk Suppressions for markuplint.
+ *
+ * Allows recording existing violations in a JSON file and suppressing them
+ * during subsequent lint runs, so new code is strictly enforced while
+ * existing violations are addressed incrementally.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3503
+ * @see https://eslint.org/docs/latest/use/suppressions — Reference design
+ */
+export type { SuppressionsData, SuppressionEntry } from './types.js';
+export type { ApplySuppressionsResult, ApplySuppressionsOptions } from './apply-suppressions.js';
+export type { GenerateSuppressionsOptions } from './generate-suppressions.js';
+export type { ScopedNode, PositionedNode } from './compute-scope.js';
+export { computeScopeForViolations, computeLCA, generateUniqueSelector } from './compute-scope.js';
+export { applySuppressions } from './apply-suppressions.js';
+export { generateSuppressions } from './generate-suppressions.js';
+export { mergeSuppressions } from './merge-suppressions.js';
+export { pruneSuppressions } from './prune-suppressions.js';
+export { readSuppressionsFile, writeSuppressionsFile, resolveSuppressionsPath, toRelativePath, toAbsolutePath, } from './suppressions-file.js';

package/lib/suppressions/index.js

@@ -0,0 +1,16 @@
+/**
+ * @experimental Bulk Suppressions for markuplint.
+ *
+ * Allows recording existing violations in a JSON file and suppressing them
+ * during subsequent lint runs, so new code is strictly enforced while
+ * existing violations are addressed incrementally.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3503
+ * @see https://eslint.org/docs/latest/use/suppressions — Reference design
+ */
+export { computeScopeForViolations, computeLCA, generateUniqueSelector } from './compute-scope.js';
+export { applySuppressions } from './apply-suppressions.js';
+export { generateSuppressions } from './generate-suppressions.js';
+export { mergeSuppressions } from './merge-suppressions.js';
+export { pruneSuppressions } from './prune-suppressions.js';
+export { readSuppressionsFile, writeSuppressionsFile, resolveSuppressionsPath, toRelativePath, toAbsolutePath, } from './suppressions-file.js';

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

@@ -0,0 +1,11 @@
+import type { SuppressionsData } from './types.js';
+/**
+ * @experimental
+ * Merges incoming suppressions into existing suppressions.
+ * For overlapping entries, takes the maximum count.
+ *
+ * @param existing - The current suppressions data.
+ * @param incoming - The new suppressions data to merge.
+ * @returns The merged suppressions data.
+ */
+export declare function mergeSuppressions(existing: SuppressionsData, incoming: SuppressionsData): SuppressionsData;

package/lib/suppressions/merge-suppressions.js

@@ -0,0 +1,31 @@
+/**
+ * @experimental
+ * Merges incoming suppressions into existing suppressions.
+ * For overlapping entries, takes the maximum count.
+ *
+ * @param existing - The current suppressions data.
+ * @param incoming - The new suppressions data to merge.
+ * @returns The merged suppressions data.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+export function mergeSuppressions(existing, incoming) {
+    // Uses max(count) to ensure running --suppress multiple times is idempotent
+    // and never accidentally lowers a suppression threshold. Counts are only
+    // reduced explicitly via --prune-suppressions.
+    const merged = {};
+    // Collect all file paths
+    const allFiles = new Set([...Object.keys(existing), ...Object.keys(incoming)]);
+    for (const filePath of allFiles) {
+        const existingRules = existing[filePath] ?? {};
+        const incomingRules = incoming[filePath] ?? {};
+        const allRules = new Set([...Object.keys(existingRules), ...Object.keys(incomingRules)]);
+        const mergedRules = {};
+        for (const ruleId of allRules) {
+            const existingCount = existingRules[ruleId]?.count ?? 0;
+            const incomingCount = incomingRules[ruleId]?.count ?? 0;
+            mergedRules[ruleId] = { count: Math.max(existingCount, incomingCount) };
+        }
+        merged[filePath] = mergedRules;
+    }
+    return merged;
+}

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

@@ -0,0 +1,22 @@
+import type { Violation } from '@markuplint/ml-config';
+import type { SuppressionsData } from './types.js';
+/**
+ * @experimental
+ * Prunes stale entries from suppressions data based on current violations.
+ *
+ * - Entries with 0 current violations are removed entirely.
+ * - Entries with current count < suppressed count are updated to the current count.
+ * - Entries with current count >= suppressed count are kept as-is.
+ * - Empty file entries (all rules removed) are removed from the top-level.
+ *
+ * **Note:** Pruning counts all file-level violations, not scope-filtered ones.
+ * This is because `pruneSuppressions` does not receive document node lists
+ * (required for scope-based violation filtering). For scope-accurate counts,
+ * re-run `--suppress` which recomputes both scope and count from the DOM tree.
+ *
+ * @param currentViolations - Map of absolute file paths to current violations.
+ * @param existing - The current suppressions data.
+ * @param suppressionsFilePath - Absolute path to the suppressions file.
+ * @returns The pruned suppressions data.
+ */
+export declare function pruneSuppressions(currentViolations: ReadonlyMap<string, readonly Violation[]>, existing: SuppressionsData, suppressionsFilePath: string): SuppressionsData;

package/lib/suppressions/prune-suppressions.js

@@ -0,0 +1,64 @@
+import { toRelativePath } from './suppressions-file.js';
+/**
+ * @experimental
+ * Prunes stale entries from suppressions data based on current violations.
+ *
+ * - Entries with 0 current violations are removed entirely.
+ * - Entries with current count < suppressed count are updated to the current count.
+ * - Entries with current count >= suppressed count are kept as-is.
+ * - Empty file entries (all rules removed) are removed from the top-level.
+ *
+ * **Note:** Pruning counts all file-level violations, not scope-filtered ones.
+ * This is because `pruneSuppressions` does not receive document node lists
+ * (required for scope-based violation filtering). For scope-accurate counts,
+ * re-run `--suppress` which recomputes both scope and count from the DOM tree.
+ *
+ * @param currentViolations - Map of absolute file paths to current violations.
+ * @param existing - The current suppressions data.
+ * @param suppressionsFilePath - Absolute path to the suppressions file.
+ * @returns The pruned suppressions data.
+ */
+export function pruneSuppressions(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+currentViolations, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+existing, suppressionsFilePath) {
+    // Build a lookup: relPath → ruleId → error count
+    const currentCounts = new Map();
+    for (const [absolutePath, violations] of currentViolations) {
+        const relPath = toRelativePath(absolutePath, suppressionsFilePath);
+        const ruleCounts = new Map();
+        for (const v of violations) {
+            if (v.severity === 'error') {
+                ruleCounts.set(v.ruleId, (ruleCounts.get(v.ruleId) ?? 0) + 1);
+            }
+        }
+        currentCounts.set(relPath, ruleCounts);
+    }
+    const pruned = {};
+    for (const [filePath, rules] of Object.entries(existing)) {
+        const fileCounts = currentCounts.get(filePath);
+        const prunedRules = {};
+        for (const [ruleId, entry] of Object.entries(rules)) {
+            const currentCount = fileCounts?.get(ruleId) ?? 0;
+            if (currentCount === 0) {
+                // No more violations, remove entry
+                continue;
+            }
+            if (currentCount < entry.count) {
+                // Reduced violations, update count; preserve scope if present
+                prunedRules[ruleId] = entry.scope
+                    ? { count: currentCount, scope: entry.scope }
+                    : { count: currentCount };
+            }
+            else {
+                // Same or more violations, keep as-is (including scope)
+                prunedRules[ruleId] = entry;
+            }
+        }
+        if (Object.keys(prunedRules).length > 0) {
+            pruned[filePath] = prunedRules;
+        }
+    }
+    return pruned;
+}

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

@@ -0,0 +1,46 @@
+import type { SuppressionsData } from './types.js';
+/**
+ * @experimental
+ * Resolves the absolute path to the suppressions file.
+ *
+ * @param customPath - Optional custom path (relative or absolute). Defaults to `markuplint-suppressions.json` in CWD.
+ * @returns The absolute file path.
+ */
+export declare function resolveSuppressionsPath(customPath?: string): string;
+/**
+ * @experimental
+ * Reads and parses a suppressions JSON file.
+ * Returns an empty object if the file does not exist.
+ *
+ * @param filePath - Absolute path to the suppressions file.
+ * @returns The parsed suppressions data, or an empty object if the file does not exist.
+ */
+export declare function readSuppressionsFile(filePath: string): Promise<SuppressionsData>;
+/**
+ * @experimental
+ * Writes suppressions data to a JSON file with sorted keys.
+ * Deletes the file if data is empty.
+ *
+ * @param filePath - Absolute path to the suppressions file.
+ * @param data - The suppressions data to write.
+ */
+export declare function writeSuppressionsFile(filePath: string, data: SuppressionsData): Promise<void>;
+/**
+ * @experimental
+ * Converts an absolute file path to a relative path based on the suppressions file location.
+ * Always uses POSIX separators for cross-platform consistency.
+ *
+ * @param absoluteFilePath - The absolute path to the linted file.
+ * @param suppressionsFilePath - The absolute path to the suppressions file.
+ * @returns The relative path using POSIX separators.
+ */
+export declare function toRelativePath(absoluteFilePath: string, suppressionsFilePath: string): string;
+/**
+ * @experimental
+ * Converts a relative path (from the suppressions file) back to an absolute path.
+ *
+ * @param relativeFilePath - The relative path stored in the suppressions file.
+ * @param suppressionsFilePath - The absolute path to the suppressions file.
+ * @returns The absolute file path.
+ */
+export declare function toAbsolutePath(relativeFilePath: string, suppressionsFilePath: string): string;