npm - markuplint - Versions diffs - 4.14.0 → 4.18.0 - Mend

markuplint 4.14.0 → 4.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/ARCHITECTURE.ja.md +419 -0
package/ARCHITECTURE.md +419 -0
package/CHANGELOG.md +22 -3
package/SKILL.md +110 -0
package/docs/maintenance.ja.md +207 -0
package/docs/maintenance.md +207 -0
package/lib/api/index.d.ts +8 -0
package/lib/api/index.js +8 -0
package/lib/api/lint.d.ts +7 -0
package/lib/api/lint.js +7 -0
package/lib/api/ml-engine.d.ts +48 -0
package/lib/api/ml-engine.js +43 -0
package/lib/api/types.d.ts +6 -0
package/lib/api/v1.d.ts +8 -3
package/lib/api/v1.js +8 -3
package/lib/cli/bootstrap.d.ts +12 -0
package/lib/cli/bootstrap.js +8 -0
package/lib/cli/command.d.ts +12 -0
package/lib/cli/command.js +12 -0
package/lib/cli/index.d.ts +7 -0
package/lib/cli/index.js +7 -0
package/lib/cli/init/create-config.d.ts +16 -0
package/lib/cli/init/create-config.js +20 -0
package/lib/cli/init/get-default-rules.d.ts +9 -0
package/lib/cli/init/get-default-rules.js +9 -0
package/lib/cli/init/index.d.ts +14 -0
package/lib/cli/init/index.js +14 -0
package/lib/cli/init/select-modules.d.ts +10 -0
package/lib/cli/init/select-modules.js +10 -0
package/lib/cli/init/types.d.ts +19 -0
package/lib/cli/output.d.ts +11 -0
package/lib/cli/output.js +11 -0
package/lib/cli/search/index.d.ts +17 -0
package/lib/cli/search/index.js +17 -0
package/lib/debug.d.ts +9 -0
package/lib/debug.js +9 -0
package/lib/get-json-module.d.ts +10 -0
package/lib/get-json-module.js +10 -0
package/lib/global-settings.d.ts +15 -0
package/lib/global-settings.js +12 -0
package/lib/i18n.d.ts +9 -0
package/lib/i18n.js +9 -0
package/lib/index.d.ts +14 -1
package/lib/index.js +13 -1
package/lib/reporter/github-reporter.d.ts +9 -0
package/lib/reporter/github-reporter.js +9 -0
package/lib/reporter/index.d.ts +9 -0
package/lib/reporter/index.js +9 -0
package/lib/reporter/simple-reporter.d.ts +11 -0
package/lib/reporter/simple-reporter.js +11 -0
package/lib/reporter/standard-reporter.d.ts +12 -0
package/lib/reporter/standard-reporter.js +12 -0
package/lib/testing-tool/index.d.ts +44 -0
package/lib/testing-tool/index.js +32 -0
package/lib/types.d.ts +3 -0
package/lib/v1.d.ts +3 -1
package/lib/v1.js +3 -1
package/lib/version.d.ts +3 -0
package/lib/version.js +3 -0
package/package.json +17 -17

package/lib/cli/bootstrap.d.ts CHANGED Viewed

@@ -1,5 +1,13 @@
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * 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--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";
+/**
+ * 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";
@@ -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 CHANGED Viewed

@@ -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)>
@@ -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: {

package/lib/cli/command.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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;

package/lib/cli/init/create-config.js CHANGED Viewed

@@ -1,3 +1,7 @@
+/**
+ * Maps each supported language/framework to a file-extension regular expression
+ * used in the generated configuration's `parser` field.
+ */
 const extRExp = {
     jsx: '\\.[jt]sx?$',
     vue: '\\.vue$',
@@ -14,6 +18,10 @@ const extRExp = {
     nunjucks: '\\.nunjucks$',
     liquid: '\\.liquid$',
 };
+/**
+ * Human-readable display names for each supported template language/framework,
+ * shown in the interactive init wizard prompts.
+ */
 export const langs = {
     jsx: 'React (JSX)',
     vue: 'Vue',
@@ -30,6 +38,18 @@ export const langs = {
     nunjucks: 'Nunjucks',
     liquid: 'liquid (Shopify)',
 };
+/**
+ * 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 function createConfig(langs, mode, defaultRules) {
     let config = {};
     const parser = { ...config.parser };

package/lib/cli/init/get-default-rules.d.ts CHANGED Viewed

@@ -1,3 +1,12 @@
+/**
+ * Collects all built-in rules that have a defined category and returns them
+ * as a record of rule name to rule metadata.
+ *
+ * Rules with `'warning'` default severity are disabled by default (`false`),
+ * while all others use their defined default value or `true`.
+ *
+ * @returns A read-only mapping from rule names to their category and default configuration value.
+ */
 export declare function getDefaultRules(): {
     [x: string]: import("./types.js").Rule;
 };

package/lib/cli/init/get-default-rules.js CHANGED Viewed

@@ -1,4 +1,13 @@
 import builtinRules from '@markuplint/rules';
+/**
+ * Collects all built-in rules that have a defined category and returns them
+ * as a record of rule name to rule metadata.
+ *
+ * Rules with `'warning'` default severity are disabled by default (`false`),
+ * while all others use their defined default value or `true`.
+ *
+ * @returns A read-only mapping from rule names to their category and default configuration value.
+ */
 export function getDefaultRules() {
     const rules = {};
     for (const [ruleName, rule] of Object.entries(builtinRules)) {

package/lib/cli/init/index.d.ts CHANGED Viewed

@@ -1 +1,15 @@
+/**
+ * @module cli/init
+ *
+ * Interactive initialization wizard for markuplint.
+ * Guides the user through selecting template engines, rule categories,
+ * and dependency installation, then writes a `.markuplintrc` config file.
+ */
+/**
+ * Runs the interactive initialization flow.
+ *
+ * Prompts the user to select template engines, choose rule categories or the
+ * recommended preset, generates a `.markuplintrc` configuration file in the
+ * current working directory, and optionally installs the required npm packages.
+ */
 export declare function initialize(): Promise<void>;

package/lib/cli/init/index.js CHANGED Viewed

@@ -1,3 +1,10 @@
+/**
+ * @module cli/init
+ *
+ * Interactive initialization wizard for markuplint.
+ * Guides the user through selecting template engines, rule categories,
+ * and dependency installation, then writes a `.markuplintrc` config file.
+ */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { installModule, multiSelect, confirm, confirmSequence, header } from '@markuplint/cli-utils';
@@ -21,6 +28,13 @@ const ruleCategories = {
         message: 'Are you going to check for the code styles?',
     },
 };
+/**
+ * Runs the interactive initialization flow.
+ *
+ * Prompts the user to select template engines, choose rule categories or the
+ * recommended preset, generates a `.markuplintrc` configuration file in the
+ * current working directory, and optionally installs the required npm packages.
+ */
 export async function initialize() {
     process.stdout.write(header('Initialization'));
     process.stdout.write('\n');

package/lib/cli/init/select-modules.d.ts CHANGED Viewed

@@ -1,2 +1,12 @@
 import type { Langs } from './types.js';
+/**
+ * Determines the list of npm modules that need to be installed based on the
+ * user's template language selections.
+ *
+ * Always includes `markuplint` itself, adds a parser package for each selected
+ * language, and includes spec packages for Vue and React when applicable.
+ *
+ * @param selectedLangs - The template languages/frameworks selected by the user.
+ * @returns An array of npm package names to install.
+ */
 export declare function selectModules(selectedLangs: readonly Langs[]): string[];

package/lib/cli/init/select-modules.js CHANGED Viewed

@@ -1,3 +1,13 @@
+/**
+ * Determines the list of npm modules that need to be installed based on the
+ * user's template language selections.
+ *
+ * Always includes `markuplint` itself, adds a parser package for each selected
+ * language, and includes spec packages for Vue and React when applicable.
+ *
+ * @param selectedLangs - The template languages/frameworks selected by the user.
+ * @returns An array of npm package names to install.
+ */
 export function selectModules(selectedLangs) {
     const modules = ['markuplint', ...selectedLangs.map(lang => `@markuplint/${lang}-parser`)];
     if (selectedLangs.includes('vue')) {

package/lib/cli/init/types.d.ts CHANGED Viewed

@@ -1,8 +1,27 @@
 import type { RuleConfigValue } from '@markuplint/ml-config';
+/**
+ * Identifiers for template engines and frameworks supported by the init wizard.
+ */
 export type Langs = 'jsx' | 'vue' | 'svelte' | 'sveltekit' | 'astro' | 'alpine' | 'pug' | 'php' | 'smarty' | 'erb' | 'ejs' | 'mustache' | 'nunjucks' | 'liquid';
+/**
+ * Rule categories used to group lint rules during interactive initialization.
+ */
 export type Category = 'validation' | 'a11y' | 'naming-convention' | 'style' | 'maintainability';
+/**
+ * Determines how rules are selected during initialization.
+ *
+ * - An array of {@link Category} values enables per-category customization.
+ * - `'recommended'` applies the built-in recommended preset.
+ * - `'none'` skips rule configuration entirely.
+ */
 export type RuleSettingMode = readonly Category[] | 'recommended' | 'none';
+/**
+ * A mapping from rule names to their metadata, used to populate default rule values.
+ */
 export type DefaultRules = Readonly<Record<string, Rule>>;
+/**
+ * Metadata for a single rule as used by the init wizard.
+ */
 export type Rule = {
     readonly category: Category;
     readonly defaultValue: RuleConfigValue;

package/lib/cli/output.d.ts CHANGED Viewed

@@ -1,3 +1,14 @@
 import type { CLIOptions } from './bootstrap.js';
 import type { MLResultInfo } from '../types.js';
+/**
+ * Writes lint results to stdout or stderr using the reporter selected by `--format`.
+ *
+ * Violations are written to stderr (and set `process.exitCode` to 1),
+ * while clean results are written to stdout. When `--no-color` is set,
+ * ANSI escape codes are stripped before output. JSON format is handled
+ * separately by the caller, so this function returns early for JSON.
+ *
+ * @param results - The lint result information for a single file.
+ * @param options - CLI options that control the output format and color.
+ */
 export declare function output(results: MLResultInfo, options: CLIOptions): void;

package/lib/cli/output.js CHANGED Viewed

@@ -1,5 +1,16 @@
 import stripAnsi from 'strip-ansi';
 import { simpleReporter, standardReporter, githubReporter } from '../reporter/index.js';
+/**
+ * Writes lint results to stdout or stderr using the reporter selected by `--format`.
+ *
+ * Violations are written to stderr (and set `process.exitCode` to 1),
+ * while clean results are written to stdout. When `--no-color` is set,
+ * ANSI escape codes are stripped before output. JSON format is handled
+ * separately by the caller, so this function returns early for JSON.
+ *
+ * @param results - The lint result information for a single file.
+ * @param options - CLI options that control the output format and color.
+ */
 export function output(results, options) {
     const format = options.format ?? 'Standard';
     let out;

package/lib/cli/search/index.d.ts CHANGED Viewed

@@ -1,2 +1,19 @@
+/**
+ * @module cli/search
+ *
+ * Element search subcommand for the markuplint CLI.
+ * Finds lines of code that match the given CSS selectors across the target files
+ * and outputs their locations in `file:line:col` format.
+ */
 import type { CLIOptions } from '../bootstrap.js';
+/**
+ * Searches the given files for elements matching a CSS selector and prints their locations.
+ *
+ * Internally creates a temporary lint rule that uses `document.querySelectorAll`
+ * to find matching nodes, then outputs each match as `file:line:col` to stdout.
+ *
+ * @param files - The file paths (or glob patterns) to search.
+ * @param options - CLI options forwarded to the underlying lint command.
+ * @param selectors - A CSS selector string to match elements against.
+ */
 export declare function search(files: readonly string[], options: CLIOptions, selectors: string): Promise<void>;

package/lib/cli/search/index.js CHANGED Viewed

@@ -1,5 +1,22 @@
+/**
+ * @module cli/search
+ *
+ * Element search subcommand for the markuplint CLI.
+ * Finds lines of code that match the given CSS selectors across the target files
+ * and outputs their locations in `file:line:col` format.
+ */
 import { createRule, MLRule } from '@markuplint/ml-core';
 import { command } from '../command.js';
+/**
+ * Searches the given files for elements matching a CSS selector and prints their locations.
+ *
+ * Internally creates a temporary lint rule that uses `document.querySelectorAll`
+ * to find matching nodes, then outputs each match as `file:line:col` to stdout.
+ *
+ * @param files - The file paths (or glob patterns) to search.
+ * @param options - CLI options forwarded to the underlying lint command.
+ * @param selectors - A CSS selector string to match elements against.
+ */
 export async function search(files, options, selectors) {
     const name = '__CLI_SEARCH__';
     const locations = [];

package/lib/debug.d.ts CHANGED Viewed

@@ -1,3 +1,12 @@
 import debug from 'debug';
+/**
+ * Debug logger instance for the markuplint CLI, using the `markuplint-cli` namespace.
+ */
 export declare const log: debug.Debugger;
+/**
+ * Enables verbose debug logging for both the CLI and the core library.
+ *
+ * When called, it activates the `markuplint-cli*` and `ml-*` debug namespaces
+ * and turns on the core library's internal debug output.
+ */
 export declare function verbosely(): void;

package/lib/debug.js CHANGED Viewed

@@ -1,6 +1,15 @@
 import { enableDebug } from '@markuplint/ml-core';
 import debug from 'debug';
+/**
+ * Debug logger instance for the markuplint CLI, using the `markuplint-cli` namespace.
+ */
 export const log = debug('markuplint-cli');
+/**
+ * Enables verbose debug logging for both the CLI and the core library.
+ *
+ * When called, it activates the `markuplint-cli*` and `ml-*` debug namespaces
+ * and turns on the core library's internal debug output.
+ */
 export function verbosely() {
     if (!log.enabled) {
         const namespace = `${log.namespace}*,ml-*`;

package/lib/get-json-module.d.ts CHANGED Viewed

@@ -1 +1,11 @@
+/**
+ * Loads a JSON module by its path using `require`, returning `null` if the module cannot be found.
+ *
+ * This is a safe wrapper around `require` that swallows resolution errors,
+ * making it suitable for optional module loading (e.g., locale files).
+ *
+ * @template T - The expected shape of the JSON module.
+ * @param modulePath - The module specifier or file path to load.
+ * @returns The parsed JSON module, or `null` if it could not be loaded.
+ */
 export declare function getJsonModule<T extends {}>(modulePath: string): T | null;

package/lib/get-json-module.js CHANGED Viewed

@@ -1,5 +1,15 @@
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
+/**
+ * Loads a JSON module by its path using `require`, returning `null` if the module cannot be found.
+ *
+ * This is a safe wrapper around `require` that swallows resolution errors,
+ * making it suitable for optional module loading (e.g., locale files).
+ *
+ * @template T - The expected shape of the JSON module.
+ * @param modulePath - The module specifier or file path to load.
+ * @returns The parsed JSON module, or `null` if it could not be loaded.
+ */
 export function getJsonModule(modulePath) {
     try {
         return require(modulePath);

package/lib/global-settings.d.ts CHANGED Viewed

@@ -1,5 +1,20 @@
+/**
+ * Shape of the global settings that apply across all markuplint operations.
+ */
 export type GlobalSettings = {
     readonly locale: string;
 };
+/**
+ * Merges the provided settings into the current global settings.
+ *
+ * Settings are shallowly merged, so only the specified keys are overwritten.
+ *
+ * @param settings - A partial set of global settings to apply.
+ */
 export declare function setGlobal(settings: Partial<GlobalSettings>): void;
+/**
+ * Returns the current global settings as a read-only object.
+ *
+ * @returns The current global settings.
+ */
 export declare function getGlobal(): Readonly<Partial<GlobalSettings>>;

package/lib/global-settings.js CHANGED Viewed

@@ -1,10 +1,22 @@
 let globalSettings = {};
+/**
+ * Merges the provided settings into the current global settings.
+ *
+ * Settings are shallowly merged, so only the specified keys are overwritten.
+ *
+ * @param settings - A partial set of global settings to apply.
+ */
 export function setGlobal(settings) {
     globalSettings = {
         ...globalSettings,
         ...settings,
     };
 }
+/**
+ * Returns the current global settings as a read-only object.
+ *
+ * @returns The current global settings.
+ */
 export function getGlobal() {
     return globalSettings;
 }

package/lib/i18n.d.ts CHANGED Viewed

@@ -1,2 +1,11 @@
 import type { LocaleSet } from '@markuplint/i18n';
+/**
+ * Loads the locale-specific message set for use in violation messages.
+ *
+ * If no locale is provided, it auto-detects the OS locale. When the requested
+ * locale is not available, it falls back to English (`en`).
+ *
+ * @param locale - An optional BCP 47 locale string (e.g., `"ja"`, `"en-US"`).
+ * @returns The loaded locale set containing translated messages and the resolved locale code.
+ */
 export declare function i18n(locale?: string): Promise<LocaleSet>;

package/lib/i18n.js CHANGED Viewed

@@ -7,6 +7,15 @@ async function getLocale() {
     }
     return cachedLocale;
 }
+/**
+ * Loads the locale-specific message set for use in violation messages.
+ *
+ * If no locale is provided, it auto-detects the OS locale. When the requested
+ * locale is not available, it falls back to English (`en`).
+ *
+ * @param locale - An optional BCP 47 locale string (e.g., `"ja"`, `"en-US"`).
+ * @returns The loaded locale set containing translated messages and the resolved locale code.
+ */
 export async function i18n(locale) {
     locale = locale ?? (await getLocale()) ?? 'en';
     const langCode = locale.split('-')[0] ?? locale;

package/lib/index.d.ts CHANGED Viewed

@@ -1,10 +1,23 @@
+/**
+ * @module markuplint
+ *
+ * Main package entry point for markuplint.
+ * Re-exports the public API surface including the lint engine, types,
+ * internationalization utilities, testing tools, and version information.
+ */
+/** The primary linting engine and options for linting from source code strings. */
 export { MLEngine, FromCodeOptions } from './api/index.js';
+/** Event map type describing events emitted by {@link MLEngine}. */
 export { MLEngineEventMap } from './api/types.js';
+/** Internationalization utilities for loading locale-specific message sets. */
 export * from './i18n.js';
+/** Testing utilities for verifying markuplint rules and configurations. */
 export * from './testing-tool/index.js';
+/** Shared type definitions for lint results and violations. */
 export * from './types.js';
+/** The current markuplint package version string. */
 export { version } from './version.js';
 /**
- * @deprecated
+ * @deprecated Use the current API exports instead.
  */
 export * from './v1.js';

package/lib/index.js CHANGED Viewed

@@ -1,9 +1,21 @@
+/**
+ * @module markuplint
+ *
+ * Main package entry point for markuplint.
+ * Re-exports the public API surface including the lint engine, types,
+ * internationalization utilities, testing tools, and version information.
+ */
+/** The primary linting engine and options for linting from source code strings. */
 export { MLEngine } from './api/index.js';
+/** Internationalization utilities for loading locale-specific message sets. */
 export * from './i18n.js';
+/** Testing utilities for verifying markuplint rules and configurations. */
 export * from './testing-tool/index.js';
+/** Shared type definitions for lint results and violations. */
 export * from './types.js';
+/** The current markuplint package version string. */
 export { version } from './version.js';
 /**
- * @deprecated
+ * @deprecated Use the current API exports instead.
  */
 export * from './v1.js';

package/lib/reporter/github-reporter.d.ts CHANGED Viewed

@@ -1,2 +1,11 @@
 import type { MLResultInfo } from '../types.js';
+/**
+ * Formats lint results as GitHub Actions workflow commands.
+ *
+ * Each violation is emitted as a `::error`, `::warning`, or `::notice` command
+ * that GitHub Actions interprets as an inline annotation on the affected file and line.
+ *
+ * @param results - The lint result information for a single file.
+ * @returns An array of GitHub Actions workflow command strings.
+ */
 export declare function githubReporter(results: MLResultInfo): string[];

package/lib/reporter/github-reporter.js CHANGED Viewed

@@ -1,4 +1,13 @@
 import { messageToString } from '@markuplint/cli-utils';
+/**
+ * Formats lint results as GitHub Actions workflow commands.
+ *
+ * Each violation is emitted as a `::error`, `::warning`, or `::notice` command
+ * that GitHub Actions interprets as an inline annotation on the affected file and line.
+ *
+ * @param results - The lint result information for a single file.
+ * @returns An array of GitHub Actions workflow command strings.
+ */
 export function githubReporter(results) {
     const out = [];
     for (const violation of results.violations) {

package/lib/reporter/index.d.ts CHANGED Viewed

@@ -1,3 +1,12 @@
+/**
+ * @module reporter
+ *
+ * Output reporters for markuplint lint results.
+ * Provides standard (detailed), simple (compact), and GitHub Actions annotation formats.
+ */
+/** Detailed multi-line reporter showing source context around each violation. */
 export * from './standard-reporter.js';
+/** Compact single-line-per-violation reporter. */
 export * from './simple-reporter.js';
+/** GitHub Actions workflow command reporter using `::error` and `::warning` annotations. */
 export * from './github-reporter.js';

package/lib/reporter/index.js CHANGED Viewed

@@ -1,3 +1,12 @@
+/**
+ * @module reporter
+ *
+ * Output reporters for markuplint lint results.
+ * Provides standard (detailed), simple (compact), and GitHub Actions annotation formats.
+ */
+/** Detailed multi-line reporter showing source context around each violation. */
 export * from './standard-reporter.js';
+/** Compact single-line-per-violation reporter. */
 export * from './simple-reporter.js';
+/** GitHub Actions workflow command reporter using `::error` and `::warning` annotations. */
 export * from './github-reporter.js';

package/lib/reporter/simple-reporter.d.ts CHANGED Viewed

@@ -1,3 +1,14 @@
 import type { CLIOptions } from '../cli/bootstrap.js';
 import type { MLResultInfo } from '../types.js';
+/**
+ * Formats lint results using the simple (compact) reporter.
+ *
+ * Produces one line per violation showing location, severity icon,
+ * message, and rule ID in a condensed format. Clean files display
+ * a check mark or warning icon unless `--problem-only` is set.
+ *
+ * @param results - The lint result information for a single file.
+ * @param options - CLI options controlling problem-only output.
+ * @returns An array of formatted output lines.
+ */
 export declare function simpleReporter(results: MLResultInfo, options: CLIOptions): string[];

package/lib/reporter/simple-reporter.js CHANGED Viewed

@@ -2,6 +2,17 @@ import { name, font, pad, getWidth, messageToString, xterm } from '@markuplint/c
 const commandName = name.toLowerCase();
 const loggerError = font.red;
 const loggerWarning = xterm(208);
+/**
+ * Formats lint results using the simple (compact) reporter.
+ *
+ * Produces one line per violation showing location, severity icon,
+ * message, and rule ID in a condensed format. Clean files display
+ * a check mark or warning icon unless `--problem-only` is set.
+ *
+ * @param results - The lint result information for a single file.
+ * @param options - CLI options controlling problem-only output.
+ * @returns An array of formatted output lines.
+ */
 export function simpleReporter(results, options) {
     const sizes = {
         line: 0,