markuplint 5.4.0 → 5.6.0

package/lib/cli/main.js

@@ -0,0 +1,171 @@
+/**
+ * @module cli/main
+ *
+ * The CLI run itself. `index.ts` is the entry point and owns the process boundary
+ * (the exit code and why `process.exit()` is not used); this module is separate so a spec
+ * can call `main()` without starting the process.
+ */
+import { text } from 'node:stream/consumers';
+import { isFatalError } from '@markuplint/shared';
+import { verbosely } from '../debug.js';
+import { cli } from './bootstrap.js';
+import { command } from './command.js';
+import { initialize } from './init/index.js';
+import { search } from './search/index.js';
+/** The operand that means standard input. */
+const STDIN_OPERAND = '-';
+/**
+ * Runs the CLI and resolves to its exit code.
+ *
+ * Every branch returns a number: a branch that forgets to leaves `undefined`,
+ * and the `process.exitCode` that `output.ts` set (1) would leak out.
+ */
+export async function main() {
+    // Same condition as meow's automatic handling: the flag has to be the only argument.
+    const isSoleArgument = cli.input.length === 0 && process.argv.length === 3;
+    if (cli.flags.v || (isSoleArgument && cli.flags.version === true)) {
+        return showVersion();
+    }
+    if (cli.flags.h || (isSoleArgument && cli.flags.help === true)) {
+        return showHelp(0);
+    }
+    if (cli.flags.verbose) {
+        verbosely();
+    }
+    if (cli.flags.init) {
+        try {
+            await initialize();
+        }
+        catch (error) {
+            if (isFatalError(error)) {
+                throw error;
+            }
+            process.stderr.write(error + '\n');
+            return 1;
+        }
+        return 0;
+    }
+    if (cli.flags.createRule) {
+        process.stderr.write("Use to run 'npx @markuplint/create-rule' instead of 'markuplint --create-rule'.\n");
+        return 1;
+    }
+    const files = cli.input;
+    if (files.includes(STDIN_OPERAND)) {
+        const fileFlags = givenFileFlags();
+        if (files.length > 1 || fileFlags.length > 0) {
+            const conflicts = files.length > 1 ? ['file paths', ...fileFlags] : fileFlags;
+            process.stderr.write(`The \`${STDIN_OPERAND}\` operand (standard input) cannot be combined with ${conflicts.join(', ')}.\n`);
+            return 1;
+        }
+        const stdin = await readStdin();
+        if (stdin === null) {
+            return 1;
+        }
+        // An empty input is an empty source, as `markuplint empty.html` is.
+        return lintStdin(stdin);
+    }
+    if (files.length > 0) {
+        if (cli.flags.search) {
+            try {
+                await search(files, cli.flags, cli.flags.search);
+            }
+            catch (error) {
+                if (isFatalError(error)) {
+                    throw error;
+                }
+                process.stderr.write(error + '\n');
+                return 1;
+            }
+            return 0;
+        }
+        return lint(files, cli.flags);
+    }
+    if (usePipe()) {
+        const fileFlags = givenFileFlags();
+        if (fileFlags.length > 0) {
+            process.stderr.write(`Standard input cannot be combined with ${fileFlags.join(', ')}.\n`);
+            return 1;
+        }
+        const stdin = await readStdin();
+        if (stdin === null) {
+            return 1;
+        }
+        if (!stdin) {
+            // result is empty
+            return showHelp(1);
+        }
+        return lintStdin(stdin);
+    }
+    // No arguments
+    return showHelp(1);
+}
+/**
+ * The options that act on a file that are given, by their names: `--fix` writes the fixed source
+ * to it (with nothing to write to, it created a file named `<AnonymousFile>`, #4560), `--search`
+ * and the suppressions options report or record by file. The standard input has none, so both
+ * ways of reading it (the `-` operand and the no-operand pipe) reject them, and name them in the
+ * message, from this one list: an option that acts on a file is added here, and nowhere else.
+ * `--fix-dry-run` is not one: it writes nothing and prints the diff.
+ */
+function givenFileFlags() {
+    const { search, fix, suppress, suppressRule, pruneSuppressions } = cli.flags;
+    // Each is given by the condition of the code that consumes it, not by one shared test:
+    // `--search` is a search when it is not empty (the file branch below tests it so), and
+    // `--suppress-rule` turns the suppressions mode on when it is set at all (`command.ts`).
+    const given = [
+        ['--search', Boolean(search)],
+        ['--fix', Boolean(fix)],
+        ['--suppress', Boolean(suppress)],
+        ['--suppress-rule', suppressRule != null],
+        ['--prune-suppressions', Boolean(pruneSuppressions)],
+    ];
+    return given.filter(([, isGiven]) => isGiven).map(([name]) => name);
+}
+function usePipe() {
+    return !process.stdin.isTTY && process.stdout.isTTY;
+}
+/**
+ * Reports a read failure on stderr and returns `null` instead of throwing,
+ * so the caller can return the exit code.
+ */
+async function readStdin() {
+    try {
+        return await text(process.stdin);
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        process.stderr.write(error + '\n');
+        return null;
+    }
+}
+function lintStdin(sourceCode) {
+    return lint([{ sourceCode }], { ...cli.flags, ignoreExt: true });
+}
+/**
+ * Runs `command()` and resolves to its exit code. A failure that is not fatal is reported on
+ * stderr with exit code 1, whatever the input is (file paths or the standard input).
+ */
+async function lint(...args) {
+    try {
+        return (await command(...args)) ? 1 : 0;
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        process.stderr.write(error + '\n');
+        return 1;
+    }
+}
+/** Prints what meow's `showVersion()` printed (`console.log` of the version). */
+function showVersion() {
+    process.stdout.write(cli.pkg.version + '\n');
+    return 0;
+}
+/** Prints what meow's `showHelp()` printed (`console.log` of the help, which ends with a newline). */
+function showHelp(exitCode) {
+    process.stdout.write(cli.help + '\n');
+    return exitCode;
+}

package/lib/cli/output.js

@@ -28,6 +28,8 @@ export function output(results, options) {
     let msg = `${out.join('\n')}\n`;
     msg = options.color ? msg : stripAnsi(msg);
     // If it has errors, Write to `stderr` and failure and exit.
+    // `index.ts` overwrites this `exitCode` with the verdict `command()` returns, which is the one
+    // that counts (warnings are written here too, yet only `--no-allow-warnings` fails on them).
     if (results.violations.length > 0) {
         process.stderr.write(msg);
         process.exitCode = 1;
@@ -78,7 +80,7 @@ function createSummaryLines(summary) {
         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`);
+        out.push(`${font.yellow('⚠')} ${pluralize(summary.skippedFileCount, 'file')} not reported because --max-count was reached (violations in ${summary.skippedFileCount === 1 ? 'it' : 'them'} still count toward the exit code)`);
     }
     return out;
 }

package/lib/cli/search/index.js

@@ -13,7 +13,8 @@ export async function search(files, options, selectors) {
                 name,
                 ...createRule({
                     verify({ document }) {
-                        const nodes = document.querySelectorAll(selectors);
+                        // Every tree is searched: what is in the content of a `template` element is found too
+                        const nodes = document.deepQuerySelectorAll(selectors);
                         locations.push(...[...nodes].map(node => {
                             return {
                                 file: document.filename ?? '_NO_FILE_',

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

@@ -50,6 +50,29 @@ export interface ScopedNode {
 export interface PositionedNode extends ScopedNode {
     readonly startLine: number;
     readonly startCol: number;
+    /**
+     * Where the node's source ends, excluded. For an element, the end of its start tag.
+     * A violation inside this range belongs to the node (see `findNodeAtPosition`);
+     * without it, only a violation at the node's start does.
+     */
+    readonly endLine?: number;
+    /** The column of `endLine`, excluded. */
+    readonly endCol?: number;
+    /**
+     * The end tag of an element. A document's node list has no end tags, so a
+     * violation reported at one (`</P>`) is found through its element.
+     */
+    readonly closeTag?: SourceRange | null;
+}
+/**
+ * @experimental
+ * A source range: from its start, included, to its end, excluded.
+ */
+export interface SourceRange {
+    readonly startLine: number;
+    readonly startCol: number;
+    readonly endLine?: number;
+    readonly endCol?: number;
 }
 /**
  * @experimental
@@ -57,7 +80,7 @@ export interface PositionedNode extends ScopedNode {
  * (the one `CSS.escape()` is specified by), in which a code point that is not an ident code point of CSS
  * Syntax is escaped, so the output is always one identifier. A NUL is written as U+FFFD, as the algorithm
  * has it, so it does not read back as NUL. A scope is a CSS selector, and CSS lets any code point be part
- * of an identifier by escaping it, "even ones that CSS uses in its syntax". So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
+ * of an identifier by escaping it, even one that CSS uses in its syntax. So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
  * `Tabs` with the class `Root`, `py-1.5` is `py-1\.5`, `hover:bg-x` is `hover\:bg-x`, `2xl:flex` is
  * `\32 xl\:flex`, and a class that ends with `:nth-of-type(2)` is no position. What this writes and what
  * {@link unescapeIdentifier} reads are one form, so a scope matches the element it was made for.
@@ -69,7 +92,12 @@ export interface PositionedNode extends ScopedNode {
  * with `:nth-of-type(n)` (`div.a:nth-of-type(2)`) never matched, and is still read as a position. A `\`
  * that such a file holds is read as CSS reads it: `\ba` is the hex escape U+00BA.
  *
+ * CSS Syntax says of an identifier:
+ *
+ * > You can include any code point at all, even ones that CSS uses in its syntax, by escaping it.
+ *
  * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export declare function serializeIdentifier(name: string): string;
 /**
@@ -104,7 +132,7 @@ export declare function splitScopeAttr(segment: string): {
  * class `a\` at the position 2, and `a\:nth-of-type(2)` is the class `a:nth-of-type(2)`. The escapes
  * are scanned from the start, as {@link splitScopeIdents} does.
  *
- * @see https://www.w3.org/TR/css-syntax-3/#escaping
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export declare function splitScopeNth(segment: string): {
     readonly base: string;
@@ -138,6 +166,15 @@ export declare function computeLCA(nodes: readonly ScopedNode[]): ScopedNode | n
 export declare function generateUniqueSelector(node: ScopedNode): string | undefined;
 /**
  * @experimental
+ * Finds the element a violation at `line`:`col` belongs to.
+ *
+ * The node is the one `searchNodeAtLocation` of `@markuplint/ml-core` finds,
+ * the rule `MLDocument.searchNodeByLocation` and the hover of the language
+ * server share: a violation reported at an attribute (`no-duplicate-attr`),
+ * inside its value or at an end tag is the element that has it, and of several
+ * nodes that hold the position the innermost is taken. A non-element is
+ * resolved to its nearest element ancestor. `nodeList` is in document order.
+ *
  * The O(n) linear search per violation is deliberate — acceptable for
  * typical document sizes; build a position index only if very large
  * documents make this a measured bottleneck.
@@ -147,7 +184,9 @@ export declare function findNodeAtPosition(nodeList: readonly PositionedNode[],
  * @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.
+ * the LCA falls back to file-level (body/html) or when a violation is at no
+ * element: the entry counts every violation, and applying a scope counts only
+ * those found inside it, so a scope that left one out would not suppress it.
  *
  * @param nodeList - Flat list of all nodes in the document.
  * @param violations - The violations to compute scope for.

package/lib/suppressions/compute-scope.js

@@ -20,6 +20,7 @@
  *
  * @see https://github.com/markuplint/markuplint/issues/3509
  */
+import { searchNodeAtLocation } from '@markuplint/ml-core';
 const BODY_HTML_TAGS = new Set(['body', 'html']);
 /**
  * The position that ends a segment of a scope: `:nth-of-type(n)`.
@@ -40,7 +41,7 @@ const NON_ASCII_IDENT_CODE_POINT = /^[\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u0
  * (the one `CSS.escape()` is specified by), in which a code point that is not an ident code point of CSS
  * Syntax is escaped, so the output is always one identifier. A NUL is written as U+FFFD, as the algorithm
  * has it, so it does not read back as NUL. A scope is a CSS selector, and CSS lets any code point be part
- * of an identifier by escaping it, "even ones that CSS uses in its syntax". So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
+ * of an identifier by escaping it, even one that CSS uses in its syntax. So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
  * `Tabs` with the class `Root`, `py-1.5` is `py-1\.5`, `hover:bg-x` is `hover\:bg-x`, `2xl:flex` is
  * `\32 xl\:flex`, and a class that ends with `:nth-of-type(2)` is no position. What this writes and what
  * {@link unescapeIdentifier} reads are one form, so a scope matches the element it was made for.
@@ -52,7 +53,12 @@ const NON_ASCII_IDENT_CODE_POINT = /^[\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u0
  * with `:nth-of-type(n)` (`div.a:nth-of-type(2)`) never matched, and is still read as a position. A `\`
  * that such a file holds is read as CSS reads it: `\ba` is the hex escape U+00BA.
  *
+ * CSS Syntax says of an identifier:
+ *
+ * > You can include any code point at all, even ones that CSS uses in its syntax, by escaping it.
+ *
  * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export function serializeIdentifier(name) {
     let result = '';
@@ -187,7 +193,7 @@ export function splitScopeAttr(segment) {
  * class `a\` at the position 2, and `a\:nth-of-type(2)` is the class `a:nth-of-type(2)`. The escapes
  * are scanned from the start, as {@link splitScopeIdents} does.
  *
- * @see https://www.w3.org/TR/css-syntax-3/#escaping
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export function splitScopeNth(segment) {
     // Only an unescaped `:` is looked at: an escaped one is read with its `\` before it, as one character
@@ -367,6 +373,15 @@ function buildSegmentWithNth(node) {
 }
 /**
  * @experimental
+ * Finds the element a violation at `line`:`col` belongs to.
+ *
+ * The node is the one `searchNodeAtLocation` of `@markuplint/ml-core` finds,
+ * the rule `MLDocument.searchNodeByLocation` and the hover of the language
+ * server share: a violation reported at an attribute (`no-duplicate-attr`),
+ * inside its value or at an end tag is the element that has it, and of several
+ * nodes that hold the position the innermost is taken. A non-element is
+ * resolved to its nearest element ancestor. `nodeList` is in document order.
+ *
  * The O(n) linear search per violation is deliberate — acceptable for
  * typical document sizes; build a position index only if very large
  * documents make this a measured bottleneck.
@@ -374,26 +389,26 @@ function buildSegmentWithNth(node) {
 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;
-        }
+    const found = searchNodeAtLocation(nodeList, line, col);
+    if (!found) {
+        return null;
     }
-    return null;
+    if (found.nodeType === 1) {
+        return found;
+    }
+    let parent = found.parentElement;
+    while (parent && parent.nodeType !== 1) {
+        parent = parent.parentElement;
+    }
+    return parent;
 }
 /**
  * @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.
+ * the LCA falls back to file-level (body/html) or when a violation is at no
+ * element: the entry counts every violation, and applying a scope counts only
+ * those found inside it, so a scope that left one out would not suppress it.
  *
  * @param nodeList - Flat list of all nodes in the document.
  * @param violations - The violations to compute scope for.
@@ -408,9 +423,10 @@ nodeList, violations) {
             continue;
         }
         const node = findNodeAtPosition(nodeList, v.line, v.col);
-        if (node) {
-            nodes.push(node);
+        if (!node) {
+            return undefined;
         }
+        nodes.push(node);
     }
     if (nodes.length === 0) {
         return undefined;

package/lib/suppressions/index.d.ts

@@ -18,7 +18,7 @@
 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 type { ScopedNode, PositionedNode, SourceRange } from './compute-scope.js';
 export { computeScopeForViolations, computeLCA, generateUniqueSelector } from './compute-scope.js';
 export { applySuppressions } from './apply-suppressions.js';
 export { generateSuppressions } from './generate-suppressions.js';

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

@@ -2,7 +2,18 @@ import type { SuppressionsData } from './types.js';
 /**
  * @experimental
  * Merges incoming suppressions into existing suppressions.
- * For overlapping entries, takes the maximum count.
+ * For overlapping entries with the same scope, takes the maximum count;
+ * for overlapping entries whose scopes differ, takes the incoming entry.
+ *
+ * The scope of an overlapping entry is always the incoming one:
+ * `generateSuppressions` computes it as the subtree that contains every current
+ * violation of the rule, so an existing scope could leave some of them outside
+ * and unsuppressed. An incoming entry without a scope covers the whole file, so
+ * it drops the existing scope. A count is the number of violations inside its
+ * own scope, so when the scope changes, the existing count is not carried over:
+ * it would let new violations inside the new scope pass up to a number that
+ * scope never held. An entry only on one side is kept as it is, scope included
+ * (a rule `--suppress-rule` did not select, a file not linted).
  *
  * @param existing - The current suppressions data.
  * @param incoming - The new suppressions data to merge.

package/lib/suppressions/merge-suppressions.js

@@ -1,7 +1,18 @@
 /**
  * @experimental
  * Merges incoming suppressions into existing suppressions.
- * For overlapping entries, takes the maximum count.
+ * For overlapping entries with the same scope, takes the maximum count;
+ * for overlapping entries whose scopes differ, takes the incoming entry.
+ *
+ * The scope of an overlapping entry is always the incoming one:
+ * `generateSuppressions` computes it as the subtree that contains every current
+ * violation of the rule, so an existing scope could leave some of them outside
+ * and unsuppressed. An incoming entry without a scope covers the whole file, so
+ * it drops the existing scope. A count is the number of violations inside its
+ * own scope, so when the scope changes, the existing count is not carried over:
+ * it would let new violations inside the new scope pass up to a number that
+ * scope never held. An entry only on one side is kept as it is, scope included
+ * (a rule `--suppress-rule` did not select, a file not linted).
  *
  * @param existing - The current suppressions data.
  * @param incoming - The new suppressions data to merge.
@@ -9,9 +20,9 @@
  */
 // 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.
+    // Under the same scope, uses max(count) to ensure running --suppress multiple
+    // times is idempotent and never accidentally lowers a suppression threshold.
+    // Counts of an unchanged scope are only reduced explicitly via --prune-suppressions.
     const merged = {};
     // Collect all file paths
     const allFiles = new Set([...Object.keys(existing), ...Object.keys(incoming)]);
@@ -21,11 +32,20 @@ export function mergeSuppressions(existing, incoming) {
         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) };
+            const existingEntry = existingRules[ruleId];
+            const incomingEntry = incomingRules[ruleId];
+            mergedRules[ruleId] = mergeEntry(existingEntry, incomingEntry);
         }
         merged[filePath] = mergedRules;
     }
     return merged;
 }
+function mergeEntry(existing, incoming) {
+    // Both are never absent: the rule ID comes from one of the two sides.
+    const base = incoming ?? existing;
+    const count = existing && incoming && existing.scope === incoming.scope
+        ? Math.max(existing.count, incoming.count)
+        : base.count;
+    // Only `count` and `scope` are written: a key the file has besides them is not carried over.
+    return base.scope === undefined ? { count } : { count, scope: base.scope };
+}

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

@@ -11,8 +11,9 @@ import type { SuppressionsData } from './types.js';
  *
  * **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.
+ * (required for scope-based violation filtering). `--suppress` recomputes the scope
+ * from the DOM tree, and takes the new count when the scope changes; under an
+ * unchanged scope it keeps the higher count (see `mergeSuppressions`).
  *
  * @param currentViolations - Map of absolute file paths to current violations.
  * @param existing - The current suppressions data.

package/lib/suppressions/prune-suppressions.js

@@ -10,8 +10,9 @@ import { toRelativePath } from './suppressions-file.js';
  *
  * **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.
+ * (required for scope-based violation filtering). `--suppress` recomputes the scope
+ * from the DOM tree, and takes the new count when the scope changes; under an
+ * unchanged scope it keeps the higher count (see `mergeSuppressions`).
  *
  * @param currentViolations - Map of absolute file paths to current violations.
  * @param existing - The current suppressions data.

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

@@ -12,6 +12,11 @@ export declare function resolveSuppressionsPath(customPath?: string): string;
  * Reads and parses a suppressions JSON file.
  * Returns an empty object if the file does not exist.
  *
+ * Only the top level is checked: valid JSON that is not an object (`null`, an
+ * array, a string, a number) is not suppressions data and fails like
+ * unparsable JSON does, so that every caller gets the same readable error
+ * instead of a `TypeError` from the first `Object.keys` on it.
+ *
  * @param filePath - Absolute path to the suppressions file.
  * @returns The parsed suppressions data, or an empty object if the file does not exist.
  */

package/lib/suppressions/suppressions-file.js

@@ -20,13 +20,22 @@ export function resolveSuppressionsPath(customPath) {
  * Reads and parses a suppressions JSON file.
  * Returns an empty object if the file does not exist.
  *
+ * Only the top level is checked: valid JSON that is not an object (`null`, an
+ * array, a string, a number) is not suppressions data and fails like
+ * unparsable JSON does, so that every caller gets the same readable error
+ * instead of a `TypeError` from the first `Object.keys` on it.
+ *
  * @param filePath - Absolute path to the suppressions file.
  * @returns The parsed suppressions data, or an empty object if the file does not exist.
  */
 export async function readSuppressionsFile(filePath) {
     try {
         const content = await fs.readFile(filePath, 'utf8');
-        return JSON.parse(content);
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`Failed to parse suppressions file "${filePath}": the top level must be a JSON object`);
+        }
+        return parsed;
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "markuplint",
-	"version": "5.4.0",
+	"version": "5.6.0",
 	"description": "An HTML linter for all markup developers",
 	"author": "Yusuke Hirao",
 	"license": "MIT",
@@ -24,29 +24,34 @@
 		},
 		"./package.json": "./package.json"
 	},
-	"typedoc": {
-		"entryPoint": "./src/index.ts"
-	},
 	"bin": "./bin/markuplint.mjs",
 	"scripts": {
 		"build": "tsc --project tsconfig.build.json",
 		"dev": "tsc --watch --project tsconfig.build.json",
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
+	"devDependencies": {
+		"@markuplint/astro-parser": "5.6.0",
+		"@markuplint/jsx-parser": "5.6.0",
+		"@markuplint/mdx-parser": "5.6.0",
+		"@markuplint/pretenders": "5.6.0",
+		"@markuplint/svelte-parser": "5.6.0",
+		"@markuplint/vue-parser": "5.6.0"
+	},
 	"dependencies": {
 		"@markuplint/cli-utils": "5.3.0",
-		"@markuplint/file-resolver": "5.4.0",
-		"@markuplint/html-parser": "5.4.0",
-		"@markuplint/html-spec": "5.4.0",
-		"@markuplint/i18n": "5.3.0",
-		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-config": "5.4.0",
-		"@markuplint/ml-core": "5.4.0",
-		"@markuplint/ml-spec": "5.4.0",
-		"@markuplint/rules": "5.4.0",
-		"@markuplint/shared": "5.4.0",
+		"@markuplint/file-resolver": "5.6.0",
+		"@markuplint/html-parser": "5.6.0",
+		"@markuplint/html-spec": "5.6.0",
+		"@markuplint/i18n": "5.6.0",
+		"@markuplint/ml-ast": "5.6.0",
+		"@markuplint/ml-config": "5.6.0",
+		"@markuplint/ml-core": "5.6.0",
+		"@markuplint/ml-spec": "5.6.0",
+		"@markuplint/rules": "5.6.0",
+		"@markuplint/shared": "5.6.0",
 		"@types/debug": "^4.1.13",
-		"chokidar": "^5.0.0",
+		"chokidar": "^6.0.0",
 		"debug": "^4.4.3",
 		"meow": "^14.1.0",
 		"os-locale": "^8.0.0",
@@ -54,5 +59,33 @@
 		"strip-ansi": "^7.2.0",
 		"type-fest": "^5.10.0"
 	},
-	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
+	"peerDependencies": {
+		"@markuplint/astro-parser": "^5.4.0",
+		"@markuplint/jsx-parser": "^5.4.0",
+		"@markuplint/mdx-parser": "^5.4.0",
+		"@markuplint/pretenders": "^5.4.0",
+		"@markuplint/svelte-parser": "^5.4.0",
+		"@markuplint/vue-parser": "^5.4.0"
+	},
+	"peerDependenciesMeta": {
+		"@markuplint/astro-parser": {
+			"optional": true
+		},
+		"@markuplint/jsx-parser": {
+			"optional": true
+		},
+		"@markuplint/mdx-parser": {
+			"optional": true
+		},
+		"@markuplint/pretenders": {
+			"optional": true
+		},
+		"@markuplint/svelte-parser": {
+			"optional": true
+		},
+		"@markuplint/vue-parser": {
+			"optional": true
+		}
+	},
+	"gitHead": "eade3d7202682e567f3c1b6985478f1d4b5c5481"
 }