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

package/lib/suppressions/suppressions-file.js

@@ -0,0 +1,108 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { isFatalError } from '@markuplint/shared';
+const DEFAULT_FILE_NAME = 'markuplint-suppressions.json';
+/**
+ * @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 function resolveSuppressionsPath(customPath) {
+    if (customPath) {
+        return path.isAbsolute(customPath) ? customPath : path.resolve(process.cwd(), customPath);
+    }
+    return path.resolve(process.cwd(), DEFAULT_FILE_NAME);
+}
+/**
+ * @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 async function readSuppressionsFile(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return {};
+        }
+        if (error instanceof SyntaxError) {
+            // User may have manually edited and broken the JSON — Tier 2, not Fatal
+            throw new Error(`Failed to parse suppressions file "${filePath}": ${error.message}`, { cause: error });
+        }
+        if (isFatalError(error)) {
+            throw error;
+        }
+        throw error;
+    }
+}
+/**
+ * @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.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+export async function writeSuppressionsFile(filePath, data) {
+    // If empty, delete the file rather than leaving an empty JSON object.
+    // This avoids committing a useless file to the repository.
+    if (Object.keys(data).length === 0) {
+        try {
+            await fs.unlink(filePath);
+        }
+        catch (error) {
+            if (isFatalError(error)) {
+                throw error;
+            }
+            // ENOENT is expected when the file doesn't already exist
+        }
+        return;
+    }
+    // Sort top-level keys and nested keys
+    const sorted = {};
+    for (const fileKey of Object.keys(data).toSorted()) {
+        const rules = data[fileKey];
+        const sortedRules = {};
+        for (const ruleKey of Object.keys(rules).toSorted()) {
+            sortedRules[ruleKey] = rules[ruleKey];
+        }
+        sorted[fileKey] = sortedRules;
+    }
+    const content = JSON.stringify(sorted, null, '\t') + '\n';
+    await fs.writeFile(filePath, content, 'utf8');
+}
+/**
+ * @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 function toRelativePath(absoluteFilePath, suppressionsFilePath) {
+    const dir = path.dirname(suppressionsFilePath);
+    const rel = path.relative(dir, absoluteFilePath);
+    // Normalize to POSIX separators
+    return rel.split(path.sep).join('/');
+}
+/**
+ * @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 function toAbsolutePath(relativeFilePath, suppressionsFilePath) {
+    const dir = path.dirname(suppressionsFilePath);
+    return path.resolve(dir, relativeFilePath);
+}

package/lib/suppressions/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @experimental
+ * A single suppression entry representing the count of suppressed violations
+ * for a specific rule in a specific file.
+ */
+export type SuppressionEntry = {
+    readonly count: number;
+    /**
+     * @experimental
+     * 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.
+     */
+    readonly scope?: string;
+};
+/**
+ * @experimental
+ * The full suppressions data structure.
+ * Top-level keys are relative file paths, values are maps of ruleId to suppression entry.
+ *
+ * **Format note:** The flat structure `{ filePath: { ruleId: { count, scope? } } }`
+ * has no version envelope. The `scope` field is additive (Phase 2) — existing files
+ * without `scope` remain compatible as file-level suppressions. Should a breaking
+ * format change ever be needed, introduce a `{ version: N, ... }` wrapper and migrate.
+ */
+export type SuppressionsData = Record<string, Record<string, SuppressionEntry>>;

package/lib/suppressions/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "markuplint",
-	"version": "5.0.0-dev.5+e96392f56",
+	"version": "5.0.0-rc.1",
 	"description": "An HTML linter for all markup developers",
 	"author": "Yusuke Hirao",
 	"license": "MIT",
@@ -26,25 +26,25 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/cli-utils": "5.0.0-dev.5+e96392f56",
-		"@markuplint/file-resolver": "5.0.0-dev.5+e96392f56",
-		"@markuplint/html-parser": "5.0.0-dev.5+e96392f56",
-		"@markuplint/html-spec": "5.0.0-dev.5+e96392f56",
-		"@markuplint/i18n": "5.0.0-dev.5+e96392f56",
-		"@markuplint/ml-ast": "5.0.0-dev.5+e96392f56",
-		"@markuplint/ml-config": "5.0.0-dev.5+e96392f56",
-		"@markuplint/ml-core": "5.0.0-dev.5+e96392f56",
-		"@markuplint/ml-spec": "5.0.0-dev.5+e96392f56",
-		"@markuplint/rules": "5.0.0-dev.5+e96392f56",
-		"@markuplint/shared": "5.0.0-dev.5+e96392f56",
-		"@types/debug": "4.1.12",
+		"@markuplint/cli-utils": "5.0.0-rc.1",
+		"@markuplint/file-resolver": "5.0.0-rc.1",
+		"@markuplint/html-parser": "5.0.0-rc.1",
+		"@markuplint/html-spec": "5.0.0-rc.1",
+		"@markuplint/i18n": "5.0.0-rc.1",
+		"@markuplint/ml-ast": "5.0.0-rc.1",
+		"@markuplint/ml-config": "5.0.0-rc.1",
+		"@markuplint/ml-core": "5.0.0-rc.1",
+		"@markuplint/ml-spec": "5.0.0-rc.1",
+		"@markuplint/rules": "5.0.0-rc.1",
+		"@markuplint/shared": "5.0.0-rc.1",
+		"@types/debug": "4.1.13",
 		"chokidar": "5.0.0",
 		"debug": "4.4.3",
 		"meow": "14.1.0",
 		"os-locale": "8.0.0",
 		"strict-event-emitter": "0.5.1",
 		"strip-ansi": "7.2.0",
-		"type-fest": "5.4.4"
+		"type-fest": "5.5.0"
 	},
-	"gitHead": "e96392f56e4bc8165ba59622b41c822703a96372"
+	"gitHead": "0d6b4324d9a7d6b9e1ba57d4a57e45d36975cba9"
 }

package/lib/api/v1.d.ts

@@ -1,57 +0,0 @@
-import type { MLResultInfo } from '../types.js';
-import type { Config, PlainData, RuleConfigValue } from '@markuplint/ml-config';
-import type { MLRule } from '@markuplint/ml-core';
-/**
- * Legacy v1 lint function provided for backward compatibility.
- *
- * Translates the v1 option shape into the current `lint` function's parameters
- * and delegates execution to it.
- *
- * @deprecated Use the `lint` function or `MLEngine` class from the current API instead.
- * @param options - The v1-style lint options including file paths, source codes, config, and rules.
- * @returns An array of lint result information objects, one per evaluated file.
- */
-export declare function lint_v1(options: {
-    /**
-     * Glob pattern
-     */
-    readonly files?: string | readonly string[];
-    /**
-     * Target source code of evaluation
-     */
-    readonly sourceCodes?: string | readonly string[];
-    /**
-     * File names when `sourceCodes`
-     */
-    readonly names?: string | readonly string[];
-    /**
-     * Workspace path when `sourceCodes`
-     */
-    readonly workspace?: string;
-    /**
-     * Configure file or object
-     */
-    readonly config?: string | Config;
-    /**
-     * The config applied when not resolved from files or set it explicitly.
-     */
-    readonly defaultConfig?: Config;
-    /**
-     * Rules (default: `@markuplint/rules`)
-     */
-    readonly rules?: readonly Readonly<MLRule<RuleConfigValue, PlainData>>[];
-    /**
-     * Auto resolve rules
-     *
-     * Auto importing form *node_modules* when set `@markuplint/rule-{RULE_NAME}` or `markuplint-rule-{RULE_NAME}` in config rules
-     */
-    readonly rulesAutoResolve?: boolean;
-    /**
-     * Auto fix
-     */
-    readonly fix?: boolean;
-    /**
-     * Locale
-     */
-    readonly locale?: string;
-}): Promise<MLResultInfo[]>;

package/lib/api/v1.js

@@ -1,41 +0,0 @@
-import { toNoEmptyStringArrayFromStringOrArray } from '@markuplint/shared';
-import { lint } from './lint.js';
-/**
- * Legacy v1 lint function provided for backward compatibility.
- *
- * Translates the v1 option shape into the current `lint` function's parameters
- * and delegates execution to it.
- *
- * @deprecated Use the `lint` function or `MLEngine` class from the current API instead.
- * @param options - The v1-style lint options including file paths, source codes, config, and rules.
- * @returns An array of lint result information objects, one per evaluated file.
- */
-export async function lint_v1(options) {
-    const filePathList = toNoEmptyStringArrayFromStringOrArray(options.files);
-    const codes = toNoEmptyStringArrayFromStringOrArray(options.sourceCodes);
-    const files = [
-        ...filePathList,
-        ...codes.map((code, i) => ({
-            sourceCode: code,
-            name: Array.isArray(options.names) ? options.names?.[i] : options.names,
-            workspace: options.workspace?.[i],
-        })),
-    ];
-    let config;
-    let configFile;
-    if (typeof options.config === 'string') {
-        configFile = options.config;
-    }
-    else if (options.config) {
-        config = options.config;
-    }
-    const result = await lint(files, {
-        config,
-        configFile,
-        noSearchConfig: filePathList.length === 0,
-        rules: options.rules,
-        autoLoad: options.rulesAutoResolve ?? true,
-        locale: options.locale,
-    });
-    return result;
-}

package/lib/v1.d.ts

@@ -1,6 +0,0 @@
-/**
- * Legacy v1 entry point re-exporting the deprecated `exec` function.
- *
- * @deprecated Use `lint` or `MLEngine` from the current API instead.
- */
-export { lint_v1 as exec } from './api/v1.js';

package/lib/v1.js

@@ -1,6 +0,0 @@
-/**
- * Legacy v1 entry point re-exporting the deprecated `exec` function.
- *
- * @deprecated Use `lint` or `MLEngine` from the current API instead.
- */
-export { lint_v1 as exec } from './api/v1.js';