markuplint 4.14.0 → 5.0.0-alpha.0

package/lib/api/ml-engine.js

@@ -1,15 +1,3 @@
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var _MLEngine_configProvider, _MLEngine_core, _MLEngine_file, _MLEngine_options, _MLEngine_watcher;
 import { ConfigProvider, resolveFiles, resolveParser, resolvePretenders, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
 import { mergeConfig } from '@markuplint/ml-config';
 import { MLCore, convertRuleset } from '@markuplint/ml-core';
@@ -20,7 +8,20 @@ import { i18n } from '../i18n.js';
 const log = coreLog.extend('ml-engine');
 const fileLog = log.extend('file');
 const configLog = log.extend('config');
+/**
+ * The main markuplint engine that orchestrates file resolution, configuration loading,
+ * parsing, and linting. Supports both single-file and watch-mode operation.
+ *
+ * Emits events at each stage of the linting pipeline for monitoring and debugging.
+ */
 export class MLEngine extends Emitter {
+    /**
+     * Creates an MLEngine instance from inline source code.
+     *
+     * @param sourceCode - The markup source code to lint
+     * @param options - Options for configuration, naming, and behavior
+     * @returns A new MLEngine instance ready to lint the provided code
+     */
     static async fromCode(sourceCode, options) {
         if (options?.debug) {
             verbosely();
@@ -38,36 +39,55 @@ export class MLEngine extends Emitter {
         const engine = new MLEngine(file, options);
         return engine;
     }
+    /**
+     * Converts a target (file path or inline source) into an MLFile instance.
+     *
+     * @param target - A file path string or inline source code target
+     * @returns The resolved MLFile, or `undefined` if resolution failed
+     */
     static async toMLFile(target) {
         const files = await resolveFiles([target]);
         return files[0];
     }
+    #configProvider;
+    #core = null;
+    #file;
+    #options;
+    #watcher = new FSWatcher();
     constructor(file, options) {
         super();
-        _MLEngine_configProvider.set(this, void 0);
-        _MLEngine_core.set(this, null);
-        _MLEngine_file.set(this, void 0);
-        _MLEngine_options.set(this, void 0);
-        _MLEngine_watcher.set(this, new FSWatcher());
-        if (__classPrivateFieldGet(this, _MLEngine_options, "f")?.debug) {
+        if (this.#options?.debug) {
             verbosely();
         }
-        __classPrivateFieldSet(this, _MLEngine_file, file, "f");
-        __classPrivateFieldSet(this, _MLEngine_options, options, "f");
-        __classPrivateFieldSet(this, _MLEngine_configProvider, new ConfigProvider(), "f");
-        this.watchMode(!!__classPrivateFieldGet(this, _MLEngine_options, "f")?.watch);
-        log('[MLEngine] Initialized: %s', __classPrivateFieldGet(this, _MLEngine_file, "f").path);
+        this.#file = file;
+        this.#options = options;
+        this.#configProvider = new ConfigProvider();
+        this.watchMode(!!this.#options?.watch);
+        log('[MLEngine] Initialized: %s', this.#file.path);
     }
+    /**
+     * The parsed document, or `null` if not yet set up or if parsing failed.
+     */
     get document() {
-        if (__classPrivateFieldGet(this, _MLEngine_core, "f")?.document instanceof Error) {
+        if (this.#core?.document instanceof Error) {
             return null;
         }
-        return __classPrivateFieldGet(this, _MLEngine_core, "f")?.document ?? null;
+        return this.#core?.document ?? null;
     }
+    /**
+     * Closes the engine, removing all event listeners and stopping the file watcher.
+     */
     async close() {
         this.removeAllListeners();
-        await __classPrivateFieldGet(this, _MLEngine_watcher, "f").close();
+        await this.#watcher.close();
     }
+    /**
+     * Executes linting on the target file and returns the results.
+     *
+     * Sets up the engine on first call, then verifies the document against all rules.
+     *
+     * @returns The lint result including violations and fixed code, or `null` if setup was skipped
+     */
     async exec() {
         log('exec: start');
         const core = await this.setup();
@@ -75,16 +95,16 @@ export class MLEngine extends Emitter {
             log('exec: cancel (unsetuped yet)');
             return null;
         }
-        const violations = await core.verify(__classPrivateFieldGet(this, _MLEngine_options, "f")?.fix).catch(error => {
+        const violations = await core.verify(this.#options?.fix).catch(error => {
             if (error instanceof Error) {
                 return error;
             }
             throw error;
         });
-        const sourceCode = await __classPrivateFieldGet(this, _MLEngine_file, "f").getCode();
+        const sourceCode = await this.#file.getCode();
         const fixedCode = core.document.toString(true);
         if (violations instanceof Error) {
-            this.emit('lint-error', __classPrivateFieldGet(this, _MLEngine_file, "f").path, sourceCode, violations);
+            this.emit('lint-error', this.#file.path, sourceCode, violations);
             const errMessage = violations.stack ?? violations.message;
             log('exec: error %O', errMessage);
             return {
@@ -98,66 +118,77 @@ export class MLEngine extends Emitter {
                         raw: '',
                     },
                 ],
-                filePath: __classPrivateFieldGet(this, _MLEngine_file, "f").path,
+                filePath: this.#file.path,
                 sourceCode,
                 fixedCode,
                 status: 'processed',
             };
         }
         const debugMap = 'debugMap' in core.document ? core.document.debugMap() : null;
-        this.emit('lint', __classPrivateFieldGet(this, _MLEngine_file, "f").path, sourceCode, violations, fixedCode, debugMap);
+        this.emit('lint', this.#file.path, sourceCode, violations, fixedCode, debugMap);
         log('exec: end');
         return {
             violations,
-            filePath: __classPrivateFieldGet(this, _MLEngine_file, "f").path,
+            filePath: this.#file.path,
             sourceCode,
             fixedCode,
             status: 'processed',
         };
     }
+    /**
+     * Updates the source code and re-parses the document without re-resolving configuration.
+     *
+     * @param code - The new markup source code
+     */
     async setCode(code) {
         const core = await this.setup();
         if (!core) {
             return;
         }
-        __classPrivateFieldGet(this, _MLEngine_file, "f").setCode(code);
+        this.#file.setCode(code);
         core.setCode(code);
     }
+    /**
+     * Enables or disables watch mode. When enabled, the engine watches config files
+     * for changes and re-lints automatically.
+     *
+     * @param enable - Whether to enable watch mode
+     */
     watchMode(enable) {
-        __classPrivateFieldSet(this, _MLEngine_options, {
-            ...__classPrivateFieldGet(this, _MLEngine_options, "f"),
+        this.#options = {
+            ...this.#options,
             watch: enable,
-        }, "f");
+        };
         if (enable) {
-            __classPrivateFieldGet(this, _MLEngine_watcher, "f").on('change', this.onChange.bind(this));
+            this.#watcher.on('change', this.onChange.bind(this));
         }
         else {
-            __classPrivateFieldGet(this, _MLEngine_watcher, "f").removeAllListeners();
+            this.#watcher.removeAllListeners();
         }
     }
     async createCore(fabric) {
         fileLog('Get source code');
-        const sourceCode = await __classPrivateFieldGet(this, _MLEngine_file, "f").getCode();
-        fileLog('Source code path: %s', __classPrivateFieldGet(this, _MLEngine_file, "f").path);
+        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);
-        this.emit('code', __classPrivateFieldGet(this, _MLEngine_file, "f").path, sourceCode);
+        this.emit('code', this.#file.path, sourceCode);
         const core = new MLCore({
             sourceCode,
-            filename: __classPrivateFieldGet(this, _MLEngine_file, "f").path,
-            debug: __classPrivateFieldGet(this, _MLEngine_options, "f")?.debug,
+            filename: this.#file.path,
+            debug: this.#options?.debug,
             ...fabric,
         });
-        __classPrivateFieldSet(this, _MLEngine_core, core, "f");
+        this.#core = core;
         return core;
     }
-    async i18n() {
-        const i18nSettings = await i18n(__classPrivateFieldGet(this, _MLEngine_options, "f")?.locale);
-        this.emit('i18n', __classPrivateFieldGet(this, _MLEngine_file, "f").path, i18nSettings);
+    i18n() {
+        const i18nSettings = i18n(this.#options?.locale);
+        this.emit('i18n', this.#file.path, i18nSettings);
         return i18nSettings;
     }
     async onChange(filePath) {
-        if (!__classPrivateFieldGet(this, _MLEngine_options, "f")?.watch) {
+        if (!this.#options?.watch) {
             return;
         }
         this.emit('log', 'watch:onChange', filePath);
@@ -166,10 +197,10 @@ export class MLEngine extends Emitter {
             return;
         }
         if (fabric.configErrors) {
-            this.emit('config-errors', __classPrivateFieldGet(this, _MLEngine_file, "f").path, fabric.configErrors);
+            this.emit('config-errors', this.#file.path, fabric.configErrors);
         }
-        this.emit('log', 'update:core', __classPrivateFieldGet(this, _MLEngine_file, "f").path);
-        __classPrivateFieldGet(this, _MLEngine_core, "f")?.update(fabric);
+        this.emit('log', 'update:core', this.#file.path);
+        this.#core?.update(fabric);
         await this.exec();
     }
     async provide(cache = true) {
@@ -194,27 +225,27 @@ export class MLEngine extends Emitter {
         fileLog('Resolved Config: %O', configSet.config);
         fileLog('Resolved Plugins: %O', configSet.plugins);
         fileLog('Resolve Errors: %O', configSet.errs);
-        if (!(await __classPrivateFieldGet(this, _MLEngine_file, "f").isFile())) {
-            this.emit('log', 'file-no-exists', `The file doesn't exist or it is not a file: ${__classPrivateFieldGet(this, _MLEngine_file, "f").path}`);
-            fileLog("The file doesn't exist or it is not a file: %s", __classPrivateFieldGet(this, _MLEngine_file, "f").path);
+        if (!(await this.#file.isFile())) {
+            this.emit('log', 'file-no-exists', `The file doesn't exist or it is not a file: ${this.#file.path}`);
+            fileLog("The file doesn't exist or it is not a file: %s", this.#file.path);
             return null;
         }
         // Exclude
         const excludeFiles = configSet.config.excludeFiles ?? [];
-        if (__classPrivateFieldGet(this, _MLEngine_file, "f").ignored(excludeFiles)) {
-            fileLog('Excludes the file: %s', __classPrivateFieldGet(this, _MLEngine_file, "f").path);
+        if (this.#file.ignored(excludeFiles)) {
+            fileLog('Excludes the file: %s', this.#file.path);
             return null;
         }
         const { parser, parserOptions, matched } = await this.resolveParser(configSet);
-        const checkingExt = !__classPrivateFieldGet(this, _MLEngine_options, "f")?.ignoreExt;
+        const checkingExt = !this.#options?.ignoreExt;
         if (checkingExt && !matched) {
-            this.emit('log', 'ext-unmatched', `Avoided linting because a file is unmatched by the extension: ${__classPrivateFieldGet(this, _MLEngine_file, "f").path}`);
-            fileLog('Avoided linting because a file is unmatched by the extension: %s', __classPrivateFieldGet(this, _MLEngine_file, "f").path);
+            this.emit('log', 'ext-unmatched', `Avoided linting because a file is unmatched by the extension: ${this.#file.path}`);
+            fileLog('Avoided linting because a file is unmatched by the extension: %s', this.#file.path);
             return null;
         }
         const severity = {
             ...configSet.config.severity,
-            ...__classPrivateFieldGet(this, _MLEngine_options, "f")?.severity,
+            ...this.#options?.severity,
         };
         const pretenders = await this.resolvePretenders(configSet);
         fileLog('Resolved pretenders: %O', pretenders);
@@ -235,7 +266,8 @@ export class MLEngine extends Emitter {
         }
         const rules = await this.resolveRules(configSet.plugins, ruleset);
         fileLog('Resolved rules: %O', rules);
-        const locale = await i18n(__classPrivateFieldGet(this, _MLEngine_options, "f")?.locale);
+        const locale = i18n(this.#options?.locale);
+        const ruleCommonSettings = configSet.config.ruleCommonSettings ?? {};
         if (fileLog.enabled) {
             fileLog('Loaded %d rules: %O', rules.length, rules.map(r => r.name));
         }
@@ -248,46 +280,47 @@ export class MLEngine extends Emitter {
             schemas,
             rules,
             locale,
+            ruleCommonSettings,
             configErrors: configSet.errs,
         };
     }
     async resolveConfig(cache) {
-        this.emit('log', 'resolveConfig', JSON.stringify(__classPrivateFieldGet(this, _MLEngine_configProvider, "f"), null, 2));
-        configLog('configProvider: %s', __classPrivateFieldGet(this, _MLEngine_configProvider, "f"));
-        const defaultConfigKey = __classPrivateFieldGet(this, _MLEngine_options, "f")?.defaultConfig && __classPrivateFieldGet(this, _MLEngine_configProvider, "f").set(mergeConfig(__classPrivateFieldGet(this, _MLEngine_options, "f")?.defaultConfig));
+        this.emit('log', 'resolveConfig', JSON.stringify(this.#configProvider, null, 2));
+        configLog('configProvider: %s', this.#configProvider);
+        const defaultConfigKey = this.#options?.defaultConfig && this.#configProvider.set(mergeConfig(this.#options?.defaultConfig));
         configLog('defaultConfigKey: %s', defaultConfigKey ?? 'N/A');
         this.emit('log', 'defaultConfigKey', defaultConfigKey ?? 'N/A');
-        const targetConfig = await __classPrivateFieldGet(this, _MLEngine_configProvider, "f").search(__classPrivateFieldGet(this, _MLEngine_file, "f"));
+        const targetConfig = await this.#configProvider.search(this.#file);
         this.emit('log', 'targetConfig', targetConfig ?? 'N/A');
-        const configFilePathsFromTarget = __classPrivateFieldGet(this, _MLEngine_options, "f")?.noSearchConfig
+        const configFilePathsFromTarget = this.#options?.noSearchConfig || this.#options?.configFile
             ? (defaultConfigKey ?? null)
             : (targetConfig ?? defaultConfigKey);
         configLog('configFilePathsFromTarget: %s', configFilePathsFromTarget ?? 'N/A');
         this.emit('log', 'configFilePathsFromTarget', configFilePathsFromTarget ?? 'N/A');
-        const configKey = __classPrivateFieldGet(this, _MLEngine_options, "f")?.config && __classPrivateFieldGet(this, _MLEngine_configProvider, "f").set(mergeConfig(__classPrivateFieldGet(this, _MLEngine_options, "f").config));
+        const configKey = this.#options?.config && this.#configProvider.set(mergeConfig(this.#options.config));
         configLog('option.config: %s', configKey ?? 'N/A');
         this.emit('log', 'option.config', configFilePathsFromTarget ?? 'N/A');
         let defaultRecommended = null;
-        if (!defaultConfigKey && !configFilePathsFromTarget && !configKey) {
+        if (!defaultConfigKey && !configFilePathsFromTarget && !configKey && !this.#options?.configFile) {
             // No configured
             // Default: set recommended
-            defaultRecommended = __classPrivateFieldGet(this, _MLEngine_configProvider, "f").set({ extends: ['markuplint:recommended'] });
+            defaultRecommended = this.#configProvider.set({ extends: ['markuplint:recommended'] });
         }
         configLog('defaultRecommended: %s', defaultRecommended ?? 'N/A');
         this.emit('log', 'defaultRecommended', defaultRecommended ?? 'N/A');
-        const configSet = await __classPrivateFieldGet(this, _MLEngine_configProvider, "f").resolve(__classPrivateFieldGet(this, _MLEngine_file, "f"), [configFilePathsFromTarget, __classPrivateFieldGet(this, _MLEngine_options, "f")?.configFile, configKey, defaultRecommended], cache);
-        this.emit('config', __classPrivateFieldGet(this, _MLEngine_file, "f").path, configSet);
-        if (__classPrivateFieldGet(this, _MLEngine_options, "f")?.watch) {
+        const configSet = await this.#configProvider.resolve(this.#file, [configFilePathsFromTarget, this.#options?.configFile, configKey, defaultRecommended], cache);
+        this.emit('config', this.#file.path, configSet);
+        if (this.#options?.watch) {
             // It doesn't watch the main HTML file because it may is watched and managed by a language server or text editor or more.
-            __classPrivateFieldGet(this, _MLEngine_watcher, "f").add([...configSet.files]);
+            this.#watcher.add([...configSet.files]);
         }
         return configSet;
     }
     async resolveParser(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     configSet) {
-        const parser = await resolveParser(__classPrivateFieldGet(this, _MLEngine_file, "f"), configSet.config.parser, configSet.config.parserOptions);
-        this.emit('parser', __classPrivateFieldGet(this, _MLEngine_file, "f").path, parser.parserModName);
+        const parser = await resolveParser(this.#file, configSet.config.parser, configSet.config.parserOptions);
+        this.emit('parser', this.#file.path, parser.parserModName);
         fileLog('Fetched Parser module: %s', parser.parserModName);
         return parser;
     }
@@ -299,39 +332,38 @@ export class MLEngine extends Emitter {
         return pretenders;
     }
     async resolveRules(plugins, ruleset) {
-        const rules = await resolveRules(plugins, ruleset, __classPrivateFieldGet(this, _MLEngine_options, "f")?.importPresetRules ?? true, __classPrivateFieldGet(this, _MLEngine_options, "f")?.autoLoad ?? true);
-        if (__classPrivateFieldGet(this, _MLEngine_options, "f")?.rules) {
-            rules.push(...__classPrivateFieldGet(this, _MLEngine_options, "f").rules);
+        const rules = await resolveRules(plugins, ruleset, this.#options?.importPresetRules ?? true, this.#options?.autoLoad ?? true);
+        if (this.#options?.rules) {
+            rules.push(...this.#options.rules);
         }
-        this.emit('rules', __classPrivateFieldGet(this, _MLEngine_file, "f").path, rules);
+        this.emit('rules', this.#file.path, rules);
         return rules;
     }
     resolveRuleset(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     configSet) {
         const ruleset = convertRuleset(configSet.config);
-        this.emit('ruleset', __classPrivateFieldGet(this, _MLEngine_file, "f").path, ruleset);
+        this.emit('ruleset', this.#file.path, ruleset);
         return ruleset;
     }
     async resolveSchemas(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     configSet) {
-        const { schemas } = await resolveSpecs(__classPrivateFieldGet(this, _MLEngine_file, "f").path, configSet.config.specs);
-        this.emit('schemas', __classPrivateFieldGet(this, _MLEngine_file, "f").path, schemas);
+        const { schemas } = await resolveSpecs(this.#file.path, configSet.config.specs);
+        this.emit('schemas', this.#file.path, schemas);
         return schemas;
     }
     async setup() {
-        if (__classPrivateFieldGet(this, _MLEngine_core, "f")) {
-            return __classPrivateFieldGet(this, _MLEngine_core, "f");
+        if (this.#core) {
+            return this.#core;
         }
         const fabric = await this.provide();
         if (!fabric) {
             return null;
         }
         if (fabric.configErrors) {
-            this.emit('config-errors', __classPrivateFieldGet(this, _MLEngine_file, "f").path, fabric.configErrors);
+            this.emit('config-errors', this.#file.path, fabric.configErrors);
         }
         return this.createCore(fabric);
     }
 }
-_MLEngine_configProvider = new WeakMap(), _MLEngine_core = new WeakMap(), _MLEngine_file = new WeakMap(), _MLEngine_options = new WeakMap(), _MLEngine_watcher = new WeakMap();

package/lib/api/types.d.ts

@@ -2,6 +2,9 @@ import type { ConfigSet } from '@markuplint/file-resolver';
 import type { LocaleSet } from '@markuplint/i18n';
 import type { Config, SeverityOptions, Violation } from '@markuplint/ml-config';
 import type { AnyMLRule, MLSchema, Ruleset } from '@markuplint/ml-core';
+/**
+ * Options for the markuplint API, controlling configuration, locale, rules, and behavior.
+ */
 export type APIOptions = {
     readonly configFile?: string;
     readonly config?: Config;
@@ -18,6 +21,9 @@ export type APIOptions = {
      */
     readonly autoLoad?: boolean;
 };
+/**
+ * Event map for the {@link MLEngine}, defining all emitted events and their payload types.
+ */
 export type MLEngineEventMap = {
     log: [phase: string, message: string];
     config: [filePath: string, config: ConfigSet, message?: string];

package/lib/api/v1.d.ts

@@ -2,9 +2,14 @@ import type { MLResultInfo } from '../types.js';
 import type { Config, PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import type { MLRule } from '@markuplint/ml-core';
 /**
- * @deprecated
- * @param options
- * @returns
+ * 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: {
     /**

package/lib/api/v1.js

@@ -1,9 +1,14 @@
 import { toNoEmptyStringArrayFromStringOrArray } from '@markuplint/shared';
 import { lint } from './lint.js';
 /**
- * @deprecated
- * @param options
- * @returns
+ * 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);

package/lib/cli/bootstrap.d.ts

@@ -1,5 +1,13 @@
 import type { ReadonlyDeep } from 'type-fest';
-export declare const help = "\nUsage\n\t$ markuplint <HTML file paths (glob format)>\n\t$ <stdout> | markuplint\n\nOptions\n\t--config,                -c FILE_PATH  A configuration file path.\n\t--fix,                                 Fix HTML.\n\t--format,                -f FORMAT     Output format. Support \"JSON\", \"Simple\", \"GitHub\" and \"Standard\". Default: \"Standard\".\n\t--no-search-config                     No search a configure file automatically.\n\t--ignore-ext                           Evaluate files that are received even though the type of extension.\n\t--no-import-preset-rules               No import preset rules.\n\t--locale                               Locale of the message of violation. Default is an OS setting.\n\t--no-color,                            Output no color.\n\t--problem-only,          -p            Output only problems, without passeds.\n\t--allow-warnings                       Return status code 0 even if there are warnings.\n\t--allow-empty-input                    Return status code 1 even if there are no input files.\n\t--show-config                          Output computed configuration of the target file. Supports \"details\" and empty. Default: empty.\n\t--verbose                              Output with detailed information.\n\t--include-node-modules                 Include files in node_modules directory. Default: false.\n\t--severity-parse-error                 Specifies the severity level of parse errors. Supports \"error\", \"warning\", and \"off\". Default: \"error\".\n\t--max-count                            Limit the number of violations shown. Default: 0 (no limit).\n\t--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).\n\t--progressive-output                   Output results immediately after processing each file. Default: false.\n\n\t--init                                 Initialize settings interactively.\n\t--search                               Search lines of codes that include the target element by selectors.\n\n\t--help,                  -h            Show help.\n\t--version,               -v            Show version.\n\nExamples\n\t$ markuplint verifyee.html --config path/to/.markuplintrc\n\t$ cat verifyee.html | markuplint\n";
+/**
+ * Help text displayed when the CLI is invoked with `--help` or without arguments.
+ * Documents all available options, flags, and usage examples.
+ */
+export declare const help = "\nUsage\n\t$ markuplint <HTML file paths (glob format)>\n\t$ <stdout> | markuplint\n\nOptions\n\t--config,                -c FILE_PATH  A configuration file path.\n\t--fix,                                 Fix HTML.\n\t--format,                -f FORMAT     Output format. Support \"JSON\", \"Simple\", \"GitHub\" and \"Standard\". Default: \"Standard\".\n\t--no-search-config                     No search a configure file automatically.\n\t--ignore-ext                           Evaluate files that are received even though the type of extension.\n\t--no-import-preset-rules               No import preset rules.\n\t--locale                               Locale of the message of violation. Default is an OS setting.\n\t--no-color,                            Output no color.\n\t--problem-only,          -p            Output only problems, without passeds.\n\t--no-allow-warnings                    Return status code 1 even if there are warnings.\n\t--allow-empty-input                    Return status code 1 even if there are no input files.\n\t--show-config                          Output computed configuration of the target file. Supports \"details\" and empty. Default: empty.\n\t--verbose                              Output with detailed information.\n\t--include-node-modules                 Include files in node_modules directory. Default: false.\n\t--severity-parse-error                 Specifies the severity level of parse errors. Supports \"error\", \"warning\", and \"off\". Default: \"error\".\n\t--max-count                            Limit the number of violations shown. Default: 0 (no limit).\n\t--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).\n\t--progressive-output                   Output results immediately after processing each file. Default: false.\n\n\t--init                                 Initialize settings interactively.\n\t--search                               Search lines of codes that include the target element by selectors.\n\n\t--help,                  -h            Show help.\n\t--version,               -v            Show version.\n\nExamples\n\t$ markuplint verifyee.html --config path/to/.markuplintrc\n\t$ cat verifyee.html | markuplint\n";
+/**
+ * The parsed CLI instance created by `meow`, providing access to
+ * positional arguments (`cli.input`) and parsed flags (`cli.flags`).
+ */
 export declare const cli: import("meow").Result<{
     config: {
         type: "string";
@@ -39,7 +47,7 @@ export declare const cli: import("meow").Result<{
     };
     allowWarnings: {
         type: "boolean";
-        default: false;
+        default: true;
     };
     allowEmptyInput: {
         type: "boolean";
@@ -84,4 +92,8 @@ export declare const cli: import("meow").Result<{
         default: false;
     };
 }>;
+/**
+ * Deeply read-only type representing the parsed CLI flags.
+ * Derived from the `meow` flag definitions in {@link cli}.
+ */
 export type CLIOptions = ReadonlyDeep<typeof cli.flags>;

package/lib/cli/bootstrap.js

@@ -1,4 +1,8 @@
 import meow from 'meow';
+/**
+ * Help text displayed when the CLI is invoked with `--help` or without arguments.
+ * Documents all available options, flags, and usage examples.
+ */
 export const help = `
 Usage
 	$ markuplint <HTML file paths (glob format)>
@@ -14,7 +18,7 @@ Options
 	--locale                               Locale of the message of violation. Default is an OS setting.
 	--no-color,                            Output no color.
 	--problem-only,          -p            Output only problems, without passeds.
-	--allow-warnings                       Return status code 0 even if there are warnings.
+	--no-allow-warnings                    Return status code 1 even if there are warnings.
 	--allow-empty-input                    Return status code 1 even if there are no input files.
 	--show-config                          Output computed configuration of the target file. Supports "details" and empty. Default: empty.
 	--verbose                              Output with detailed information.
@@ -34,6 +38,10 @@ Examples
 	$ markuplint verifyee.html --config path/to/.markuplintrc
 	$ cat verifyee.html | markuplint
 `;
+/**
+ * The parsed CLI instance created by `meow`, providing access to
+ * positional arguments (`cli.input`) and parsed flags (`cli.flags`).
+ */
 export const cli = meow(help, {
     importMeta: import.meta,
     flags: {
@@ -75,8 +83,7 @@ export const cli = meow(help, {
         },
         allowWarnings: {
             type: 'boolean',
-            // TODO: It will be changed to `true` in the next major version.
-            default: false,
+            default: true,
         },
         allowEmptyInput: {
             type: 'boolean',

package/lib/cli/command.d.ts

@@ -1,4 +1,16 @@
 import type { CLIOptions } from './bootstrap.js';
 import type { APIOptions } from '../api/types.js';
 import type { Target } from '@markuplint/file-resolver';
+/**
+ * Executes the markuplint linting command against the given files.
+ *
+ * Resolves file targets, creates an {@link MLEngine} for each file, collects
+ * violations, and outputs results in the requested format. When the `--fix`
+ * flag is set, overwrites files with their auto-fixed content.
+ *
+ * @param files - The list of file targets (paths or inline source code) to lint.
+ * @param options - CLI options controlling output format, fix mode, locale, and other behaviors.
+ * @param apiOptions - Optional overrides for the underlying API (e.g., custom rules or config).
+ * @returns `true` if any errors were found (or warnings exceeded the limit), `false` otherwise.
+ */
 export declare function command(files: readonly Readonly<Target>[], options: CLIOptions, apiOptions?: APIOptions): Promise<boolean>;

package/lib/cli/command.js

@@ -5,6 +5,18 @@ import { ViolationCollector } from '@markuplint/ml-core';
 import { MLEngine } from '../api/index.js';
 import { log } from '../debug.js';
 import { output } from './output.js';
+/**
+ * Executes the markuplint linting command against the given files.
+ *
+ * Resolves file targets, creates an {@link MLEngine} for each file, collects
+ * violations, and outputs results in the requested format. When the `--fix`
+ * flag is set, overwrites files with their auto-fixed content.
+ *
+ * @param files - The list of file targets (paths or inline source code) to lint.
+ * @param options - CLI options controlling output format, fix mode, locale, and other behaviors.
+ * @param apiOptions - Optional overrides for the underlying API (e.g., custom rules or config).
+ * @returns `true` if any errors were found (or warnings exceeded the limit), `false` otherwise.
+ */
 export async function command(files, options, apiOptions) {
     const fix = options.fix;
     const configFile = options.config &&

package/lib/cli/index.d.ts

@@ -1 +1,8 @@
+/**
+ * @module cli
+ *
+ * CLI entry point for markuplint.
+ * Parses command-line arguments, dispatches to the appropriate handler
+ * (lint, init, search, or help), and manages the process exit code.
+ */
 export {};

package/lib/cli/index.js

@@ -1,3 +1,10 @@
+/**
+ * @module cli
+ *
+ * CLI entry point for markuplint.
+ * Parses command-line arguments, dispatches to the appropriate handler
+ * (lint, init, search, or help), and manages the process exit code.
+ */
 import { text } from 'node:stream/consumers';
 import { verbosely } from '../debug.js';
 import { cli } from './bootstrap.js';

package/lib/cli/init/create-config.d.ts

@@ -1,4 +1,20 @@
 import type { DefaultRules, Langs, RuleSettingMode } from './types.js';
 import type { Config } from '@markuplint/ml-config';
+/**
+ * Human-readable display names for each supported template language/framework,
+ * shown in the interactive init wizard prompts.
+ */
 export declare const langs: Record<Langs, string>;
+/**
+ * Builds a markuplint configuration object based on the user's init wizard selections.
+ *
+ * Configures parsers and spec modules for the selected template languages,
+ * and populates rules based on the chosen rule-setting mode (custom categories,
+ * recommended preset, or all defaults).
+ *
+ * @param langs - The template languages/frameworks selected by the user.
+ * @param mode - The rule selection mode: an array of categories, `'recommended'`, or `'none'`.
+ * @param defaultRules - The full set of available default rules with their categories and values.
+ * @returns A complete markuplint `Config` object ready to be serialized to a file.
+ */
 export declare function createConfig(langs: readonly Langs[], mode: RuleSettingMode, defaultRules: DefaultRules): Config;