@markuplint/shared 5.0.0-dev.5 → 5.0.0-rc.1

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.1](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.0...v5.0.0-rc.1) (2026-03-27)
+
+### Bug Fixes
+
+- address QA review findings for error consolidation ([ac994ee](https://github.com/markuplint/markuplint/commit/ac994ee4b4150dbcb18b30d412853df086627f87))
+
+# [5.0.0-rc.0](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.3...v5.0.0-rc.0) (2026-03-12)
+
+**Note:** Version bump only for package @markuplint/shared
+
 # [5.0.0-alpha.3](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.2...v5.0.0-alpha.3) (2026-02-26)
 
 ### Features

package/lib/errors/config-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when a configuration file cannot be loaded
+ * (Tier 2 — Per-File Recoverable). The affected file is skipped
+ * while other files continue to be processed.
+ */
+export declare class ConfigLoadError extends Error {
+    filePath: string;
+    name: string;
+    referrer: string;
+    /**
+     * @param message - Description of the load failure
+     * @param filePath - Absolute path to the config file that failed to load
+     * @param referrer - Path of the file that referenced this config
+     */
+    constructor(message: string, filePath: string, referrer: string);
+}

package/lib/errors/config-error.js

@@ -0,0 +1,20 @@
+/**
+ * Thrown when a configuration file cannot be loaded
+ * (Tier 2 — Per-File Recoverable). The affected file is skipped
+ * while other files continue to be processed.
+ */
+export class ConfigLoadError extends Error {
+    filePath;
+    name = 'ConfigLoadError';
+    referrer;
+    /**
+     * @param message - Description of the load failure
+     * @param filePath - Absolute path to the config file that failed to load
+     * @param referrer - Path of the file that referenced this config
+     */
+    constructor(message, filePath, referrer) {
+        super(message + ` in ${referrer}`);
+        this.filePath = filePath;
+        this.referrer = referrer;
+    }
+}

package/lib/errors/guards.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns true if the error is a Tier 1 (Fatal) error that must
+ * never be caught or converted. These indicate implementation bugs
+ * or broken invariants.
+ *
+ * See docs/architectures/ERROR-HANDLING.md — Tier 1 for the full list.
+ *
+ * @param error - The caught value to classify
+ * @returns `true` for fatal errors (`TypeError`, `ReferenceError`, `RangeError`,
+ *   `SyntaxError`, `UnexpectedCallError`, or non-`Error` throws); `false` otherwise
+ */
+export declare function isFatalError(error: unknown): boolean;

package/lib/errors/guards.js

@@ -0,0 +1,20 @@
+import { UnexpectedCallError } from './unexpected-call-error.js';
+/**
+ * Returns true if the error is a Tier 1 (Fatal) error that must
+ * never be caught or converted. These indicate implementation bugs
+ * or broken invariants.
+ *
+ * See docs/architectures/ERROR-HANDLING.md — Tier 1 for the full list.
+ *
+ * @param error - The caught value to classify
+ * @returns `true` for fatal errors (`TypeError`, `ReferenceError`, `RangeError`,
+ *   `SyntaxError`, `UnexpectedCallError`, or non-`Error` throws); `false` otherwise
+ */
+export function isFatalError(error) {
+    return (error instanceof TypeError ||
+        error instanceof ReferenceError ||
+        error instanceof RangeError ||
+        error instanceof SyntaxError ||
+        error instanceof UnexpectedCallError ||
+        !(error instanceof Error));
+}

package/lib/errors/index.d.ts

@@ -0,0 +1,6 @@
+export { ConfigLoadError } from './config-error.js';
+export { isFatalError } from './guards.js';
+export { ConfigParserError, ParserError, TargetParserError } from './parser-error.js';
+export type { ParserErrorInfo } from './parser-error.js';
+export { InvalidSelectorError } from './selector-error.js';
+export { UnexpectedCallError } from './unexpected-call-error.js';

package/lib/errors/index.js

@@ -0,0 +1,5 @@
+export { ConfigLoadError } from './config-error.js';
+export { isFatalError } from './guards.js';
+export { ConfigParserError, ParserError, TargetParserError } from './parser-error.js';
+export { InvalidSelectorError } from './selector-error.js';
+export { UnexpectedCallError } from './unexpected-call-error.js';

package/lib/errors/parser-error.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Positional and contextual information associated with a parser error,
+ * used to construct meaningful error messages with source locations.
+ */
+export type ParserErrorInfo = {
+    readonly line?: number;
+    readonly col?: number;
+    readonly raw?: string;
+    readonly stack?: string;
+};
+/**
+ * An error that occurs during parsing, carrying the source line, column,
+ * and raw text where the error was encountered.
+ */
+export declare class ParserError extends Error {
+    readonly col: number;
+    readonly line: number;
+    name: string;
+    readonly raw: string;
+    /**
+     * @param message - Human-readable description of the parse error
+     * @param info - Source location and context where the error occurred
+     */
+    constructor(message: string, info: ParserErrorInfo);
+}
+/**
+ * A parser error specific to a particular HTML element, including
+ * the node name of the element that caused the error in the message.
+ */
+export declare class TargetParserError extends ParserError {
+    name: string;
+    readonly nodeName: string | null;
+    /**
+     * @param message - Human-readable description of the parse error
+     * @param info - Source location, context, and the element's node name
+     */
+    constructor(message: string, info: ParserErrorInfo & {
+        readonly nodeName?: string | null;
+    });
+}
+/**
+ * A parser error that occurs while reading a configuration file,
+ * including the file path in the error message for easier debugging.
+ */
+export declare class ConfigParserError extends ParserError {
+    readonly filePath: string;
+    name: string;
+    /**
+     * @param message - Human-readable description of the parse error
+     * @param info - Source location, context, and path to the config file
+     */
+    constructor(message: string, info: ParserErrorInfo & {
+        readonly filePath: string;
+    });
+}

package/lib/errors/parser-error.js

@@ -0,0 +1,59 @@
+/**
+ * An error that occurs during parsing, carrying the source line, column,
+ * and raw text where the error was encountered.
+ */
+export class ParserError extends Error {
+    col;
+    line;
+    name = 'ParserError';
+    raw;
+    /**
+     * @param message - Human-readable description of the parse error
+     * @param info - Source location and context where the error occurred
+     */
+    constructor(message, info) {
+        super(message);
+        this.line = info.line ?? 1;
+        this.col = info.col ?? 0;
+        this.raw = info.raw ?? '';
+        this.stack = info.stack ?? this.stack;
+    }
+}
+/**
+ * A parser error specific to a particular HTML element, including
+ * the node name of the element that caused the error in the message.
+ */
+export class TargetParserError extends ParserError {
+    name = 'TargetParserError';
+    nodeName;
+    /**
+     * @param message - Human-readable description of the parse error
+     * @param info - Source location, context, and the element's node name
+     */
+    constructor(message, info) {
+        const errMsg = info.nodeName
+            ? `The ${info.nodeName} is invalid element (${info.line}:${info.col}): ${message}`
+            : message;
+        super(errMsg, info);
+        this.nodeName = info.nodeName ?? null;
+    }
+}
+/**
+ * A parser error that occurs while reading a configuration file,
+ * including the file path in the error message for easier debugging.
+ */
+export class ConfigParserError extends ParserError {
+    filePath;
+    name = 'ConfigParserError';
+    /**
+     * @param message - Human-readable description of the parse error
+     * @param info - Source location, context, and path to the config file
+     */
+    constructor(message, info) {
+        const pos = info.line != null && info.col != null ? `(${info.line}:${info.col})` : '';
+        const file = ` in ${info.filePath}${pos}`;
+        const errMsg = `${message}${file}`;
+        super(errMsg, info);
+        this.filePath = info.filePath;
+    }
+}

package/lib/errors/selector-error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown when a CSS selector string cannot be parsed.
+ */
+export declare class InvalidSelectorError extends Error {
+    name: string;
+    /** The invalid selector string that caused this error */
+    selector: string;
+    /**
+     * @param selector - The invalid selector string
+     * @param message - An optional custom error message
+     */
+    constructor(selector: string, message?: string);
+}

package/lib/errors/selector-error.js

@@ -0,0 +1,16 @@
+/**
+ * Error thrown when a CSS selector string cannot be parsed.
+ */
+export class InvalidSelectorError extends Error {
+    name = 'InvalidSelectorError';
+    /** The invalid selector string that caused this error */
+    selector;
+    /**
+     * @param selector - The invalid selector string
+     * @param message - An optional custom error message
+     */
+    constructor(selector, message) {
+        super(message ?? `Invalid selector: "${selector}"`);
+        this.selector = selector;
+    }
+}

package/lib/errors/unexpected-call-error.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Thrown when an internal API is called in a way that violates its
+ * contract (Tier 1 — Fatal). Indicates a bug in markuplint itself.
+ */
+export declare class UnexpectedCallError extends Error {
+}

package/lib/errors/unexpected-call-error.js

@@ -0,0 +1,6 @@
+/**
+ * Thrown when an internal API is called in a way that violates its
+ * contract (Tier 1 — Fatal). Indicates a bug in markuplint itself.
+ */
+export class UnexpectedCallError extends Error {
+}

package/lib/index.d.ts

@@ -1,2 +1,3 @@
+export * from './errors/index.js';
 export * from './functions.js';
 export type * from './types.js';

package/lib/index.js

@@ -1 +1,2 @@
+export * from './errors/index.js';
 export * from './functions.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/shared",
-	"version": "5.0.0-dev.5+e96392f56",
+	"version": "5.0.0-rc.1",
 	"description": "Shared functions for Markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -29,5 +29,5 @@
 	"dependencies": {
 		"html-entities": "2.6.0"
 	},
-	"gitHead": "e96392f56e4bc8165ba59622b41c822703a96372"
+	"gitHead": "0d6b4324d9a7d6b9e1ba57d4a57e45d36975cba9"
 }