markuplint 5.2.0 → 5.4.0

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
+
+### Bug Fixes
+
+* **markuplint:** skip the config search when it is disabled ([e2e8da9](https://github.com/markuplint/markuplint/commit/e2e8da9a81fb113b726fc30877b16cfab4d53736)), closes [#4409](https://github.com/markuplint/markuplint/issues/4409)
+* **markuplint:** watch a config file the search found broken ([1a51145](https://github.com/markuplint/markuplint/commit/1a51145b3eb34c18c0475205466b608787352b66)), closes [#4413](https://github.com/markuplint/markuplint/issues/4413)
+
+
+# [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
+
+### Bug Fixes
+
+* make published packages loadable from require() and put types first ([723106f](https://github.com/markuplint/markuplint/commit/723106f51aac4e60dc02db2c1a894617368b0253)), closes [#4198](https://github.com/markuplint/markuplint/issues/4198)
+* **markuplint:** build the lint AST mapping only when debug is on ([abdbfeb](https://github.com/markuplint/markuplint/commit/abdbfeb9f88ca11e07b47c279a9d793cc46c47c2))
+* **markuplint:** honor the debug option in the MLEngine constructor ([d33d3c8](https://github.com/markuplint/markuplint/commit/d33d3c87a1c8e0c04ee921945ed7488a51ab79c4)), closes [this.#options](https://github.com/this./issues/options)
+* **markuplint:** match a suppression scope of the form tag[attr] with a capital or a digit ([372f313](https://github.com/markuplint/markuplint/commit/372f3138addfbd700b076871e38e1b4fd64e4430))
+* **markuplint:** write and read a scope of a suppression for a name with a `.` ([62c0f3c](https://github.com/markuplint/markuplint/commit/62c0f3c451b45a74491b46be5dc645cbe8b60f18))
+* **markuplint:** write and read the names of a scope as identifiers of CSS ([447fee3](https://github.com/markuplint/markuplint/commit/447fee3362774f273b045fa7996846aa4294360a))
+
+### Performance Improvements
+
+* **markuplint:** group the engine debug calls under one guard ([15c0888](https://github.com/markuplint/markuplint/commit/15c088879400cf1aa0355c260c63a8eb3af4e86a))
+* **markuplint:** skip debug maps without lint listeners ([205bff7](https://github.com/markuplint/markuplint/commit/205bff712bb4a7d42d92b6927ebef5eeb7401dd5))
+
+
 # [5.2.0](https://github.com/markuplint/markuplint/compare/v5.1.1...v5.2.0) (2026-10-13)
 
 ### Bug Fixes

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

@@ -6,6 +6,9 @@ import type { Document, RuleConfigValue } from '@markuplint/ml-core';
 import { ConfigProvider } from '@markuplint/file-resolver';
 import { Emitter } from 'strict-event-emitter';
 type MLEngineOptions = {
+    /**
+     * Enables verbose logging and populates the `debug` payload of the `lint` event.
+     */
     readonly debug?: boolean;
     readonly watch?: boolean;
     /**

package/lib/api/ml-engine.js

@@ -1,4 +1,4 @@
-import { ConfigProvider, createPretenderResolver, disambiguatePretendersForFile, invalidatePretenderResolutionCaches, resolveFiles, resolveParser, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
+import { ConfigProvider, configLoadErrorFiles, createPretenderResolver, disambiguatePretendersForFile, invalidatePretenderResolutionCaches, resolveFiles, resolveParser, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
 import path from 'node:path';
 import { applyRuleAliasesToConfig, mergeConfig } from '@markuplint/ml-config';
 import { CONFIG_ERROR_RULE_ID, MLCore, convertRuleset } from '@markuplint/ml-core';
@@ -132,7 +132,7 @@ export class MLEngine extends Emitter {
     #rerunAgain = false;
     constructor(file, options) {
         super();
-        if (this.#options?.debug) {
+        if (options?.debug) {
             verbosely();
         }
         this.#file = file;
@@ -224,7 +224,10 @@ export class MLEngine extends Emitter {
             };
         }
         const { violations, fixedCode, fixSummary } = verifyResult;
-        const debugMap = 'debugMap' in core.document ? core.document.debugMap() : null;
+        // The AST mapping is a debugging aid: the language server listens to every
+        // lint but only reads the payload when the user asked for debugging, so
+        // a listener alone is no reason to walk the whole document.
+        const debugMap = this.#options?.debug && this.listenerCount('lint') > 0 ? (this.document?.debugMap() ?? null) : null;
         const resolvedFixedCode = fixedCode ?? sourceCode;
         this.emit('lint', this.#file.path, sourceCode, violations, resolvedFixedCode, debugMap, fixSummary ?? null);
         log('exec: end');
@@ -333,9 +336,10 @@ export class MLEngine extends Emitter {
     async #createCore(fabric) {
         fileLog('Get source code');
         const sourceCode = await this.#file.getCode();
-        fileLog('Source code path: %s', this.#file.path);
-        // cspell: disable-next-line
-        fileLog('Source code size: %dbyte', sourceCode.length);
+        if (fileLog.enabled) {
+            fileLog('Source code path: %s', this.#file.path);
+            fileLog('Source code size: %dbyte', sourceCode.length);
+        }
         this.emit('code', this.#file.path, sourceCode);
         const core = new MLCore({
             sourceCode,
@@ -522,10 +526,12 @@ export class MLEngine extends Emitter {
             }
             return this.#failConfig(error);
         }
-        fileLog('Fetched Config files: %O', configSet.files);
-        fileLog('Resolved Config: %O', configSet.config);
-        fileLog('Resolved Plugins: %O', configSet.plugins);
-        fileLog('Resolve Errors: %O', configSet.errs);
+        if (fileLog.enabled) {
+            fileLog('Fetched Config files: %O', configSet.files);
+            fileLog('Resolved Config: %O', configSet.config);
+            fileLog('Resolved Plugins: %O', configSet.plugins);
+            fileLog('Resolve Errors: %O', configSet.errs);
+        }
         const loadError = configSet.errs.find(error => error instanceof ConfigLoadError);
         if (loadError) {
             return this.#failConfig(loadError);
@@ -614,7 +620,7 @@ export class MLEngine extends Emitter {
         // in the middle of this one's `set()`/`search()` calls, which would
         // wipe the keys just registered below before `resolve()` gets to use
         // them. See #4015.
-        const resolvedConfigSet = await this.#configProvider.runExclusive(async () => {
+        const resolvedConfigSet = await this.#runResolution(async () => {
             if (!cache) {
                 // Must run before any `set()` call below — `ConfigProvider#resolve()`
                 // no longer clears its own store on `cache: false`, so invalidating
@@ -626,17 +632,24 @@ export class MLEngine extends Emitter {
                 this.#configProvider.set(mergeConfig(this.#options.defaultConfig), undefined, this.#options.defaultConfig);
             configLog('defaultConfigKey: %s', defaultConfigKey ?? 'N/A');
             this.emit('log', 'defaultConfigKey', defaultConfigKey ?? 'N/A');
-            const targetConfig = await this.#configProvider.search(this.#file);
-            this.emit('log', 'targetConfig', targetConfig ?? 'N/A');
-            const configFilePathsFromTarget = this.#options?.noSearchConfig || this.#options?.configFile
-                ? (defaultConfigKey ?? null)
-                : (targetConfig ?? defaultConfigKey);
+            // Skipped, not run and discarded: the search reads and parses every
+            // config file it reaches, so a malformed one would still surface as a
+            // `config-error` in a run that asked not to search. See #4409.
+            let targetConfig = null;
+            if (this.#options?.noSearchConfig || this.#options?.configFile) {
+                this.emit('log', 'targetConfig', 'skipped (search is disabled)');
+            }
+            else {
+                targetConfig = await this.#configProvider.search(this.#file);
+                this.emit('log', 'targetConfig', targetConfig ?? 'N/A');
+            }
+            const configFilePathsFromTarget = targetConfig ?? defaultConfigKey ?? null;
             configLog('configFilePathsFromTarget: %s', configFilePathsFromTarget ?? 'N/A');
             this.emit('log', 'configFilePathsFromTarget', configFilePathsFromTarget ?? 'N/A');
             const configKey = this.#options?.config &&
                 this.#configProvider.set(mergeConfig(this.#options.config), undefined, this.#options.config);
             configLog('option.config: %s', configKey ?? 'N/A');
-            this.emit('log', 'option.config', configFilePathsFromTarget ?? 'N/A');
+            this.emit('log', 'option.config', configKey ?? 'N/A');
             let defaultRecommended = null;
             if (!defaultConfigKey && !configFilePathsFromTarget && !configKey && !this.#options?.configFile) {
                 // No configured
@@ -669,6 +682,38 @@ export class MLEngine extends Emitter {
         await this.#syncWatch();
         return configSet;
     }
+    /**
+     * Runs `resolve` exclusively on the provider (see {@link resolveConfig}).
+     * When it throws a `ConfigLoadError` (a config file that the search found
+     * cannot be loaded, or a preset that is not found), the files whose change
+     * can fix it ({@link configLoadErrorFiles}: the file it names, and a
+     * `$import` target that does not exist yet) are added to the watched files
+     * before the error goes on: there is no config set to take
+     * {@link ConfigSet.files} from, and the files of the previous resolution
+     * alone would miss the fix of a file that was broken from the start. They
+     * stay watched, as the error names only the first thing that failed, not
+     * every file the config depends on. A directory that the search cannot
+     * examine is not among them, as the shared watcher takes file paths (see
+     * its module JSDoc in `shared-watcher.ts`).
+     *
+     * @param resolve - The resolution, which runs inside `runExclusive`
+     * @returns The config set that `resolve` returns
+     */
+    async #runResolution(resolve) {
+        try {
+            return await this.#configProvider.runExclusive(resolve);
+        }
+        catch (error) {
+            if (isFatalError(error)) {
+                throw error;
+            }
+            if (error instanceof ConfigLoadError) {
+                this.#configFiles = new Set([...this.#configFiles, ...configLoadErrorFiles(error)]);
+                await this.#syncWatch();
+            }
+            throw error;
+        }
+    }
     async #resolveParser(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     configSet) {

package/lib/api/types.d.ts

@@ -37,6 +37,13 @@ export type MLEngineEventMap = {
         sourceCode: string,
         violations: readonly Violation[],
         fixedCode: string,
+        /**
+         * The AST mapping dump. It is built only when the engine's `debug`
+         * option is on and a `lint` listener is registered at the time the
+         * engine emits, because the dump costs a full walk of the document
+         * that nobody reads unless debugging was requested. Otherwise, or when
+         * the engine has no parsed document, it is `null`.
+         */
         debug: readonly string[] | null,
         fixSummary: FixSummary | null
     ];

package/lib/debug.d.ts

@@ -1,3 +1,7 @@
 import debug from 'debug';
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import.
+ */
 export declare const log: debug.Debugger;
 export declare function verbosely(): void;

package/lib/debug.js

@@ -1,5 +1,9 @@
 import { enableDebug } from '@markuplint/ml-core';
 import debug from 'debug';
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import.
+ */
 export const log = debug('markuplint-cli');
 export function verbosely() {
     if (!log.enabled) {

package/lib/index.d.ts

@@ -4,6 +4,12 @@
  * Main package entry point for markuplint.
  * Re-exports the public API surface including the lint engine, types,
  * internationalization utilities, testing tools, and version information.
+ *
+ * Invariant for every published package: the ESM-only build must stay
+ * loadable from CommonJS through `require()`. Node does that synchronously only
+ * while the static module graph has no top-level `await`, so none may be
+ * introduced. `packages/@markuplint/test-tools/src/package-exports.spec.ts`
+ * enforces it.
  */
 /** The primary linting engine and options for linting from source code strings. */
 export { MLEngine, FromCodeOptions } from './api/index.js';

package/lib/index.js

@@ -4,6 +4,12 @@
  * Main package entry point for markuplint.
  * Re-exports the public API surface including the lint engine, types,
  * internationalization utilities, testing tools, and version information.
+ *
+ * Invariant for every published package: the ESM-only build must stay
+ * loadable from CommonJS through `require()`. Node does that synchronously only
+ * while the static module graph has no top-level `await`, so none may be
+ * introduced. `packages/@markuplint/test-tools/src/package-exports.spec.ts`
+ * enforces it.
  */
 /** The primary linting engine and options for linting from source code strings. */
 export { MLEngine } from './api/index.js';

package/lib/suppressions/apply-suppressions.js

@@ -1,28 +1,58 @@
-import { findNodeAtPosition } from './compute-scope.js';
+import { findNodeAtPosition, splitScopeAttr, splitScopeIdents, splitScopeNth, unescapeIdentifier, } from './compute-scope.js';
 import { toRelativePath } from './suppressions-file.js';
 function isViolationInScope(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-nodeList, violation, scope) {
+nodeList, violation, segments) {
     const violationNode = findNodeAtPosition(nodeList, violation.line, violation.col);
     if (!violationNode) {
         return false;
     }
     // Check the node itself and walk up ancestors
-    if (matchesScopeSelector(violationNode, scope)) {
+    if (matchesScopeSelector(violationNode, segments)) {
         return true;
     }
     let current = violationNode.parentElement;
     while (current) {
-        if (matchesScopeSelector(current, scope)) {
+        if (matchesScopeSelector(current, segments)) {
             return true;
         }
         current = current.parentElement;
     }
     return false;
 }
+function parseSegment(segment) {
+    if (segment.length === 0) {
+        return null;
+    }
+    // #id
+    if (segment.startsWith('#')) {
+        return { kind: 'id', id: unescapeIdentifier(segment.slice(1)) };
+    }
+    // tag[attr="value"]: the tag is the `localName` with a capital letter (`FooBar`), a digit (`h1`) or an escaped character
+    // A segment with no `[` has no attribute, so it is not scanned for one
+    const attr = segment.includes('[') ? splitScopeAttr(segment) : null;
+    if (attr) {
+        return {
+            kind: 'attr',
+            tag: splitScopeIdents(attr.tag).join('.'),
+            attrName: attr.attrName,
+            attrValue: attr.attrValue,
+        };
+    }
+    // Extract :nth-of-type(n) if present and unescaped
+    const { base: baseSegment, nth } = segment.includes(':') ? splitScopeNth(segment) : { base: segment, nth: null };
+    // tag.classA.classB
+    // A `.` of a name is escaped (`Tabs\.Root`), so only an unescaped one starts a class.
+    const [tag, ...classes] = splitScopeIdents(baseSegment);
+    return {
+        kind: 'compound',
+        tag: tag,
+        classes,
+        nth,
+    };
+}
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-function matchesScopeSelector(node, scope) {
-    const segments = scope.split(' > ');
+function matchesScopeSelector(node, segments) {
     let current = node;
     // Match segments from right (most specific) to left (ancestors)
     for (let i = segments.length - 1; i >= 0; i--) {
@@ -38,49 +68,30 @@ function matchesScopeSelector(node, scope) {
 }
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 function matchesSegment(node, segment) {
-    if (segment.length === 0) {
+    if (segment === null) {
         return false;
     }
-    // #id
-    if (segment.startsWith('#')) {
-        const id = segment.slice(1);
-        return id.length > 0 && node.id === id;
+    if (segment.kind === 'id') {
+        return segment.id.length > 0 && node.id === segment.id;
     }
-    // tag[attr="value"]
-    const attrMatch = /^([a-z-]+)\[([a-z-]+)="([^"]+)"\]$/.exec(segment);
-    if (attrMatch) {
-        const [, tag, attrName, attrValue] = attrMatch;
-        if (node.localName !== tag) {
+    if (segment.kind === 'attr') {
+        if (node.localName !== segment.tag) {
             return false;
         }
         for (const attr of node.attributes) {
-            if (attr.name === attrName && attr.value === attrValue) {
+            if (attr.name === segment.attrName && attr.value === segment.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));
-    }
+    const tagMatches = node.localName === segment.tag && segment.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);
+    if (segment.nth !== null) {
+        const expectedPosition = segment.nth;
         const parent = node.parentElement;
         if (!parent) {
             return false;
@@ -187,13 +198,17 @@ function getScopedErrorInfo(violations, ruleId, entry,
 nodeList) {
     let count = 0;
     const indices = [];
+    // The scope is read once, not once per violation.
+    // It is split at ` > ` without looking at escapes: `serializeIdentifier` writes every `>` of a name as `\>`
+    // (and a space as `\ `), so the only ` > ` of a scope is a separator.
+    const segments = entry.scope && nodeList ? entry.scope.split(' > ').map(segment => parseSegment(segment)) : undefined;
     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)) {
+        if (segments && nodeList) {
+            if (isViolationInScope(nodeList, v, segments)) {
                 count++;
                 indices.push(i);
             }

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

@@ -51,6 +51,65 @@ export interface PositionedNode extends ScopedNode {
     readonly startLine: number;
     readonly startCol: number;
 }
+/**
+ * @experimental
+ * Writes a tag name, a class name or an id into a scope, by the CSSOM algorithm "serialize an identifier"
+ * (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
+ * `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.
+ *
+ * A scope file written before the escape holds names unescaped, and they still read as the syntax,
+ * because every scope that ever matched was written so (`unescapeIdentifier` leaves a character that is
+ * not escaped as it is). A scope for a name with a `.` never matched, except in the form
+ * `tag[attr="value"]`, whose tag has always been read as a name. Likewise a scope for a name that ends
+ * 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.
+ *
+ * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ */
+export declare function serializeIdentifier(name: string): string;
+/**
+ * @experimental
+ * Reads an identifier of a scope, the reading side of {@link serializeIdentifier}: the escapes of CSS
+ * (`\` and 1 to 6 hex digits with one whitespace, or `\` and any other character), and a character that
+ * is not escaped as it is.
+ */
+export declare function unescapeIdentifier(escaped: string): string;
+/**
+ * @experimental
+ * Splits a compound scope segment (`tag.classA.classB`) at its unescaped `.` and unescapes each part,
+ * the reading side of {@link generateUniqueSelector}. The first part is the tag, the rest are classes.
+ */
+export declare function splitScopeIdents(segment: string): string[];
+/**
+ * @experimental
+ * Splits the form `tag[attr="value"]`. The tag is what comes before the first `[` that is not escaped,
+ * and it holds no unescaped `]` or `"`, so `Foo\[x="y"]` is no attribute: its `[` is escaped.
+ * The tag is returned as it is written.
+ */
+export declare function splitScopeAttr(segment: string): {
+    readonly tag: string;
+    readonly attrName: string;
+    readonly attrValue: string;
+} | null;
+/**
+ * @experimental
+ * Splits the position `:nth-of-type(n)` that ends a compound scope segment from the rest of it.
+ * The `:` of the suffix is a position only when it is not escaped, which a regex on the end of the
+ * segment cannot tell alone: a name that ends with `\` is written `\\`, so `a\\:nth-of-type(2)` is the
+ * 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
+ */
+export declare function splitScopeNth(segment: string): {
+    readonly base: string;
+    readonly nth: number | null;
+};
 export declare function getAncestorChain(node: ScopedNode): ScopedNode[];
 /**
  * @experimental

package/lib/suppressions/compute-scope.js

@@ -21,6 +21,190 @@
  * @see https://github.com/markuplint/markuplint/issues/3509
  */
 const BODY_HTML_TAGS = new Set(['body', 'html']);
+/**
+ * The position that ends a segment of a scope: `:nth-of-type(n)`.
+ * A name never ends with it unescaped, because the `:` and the `()` of a name are written escaped
+ * ({@link serializeIdentifier}), so what ends a segment so is the position.
+ */
+const NTH_OF_TYPE = /^:nth-of-type\((\d+)\)$/;
+/**
+ * The non-ASCII ident code points of CSS, inclusive: the same as HTML's valid custom element names.
+ * U+200C and U+200D (zero width joiners) are the other two, and are checked apart: a joiner in a character
+ * class makes the linter read the class as a joined character sequence.
+ * @see https://www.w3.org/TR/css-syntax-3/#non-ascii-ident-code-point
+ */
+const NON_ASCII_IDENT_CODE_POINT = /^[\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u037D\u037F-\u1FFF\u203F\u2040\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD\u{10000}-\u{10FFFF}]$/u;
+/**
+ * @experimental
+ * Writes a tag name, a class name or an id into a scope, by the CSSOM algorithm "serialize an identifier"
+ * (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
+ * `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.
+ *
+ * A scope file written before the escape holds names unescaped, and they still read as the syntax,
+ * because every scope that ever matched was written so (`unescapeIdentifier` leaves a character that is
+ * not escaped as it is). A scope for a name with a `.` never matched, except in the form
+ * `tag[attr="value"]`, whose tag has always been read as a name. Likewise a scope for a name that ends
+ * 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.
+ *
+ * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ */
+export function serializeIdentifier(name) {
+    let result = '';
+    let index = 0;
+    for (const char of name) {
+        const isDigit = char >= '0' && char <= '9';
+        if (char === '\u0000') {
+            result += '\uFFFD';
+        }
+        else if (
+        // U+0001 to U+001F and U+007F
+        (char.codePointAt(0) >= 1 && char.codePointAt(0) <= 31) ||
+            char.codePointAt(0) === 127 ||
+            (index === 0 && isDigit) ||
+            (index === 1 && isDigit && name.startsWith('-'))) {
+            result += `\\${char.codePointAt(0).toString(16)} `;
+        }
+        else if (index === 0 && char === '-' && name.length === 1) {
+            result += String.raw `\-`;
+        }
+        else if (char === '-' ||
+            char === '_' ||
+            isDigit ||
+            /^[a-z]$/i.test(char) ||
+            NON_ASCII_IDENT_CODE_POINT.test(char) ||
+            char === '\u200C' ||
+            char === '\u200D') {
+            result += char;
+        }
+        else {
+            result += `\\${char}`;
+        }
+        index++;
+    }
+    return result;
+}
+/** 1 to 6 hex digits of an escape, and the one whitespace that ends them. Sticky: it matches at `lastIndex`. */
+const HEX_ESCAPE = /[\dA-F]{1,6}(?:\r\n|[\t\n\f\r ])?/iy;
+/**
+ * The one scanner of a scope segment, which {@link unescapeIdentifier}, {@link splitScopeIdents},
+ * {@link splitScopeAttr} and {@link splitScopeNth} read with: yields each character (an escape is one
+ * character) with the index it starts at, and whether a `\` escaped it. The escapes are the ones of CSS.
+ *
+ * @see https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
+ */
+function* scanScope(segment) {
+    for (let i = 0; i < segment.length; i++) {
+        const char = segment[i];
+        const next = segment[i + 1];
+        if (char !== '\\' || next === '\n' || next === '\r' || next === '\f') {
+            // A `\` before a newline is no escape
+            yield { index: i, char, escaped: false };
+            continue;
+        }
+        if (next === undefined) {
+            yield { index: i, char: '\uFFFD', escaped: true };
+            continue;
+        }
+        HEX_ESCAPE.lastIndex = i + 1;
+        const hex = HEX_ESCAPE.exec(segment);
+        if (hex) {
+            const codePoint = Number.parseInt(hex[0], 16);
+            // Zero, a surrogate (U+D800 to U+DFFF) and a value over U+10FFFF are U+FFFD
+            const isValid = codePoint !== 0 && !(codePoint >= 55_296 && codePoint <= 57_343) && codePoint <= 1_114_111;
+            yield { index: i, char: isValid ? String.fromCodePoint(codePoint) : '\uFFFD', escaped: true };
+            i += hex[0].length;
+            continue;
+        }
+        const escapedChar = String.fromCodePoint(segment.codePointAt(i + 1));
+        yield { index: i, char: escapedChar, escaped: true };
+        i += escapedChar.length;
+    }
+}
+/**
+ * @experimental
+ * Reads an identifier of a scope, the reading side of {@link serializeIdentifier}: the escapes of CSS
+ * (`\` and 1 to 6 hex digits with one whitespace, or `\` and any other character), and a character that
+ * is not escaped as it is.
+ */
+export function unescapeIdentifier(escaped) {
+    let result = '';
+    for (const { char } of scanScope(escaped)) {
+        result += char;
+    }
+    return result;
+}
+/**
+ * @experimental
+ * Splits a compound scope segment (`tag.classA.classB`) at its unescaped `.` and unescapes each part,
+ * the reading side of {@link generateUniqueSelector}. The first part is the tag, the rest are classes.
+ */
+export function splitScopeIdents(segment) {
+    const parts = [''];
+    for (const { char, escaped } of scanScope(segment)) {
+        if (!escaped && char === '.') {
+            parts.push('');
+        }
+        else {
+            parts[parts.length - 1] += char;
+        }
+    }
+    return parts;
+}
+/**
+ * @experimental
+ * Splits the form `tag[attr="value"]`. The tag is what comes before the first `[` that is not escaped,
+ * and it holds no unescaped `]` or `"`, so `Foo\[x="y"]` is no attribute: its `[` is escaped.
+ * The tag is returned as it is written.
+ */
+export function splitScopeAttr(segment) {
+    for (const { index, char, escaped } of scanScope(segment)) {
+        if (escaped) {
+            continue;
+        }
+        if (char === ']' || char === '"') {
+            return null;
+        }
+        if (char === '[') {
+            const match = /^\[([a-z-]+)="([^"]+)"\]$/.exec(segment.slice(index));
+            return index > 0 && match
+                ? { tag: segment.slice(0, index), attrName: match[1], attrValue: match[2] }
+                : null;
+        }
+    }
+    return null;
+}
+/**
+ * @experimental
+ * Splits the position `:nth-of-type(n)` that ends a compound scope segment from the rest of it.
+ * The `:` of the suffix is a position only when it is not escaped, which a regex on the end of the
+ * segment cannot tell alone: a name that ends with `\` is written `\\`, so `a\\:nth-of-type(2)` is the
+ * 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
+ */
+export function splitScopeNth(segment) {
+    // Only an unescaped `:` is looked at: an escaped one is read with its `\` before it, as one character
+    for (const { index, char, escaped } of scanScope(segment)) {
+        if (!escaped && char === ':') {
+            const match = NTH_OF_TYPE.exec(segment.slice(index));
+            if (match) {
+                return { base: segment.slice(0, index), nth: Number.parseInt(match[1], 10) };
+            }
+        }
+    }
+    return { base: segment, nth: null };
+}
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function tagWithClasses(node, classes) {
+    return [node.localName, ...classes].map(name => serializeIdentifier(name)).join('.');
+}
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 export function getAncestorChain(node) {
     const chain = [];
@@ -97,12 +281,12 @@ export function generateUniqueSelector(node) {
     }
     // If this node has an id, just use it
     if (node.id) {
-        return `#${node.id}`;
+        return `#${serializeIdentifier(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('.')}`;
+        return tagWithClasses(node, classes);
     }
     // 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
@@ -116,12 +300,12 @@ export function generateUniqueSelector(node) {
     let current = node.parentElement;
     while (current && !BODY_HTML_TAGS.has(current.localName)) {
         if (current.id) {
-            parts.unshift(`#${current.id}`);
+            parts.unshift(`#${serializeIdentifier(current.id)}`);
             break;
         }
         const currentClasses = [...current.classList];
         if (currentClasses.length > 0) {
-            parts.unshift(`${current.localName}.${currentClasses.join('.')}`);
+            parts.unshift(tagWithClasses(current, currentClasses));
             break;
         }
         const currentAttr = getDistinguishingAttrSelector(current);
@@ -150,8 +334,9 @@ function getDistinguishingAttrSelector(node) {
     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}"]`;
+            // A value with `"` or ` > ` cannot be held by `tag[attr="value"]`: a scope ends the value at `"` and splits at ` > `.
+            if (attr.name === attrName && attr.value && !attr.value.includes('"') && !attr.value.includes(' > ')) {
+                return `${serializeIdentifier(node.localName)}[${attrName}="${attr.value}"]`;
             }
         }
     }
@@ -160,8 +345,9 @@ function getDistinguishingAttrSelector(node) {
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 function buildSegmentWithNth(node) {
     const parent = node.parentElement;
+    const name = serializeIdentifier(node.localName);
     if (!parent) {
-        return node.localName;
+        return name;
     }
     // Count same-tag siblings and find this node's position
     let sameTagCount = 0;
@@ -175,9 +361,9 @@ function buildSegmentWithNth(node) {
         }
     }
     if (sameTagCount > 1) {
-        return `${node.localName}:nth-of-type(${position})`;
+        return `${name}:nth-of-type(${position})`;
     }
-    return node.localName;
+    return name;
 }
 /**
  * @experimental

package/lib/suppressions/downgrade-severity.js

@@ -94,6 +94,6 @@ _nodeList) {
     // fall back to file-level filtering (treats all violations as in-scope).
     // This is the safe direction — more violations may be downgraded than intended,
     // but no new violations are hidden.
-    // TODO(#3536): Export isViolationInScope from apply-suppressions.ts and reuse here.
+    // TODO(#3536): Export the scope matching of apply-suppressions.ts (`parseSegment` and `isViolationInScope`) and reuse here.
     return group;
 }

package/lib/suppressions/types.d.ts

@@ -10,6 +10,9 @@ export type SuppressionEntry = {
      * CSS selector identifying the LCA (Lowest Common Ancestor) subtree
      * that contains all violations for this rule. Uses id/class/attr for
      * precise matching. When absent, suppression applies to the entire file.
+     *
+     * A `.`, `#`, `[` or `\` in a tag name or a class name is escaped with a `\` (`Tabs\.Root`),
+     * as CSS does. A scope written before the escape has none, and is read as it was written.
      */
     readonly scope?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "markuplint",
-	"version": "5.2.0",
+	"version": "5.4.0",
 	"description": "An HTML linter for all markup developers",
 	"author": "Yusuke Hirao",
 	"license": "MIT",
@@ -15,11 +15,10 @@
 	"type": "module",
 	"exports": {
 		".": {
-			"import": "./lib/index.js",
-			"types": "./lib/index.d.ts"
+			"types": "./lib/index.d.ts",
+			"default": "./lib/index.js"
 		},
 		"./suppressions": {
-			"import": "./lib/suppressions/index.js",
 			"types": "./lib/suppressions/index.d.ts",
 			"default": "./lib/suppressions/index.js"
 		},
@@ -35,17 +34,17 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/cli-utils": "5.2.0",
-		"@markuplint/file-resolver": "5.2.0",
-		"@markuplint/html-parser": "5.2.0",
-		"@markuplint/html-spec": "5.2.0",
-		"@markuplint/i18n": "5.1.1",
-		"@markuplint/ml-ast": "5.1.1",
-		"@markuplint/ml-config": "5.2.0",
-		"@markuplint/ml-core": "5.2.0",
-		"@markuplint/ml-spec": "5.2.0",
-		"@markuplint/rules": "5.2.0",
-		"@markuplint/shared": "5.2.0",
+		"@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",
 		"@types/debug": "^4.1.13",
 		"chokidar": "^5.0.0",
 		"debug": "^4.4.3",
@@ -55,5 +54,5 @@
 		"strip-ansi": "^7.2.0",
 		"type-fest": "^5.10.0"
 	},
-	"gitHead": "d8b2feab77c9c862513615bea6b80d2817431878"
+	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
 }