@markuplint/ml-config 4.8.13 → 4.8.15

package/lib/types.d.ts

@@ -2,6 +2,10 @@ import type { ParserOptions } from '@markuplint/ml-ast';
 import type { RegexSelector } from '@markuplint/selector';
 import type { Nullable } from '@markuplint/shared';
 export type { RegexSelector } from '@markuplint/selector';
+/**
+ * The root configuration object for markuplint.
+ * Defines rules, parsers, specs, plugins, and overrides for linting markup.
+ */
 export type Config = {
     readonly $schema?: string;
     readonly extends?: string | readonly string[];
@@ -18,32 +22,65 @@ export type Config = {
     readonly overrideMode?: 'merge' | 'reset';
     readonly overrides?: Readonly<Record<string, OverrideConfig>>;
 };
+/**
+ * A primitive scalar value that can appear in rule configuration.
+ */
 export type PrimitiveScalar = string | number | boolean;
+/**
+ * A JSON-compatible data structure used for rule options and plugin settings.
+ * Can be a primitive, null/undefined, an array of `PlainData`, or a plain object.
+ */
 export type PlainData = Nullable<PrimitiveScalar> | readonly PlainData[] | {
     readonly [key: string]: PlainData | any;
 };
+/**
+ * A non-nullable variant of {@link PlainData}, excluding `null` and `undefined`.
+ */
 export type NonNullablePlainData = PrimitiveScalar | readonly NonNullablePlainData[] | {
     readonly [key: string]: NonNullablePlainData;
 };
 type NoInherit = '$schema' | 'extends' | 'overrideMode' | 'overrides';
+/**
+ * Configuration applied to specific file patterns via the `overrides` field.
+ * Excludes top-level-only properties like `$schema`, `extends`, `overrideMode`, and `overrides`.
+ */
 export type OverrideConfig = Omit<Config, NoInherit>;
+/**
+ * A fully resolved and optimized configuration after merging.
+ * Plugins are normalized to objects, and pretenders are converted to {@link PretenderDetails}.
+ */
 export type OptimizedConfig = Omit<Config, '$schema' | 'extends' | 'plugins' | 'pretenders' | 'overrides'> & {
     readonly extends?: readonly string[];
     readonly plugins?: readonly PluginConfig[];
     readonly pretenders?: PretenderDetails;
     readonly overrides?: Readonly<Record<string, OptimizedOverrideConfig>>;
 };
+/**
+ * An optimized override configuration, excluding top-level-only properties.
+ */
 export type OptimizedOverrideConfig = Omit<OptimizedConfig, NoInherit>;
+/**
+ * Configuration for a single markuplint plugin.
+ */
 export type PluginConfig = {
     readonly name: string;
     readonly settings?: Readonly<Record<string, NonNullablePlainData>>;
 };
+/**
+ * Maps file extension patterns to parser module names or paths.
+ */
 export type ParserConfig = {
     readonly [extensionPattern: string]: string;
 };
+/**
+ * Maps file extension patterns to spec module names or paths.
+ */
 export type SpecConfig = {
     readonly [extensionPattern: string]: string;
 };
+/**
+ * Options for controlling the severity of specific diagnostic categories.
+ */
 export type SeverityOptions = {
     readonly parseError?: Severity | 'off' | boolean;
 };
@@ -58,6 +95,9 @@ export type PretenderDetails = {
     readonly imports?: readonly string[];
     readonly data?: readonly Pretender[];
 };
+/**
+ * Data structure for a pretender definition file.
+ */
 export type PretenderFileData = {
     readonly version: string;
     readonly data: readonly Pretender[];
@@ -218,23 +258,45 @@ export interface PretenderScanOptions {
     readonly cwd?: string;
     readonly ignoreComponentNames?: readonly string[];
 }
+/**
+ * A rule setting: either a full {@link RuleConfig} object, a direct value, or a boolean to enable/disable.
+ *
+ * @template T - The type of the rule's value
+ * @template O - The type of the rule's options
+ */
 export type Rule<T extends RuleConfigValue, O extends PlainData = undefined> = RuleConfig<T, O> | Readonly<T> | boolean;
 /**
  * @deprecated
  */
 export type RuleV2<T extends RuleConfigValue, O extends PlainData = undefined> = RuleConfigV2<T, O> | Readonly<T> | boolean;
+/**
+ * A rule setting with any value and option types.
+ */
 export type AnyRule = Rule<RuleConfigValue, PlainData>;
 /**
  * @deprecated
  */
 export type AnyRuleV2 = RuleV2<RuleConfigValue, PlainData>;
+/**
+ * A dictionary mapping rule names to their configurations.
+ */
 export type Rules = {
     readonly [ruleName: string]: AnyRule;
 };
+/**
+ * Full configuration for a single rule, specifying severity, value, options, and reason.
+ *
+ * @template T - The type of the rule's value
+ * @template O - The type of the rule's options
+ */
 export type RuleConfig<T extends RuleConfigValue, O extends PlainData = undefined> = {
+    /** The severity level for violations of this rule */
     readonly severity?: Severity;
+    /** The rule's primary configuration value */
     readonly value?: Readonly<T>;
+    /** Additional options for the rule */
     readonly options?: Readonly<O>;
+    /** A human-readable reason for this rule configuration, included in violation messages */
     readonly reason?: string;
 };
 /**
@@ -252,8 +314,18 @@ export type RuleConfigV2<T extends RuleConfigValue, O extends PlainData = undefi
      */
     readonly option?: Readonly<O>;
 };
+/**
+ * The severity level of a lint violation.
+ */
 export type Severity = 'error' | 'warning' | 'info';
+/**
+ * The value portion of a rule configuration. Can be a primitive scalar,
+ * an array of scalars or objects, or `null` to represent no value.
+ */
 export type RuleConfigValue = PrimitiveScalar | readonly (PrimitiveScalar | Readonly<Record<string, any>>)[] | null;
+/**
+ * A rule override that targets specific nodes by CSS selector, regex selector, ARIA roles, or categories.
+ */
 export type NodeRule = {
     readonly selector?: string;
     readonly regexSelector?: RegexSelector;
@@ -262,29 +334,57 @@ export type NodeRule = {
     readonly obsolete?: boolean;
     readonly rules?: Rules;
 };
+/**
+ * A rule override that targets child nodes of elements matching the selector.
+ */
 export type ChildNodeRule = {
     readonly selector?: string;
     readonly regexSelector?: RegexSelector;
     readonly inheritance?: boolean;
     readonly rules?: Rules;
 };
+/**
+ * A violation report from a rule. Can report against a scope (node-based)
+ * or against explicit line/column coordinates, or both.
+ *
+ * @template T - The type of the rule's value
+ * @template O - The type of the rule's options
+ */
 export type Report<T extends RuleConfigValue, O extends PlainData = undefined> = Report1<T, O> | Report2 | (Report1<T, O> & Report2);
+/**
+ * A scope-based violation report, referencing the rule info and position via a {@link Scope}.
+ *
+ * @template T - The type of the rule's value
+ * @template O - The type of the rule's options
+ */
 export type Report1<T extends RuleConfigValue, O extends PlainData = undefined> = {
     readonly message: string;
     readonly scope: Scope<T, O>;
 };
+/**
+ * A coordinate-based violation report with explicit line, column, and raw text.
+ */
 export type Report2 = {
     readonly message: string;
     readonly line: number;
     readonly col: number;
     readonly raw: string;
 };
+/**
+ * Identifies the location and rule context of a reported violation.
+ *
+ * @template T - The type of the rule's value
+ * @template O - The type of the rule's options
+ */
 export type Scope<T extends RuleConfigValue, O extends PlainData = undefined> = {
     readonly rule: RuleInfo<T, O>;
     readonly startLine: number;
     readonly startCol: number;
     readonly raw: string;
 };
+/**
+ * A fully resolved lint violation with all information needed for reporting.
+ */
 export type Violation = {
     readonly ruleId: string;
     readonly severity: Severity;
@@ -294,6 +394,12 @@ export type Violation = {
     readonly col: number;
     readonly raw: string;
 };
+/**
+ * Resolved rule information after configuration merging, used at runtime by rules.
+ *
+ * @template T - The type of the rule's value
+ * @template O - The type of the rule's options
+ */
 export type RuleInfo<T extends RuleConfigValue, O extends PlainData = undefined> = {
     readonly disabled: boolean;
     readonly severity: Severity;
@@ -301,6 +407,12 @@ export type RuleInfo<T extends RuleConfigValue, O extends PlainData = undefined>
     readonly options: Readonly<O>;
     readonly reason?: string;
 };
+/**
+ * Extended rule information that includes node-level and child-node-level overrides.
+ *
+ * @template T - The type of the rule's value
+ * @template O - The type of the rule's options
+ */
 export type GlobalRuleInfo<T extends RuleConfigValue, O extends PlainData = undefined> = RuleInfo<T, O> & {
     nodeRules: RuleInfo<T, O>[];
     childNodeRules: RuleInfo<T, O>[];

package/lib/utils.d.ts

@@ -1,18 +1,45 @@
 import type { AnyRule, AnyRuleV2, PlainData, RuleConfig, RuleConfigV2, RuleConfigValue } from './types.js';
 /**
- * Return undefined if the template doesn't include the variable that is set as a property in data.
- * But return template string without changes if it doesn't have a variable.
+ * Renders a Mustache template with the provided data.
  *
- * @param template Mustache template string
- * @param data Captured string for replacement
+ * Returns `undefined` if the template contains variables but none of them
+ * are present in `data`. Returns the template unchanged if it has no variables.
+ *
+ * @param template - A Mustache template string with `{{variable}}` placeholders
+ * @param data - Key-value pairs for template variable replacement
+ * @returns The rendered string, or `undefined` if no matching variables were found
  */
 export declare function provideValue(template: string, data: Readonly<Record<string, string>>): string | undefined;
+/**
+ * Applies Mustache template rendering to all string values within a rule configuration,
+ * including the rule's value, options, and reason fields.
+ *
+ * @param rule - The rule configuration containing potential template strings
+ * @param data - Key-value pairs for template variable replacement
+ * @returns The rule with all template strings rendered, or `undefined` if rendering fails
+ */
 export declare function exchangeValueOnRule(rule: AnyRule | AnyRuleV2, data: Readonly<Record<string, string>>): AnyRule | undefined;
+/**
+ * Normalizes a rule configuration by extracting the standard fields
+ * (`severity`, `value`, `options`, `reason`) and removing `undefined` properties.
+ * Also handles the deprecated `option` field by mapping it to `options`.
+ *
+ * @param rule - The rule configuration to normalize
+ * @returns A clean rule configuration with only defined properties
+ */
 export declare function cleanOptions(rule: RuleConfig<RuleConfigValue, PlainData> | RuleConfigV2<RuleConfigValue, PlainData>): RuleConfig<RuleConfigValue, PlainData>;
+/**
+ * Type guard that checks whether a value is a {@link RuleConfigValue}
+ * (i.e. a primitive, `null`, or an array) rather than a full {@link RuleConfig} object.
+ *
+ * @param v - The value to check
+ * @returns `true` if `v` is a rule config value (string, number, boolean, null, or array)
+ */
 export declare function isRuleConfigValue(v: any): v is RuleConfigValue;
 /**
+ * Removes all properties with `undefined` values from a plain object in-place.
+ * Has no effect on non-plain-object values.
  *
- * @param obj
- * @returns
+ * @param obj - The object to clean up
  */
 export declare function deleteUndefProp(obj: any): void;

package/lib/utils.js

@@ -2,11 +2,14 @@
 import { isPlainObject } from 'is-plain-object';
 import mustache from 'mustache';
 /**
- * Return undefined if the template doesn't include the variable that is set as a property in data.
- * But return template string without changes if it doesn't have a variable.
+ * Renders a Mustache template with the provided data.
  *
- * @param template Mustache template string
- * @param data Captured string for replacement
+ * Returns `undefined` if the template contains variables but none of them
+ * are present in `data`. Returns the template unchanged if it has no variables.
+ *
+ * @param template - A Mustache template string with `{{variable}}` placeholders
+ * @param data - Key-value pairs for template variable replacement
+ * @returns The rendered string, or `undefined` if no matching variables were found
  */
 export function provideValue(template, data) {
     const ast = mustache.parse(template);
@@ -22,6 +25,14 @@ export function provideValue(template, data) {
     }
     return result;
 }
+/**
+ * Applies Mustache template rendering to all string values within a rule configuration,
+ * including the rule's value, options, and reason fields.
+ *
+ * @param rule - The rule configuration containing potential template strings
+ * @param data - Key-value pairs for template variable replacement
+ * @returns The rule with all template strings rendered, or `undefined` if rendering fails
+ */
 export function exchangeValueOnRule(rule, data) {
     if (isRuleConfigValue(rule)) {
         return exchangeValue(rule, data);
@@ -55,6 +66,14 @@ export function exchangeValueOnRule(rule, data) {
     deleteUndefProp(result);
     return result;
 }
+/**
+ * Normalizes a rule configuration by extracting the standard fields
+ * (`severity`, `value`, `options`, `reason`) and removing `undefined` properties.
+ * Also handles the deprecated `option` field by mapping it to `options`.
+ *
+ * @param rule - The rule configuration to normalize
+ * @returns A clean rule configuration with only defined properties
+ */
 export function cleanOptions(rule) {
     const res = {
         severity: rule.severity,
@@ -65,6 +84,13 @@ export function cleanOptions(rule) {
     deleteUndefProp(res);
     return res;
 }
+/**
+ * Type guard that checks whether a value is a {@link RuleConfigValue}
+ * (i.e. a primitive, `null`, or an array) rather than a full {@link RuleConfig} object.
+ *
+ * @param v - The value to check
+ * @returns `true` if `v` is a rule config value (string, number, boolean, null, or array)
+ */
 export function isRuleConfigValue(v) {
     switch (typeof v) {
         case 'string':
@@ -79,9 +105,10 @@ export function isRuleConfigValue(v) {
     return Array.isArray(v);
 }
 /**
+ * Removes all properties with `undefined` values from a plain object in-place.
+ * Has no effect on non-plain-object values.
  *
- * @param obj
- * @returns
+ * @param obj - The object to clean up
  */
 export function deleteUndefProp(obj) {
     if (!isPlainObject(obj)) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-config",
-	"version": "4.8.13",
+	"version": "4.8.15",
 	"description": "JSON Schema and TypeScript types of markuplint configure JSON",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -24,15 +24,15 @@
 		"clean": "tsc --build --clean  tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/ml-spec": "4.10.0",
-		"@markuplint/selector": "4.7.6",
-		"@markuplint/shared": "4.4.12",
+		"@markuplint/ml-ast": "4.4.11",
+		"@markuplint/ml-spec": "4.10.2",
+		"@markuplint/selector": "4.7.8",
+		"@markuplint/shared": "4.4.13",
 		"@types/mustache": "4.2.6",
 		"deepmerge": "4.3.1",
 		"is-plain-object": "5.0.0",
 		"mustache": "4.2.0",
 		"type-fest": "4.41.0"
 	},
-	"gitHead": "ae97eb2d31ecedf4f0800fbbf18588aad4ebca04"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }