@markuplint/file-resolver 4.9.17 → 4.18.0

package/CHANGELOG.md

@@ -3,13 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.9.17](https://github.com/markuplint/markuplint/compare/@markuplint/file-resolver@4.9.16...@markuplint/file-resolver@4.9.17) (2025-11-05)
+# [4.18.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v4.18.0) (2026-04-22)
 
 **Note:** Version bump only for package @markuplint/file-resolver
 
+## [4.9.19](https://github.com/markuplint/markuplint/compare/@markuplint/file-resolver@4.9.18...@markuplint/file-resolver@4.9.19) (2026-04-21)
+
+**Note:** Version bump only for package @markuplint/file-resolver
 
+## [4.9.18](https://github.com/markuplint/markuplint/compare/@markuplint/file-resolver@4.9.17...@markuplint/file-resolver@4.9.18) (2026-02-10)
 
+**Note:** Version bump only for package @markuplint/file-resolver
 
+## [4.9.17](https://github.com/markuplint/markuplint/compare/@markuplint/file-resolver@4.9.16...@markuplint/file-resolver@4.9.17) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/file-resolver
 
 ## [4.9.16](https://github.com/markuplint/markuplint/compare/@markuplint/file-resolver@4.9.15...@markuplint/file-resolver@4.9.16) (2025-08-24)
 

package/lib/config-provider.d.ts

@@ -2,14 +2,51 @@ import type { MLFile } from './ml-file/index.js';
 import type { ConfigSet } from './types.js';
 import type { OptimizedConfig } from '@markuplint/ml-config';
 import type { Nullable } from '@markuplint/shared';
+/**
+ * Manages loading, caching, and resolving markuplint configuration files.
+ *
+ * Handles `extends` chains, plugins, presets, overrides, and circular reference detection.
+ * Configuration files are searched via cosmiconfig and cached by file path.
+ */
 export declare class ConfigProvider {
     #private;
+    /**
+     * Recursively loads a configuration and all its `extends` dependencies.
+     *
+     * @param key - The config file path or module name to load
+     * @param cache - Whether to use cached results
+     * @param referrer - The file path of the config that referenced this key
+     * @param depth - Current recursion depth (for circular reference detection)
+     * @returns A set of loaded config keys and any errors encountered
+     */
     recursiveLoad(key: string, cache: boolean, referrer: string, depth?: number): Promise<{
         stack: Set<string>;
         errs: Error[];
     }>;
+    /**
+     * Resolves the full configuration for a target file by merging all named configs,
+     * resolving plugins, and applying file-specific overrides.
+     *
+     * @param targetFile - The file being linted
+     * @param names - Config file paths or module names to merge
+     * @param cache - Whether to use cached results
+     * @returns The fully resolved configuration set including plugins and errors
+     */
     resolve(targetFile: Readonly<MLFile>, names: readonly Nullable<string>[], cache?: boolean): Promise<ConfigSet>;
+    /**
+     * Searches for a markuplint configuration file starting from the target file's directory.
+     *
+     * @param targetFile - The file whose directory to search from
+     * @returns The file path of the found config, or `null` if none was found
+     */
     search(targetFile: Readonly<MLFile>): Promise<string | null>;
+    /**
+     * Stores a pre-built configuration in the provider's internal store.
+     *
+     * @param config - The optimized configuration to store
+     * @param key - An optional key to store the config under; auto-generated if omitted
+     * @returns The key under which the config was stored
+     */
     set(config: OptimizedConfig, key?: string): string;
     private _load;
     private _mergeConfigs;

package/lib/config-provider.js

@@ -22,6 +22,12 @@ import { cacheClear, resolvePlugins } from './resolve-plugins.js';
 import { fileExists, uuid } from './utils.js';
 const cpLog = log.extend('config-provider');
 const KEY_SEPARATOR = '__ML_CONFIG_MERGE__';
+/**
+ * Manages loading, caching, and resolving markuplint configuration files.
+ *
+ * Handles `extends` chains, plugins, presets, overrides, and circular reference detection.
+ * Configuration files are searched via cosmiconfig and cached by file path.
+ */
 export class ConfigProvider {
     constructor() {
         _ConfigProvider_cache.set(this, new Map());
@@ -29,6 +35,15 @@ export class ConfigProvider {
         _ConfigProvider_recursiveLoadKeyAndDepth.set(this, new Map());
         _ConfigProvider_store.set(this, new Map());
     }
+    /**
+     * Recursively loads a configuration and all its `extends` dependencies.
+     *
+     * @param key - The config file path or module name to load
+     * @param cache - Whether to use cached results
+     * @param referrer - The file path of the config that referenced this key
+     * @param depth - Current recursion depth (for circular reference detection)
+     * @returns A set of loaded config keys and any errors encountered
+     */
     async recursiveLoad(key, cache, referrer, depth = 1) {
         const stack = new Set();
         const errs = [];
@@ -67,6 +82,15 @@ export class ConfigProvider {
         stack.add(key);
         return { stack, errs };
     }
+    /**
+     * Resolves the full configuration for a target file by merging all named configs,
+     * resolving plugins, and applying file-specific overrides.
+     *
+     * @param targetFile - The file being linted
+     * @param names - Config file paths or module names to merge
+     * @param cache - Whether to use cached results
+     * @returns The fully resolved configuration set including plugins and errors
+     */
     async resolve(targetFile, names, cache = true) {
         if (!cache) {
             __classPrivateFieldGet(this, _ConfigProvider_store, "f").clear();
@@ -136,6 +160,12 @@ export class ConfigProvider {
         __classPrivateFieldGet(this, _ConfigProvider_cache, "f").set(key, result);
         return result;
     }
+    /**
+     * Searches for a markuplint configuration file starting from the target file's directory.
+     *
+     * @param targetFile - The file whose directory to search from
+     * @returns The file path of the found config, or `null` if none was found
+     */
     async search(targetFile) {
         const isExists = await targetFile.dirExists();
         cpLog('search: %s', targetFile.path);
@@ -154,6 +184,13 @@ export class ConfigProvider {
         cpLog('Store key: %s', filePath);
         return filePath;
     }
+    /**
+     * Stores a pre-built configuration in the provider's internal store.
+     *
+     * @param config - The optimized configuration to store
+     * @param key - An optional key to store the config under; auto-generated if omitted
+     * @returns The key under which the config was stored
+     */
     set(config, key) {
         key = key ?? uuid();
         __classPrivateFieldGet(this, _ConfigProvider_store, "f").set(key, config);

package/lib/resolve-files.d.ts

@@ -1,3 +1,11 @@
 import type { MLFile } from './ml-file/index.js';
 import type { Target } from './types.js';
+/**
+ * Resolves a list of targets (file globs or inline source code objects) into
+ * an array of {@link MLFile} instances.
+ *
+ * @param targetList - An array of file path globs or inline source code targets
+ * @param ignoreGlob - An optional glob pattern for files to exclude
+ * @returns An array of resolved MLFile instances
+ */
 export declare function resolveFiles(targetList: readonly Readonly<Target>[], ignoreGlob?: string): Promise<MLFile[]>;

package/lib/resolve-files.js

@@ -1,4 +1,12 @@
 import { getAnonymousFile, getFiles } from './ml-file/index.js';
+/**
+ * Resolves a list of targets (file globs or inline source code objects) into
+ * an array of {@link MLFile} instances.
+ *
+ * @param targetList - An array of file path globs or inline source code targets
+ * @param ignoreGlob - An optional glob pattern for files to exclude
+ * @returns An array of resolved MLFile instances
+ */
 export async function resolveFiles(targetList, ignoreGlob) {
     const res = [];
     for (const target of targetList) {

package/lib/resolve-parser.d.ts

@@ -1,6 +1,17 @@
 import type { MLFile } from './ml-file/index.js';
 import type { MLMarkupLanguageParser, MLParser, ParserOptions } from '@markuplint/ml-ast';
 import type { ParserConfig } from '@markuplint/ml-config';
+/**
+ * Resolves the appropriate parser for a given file based on the parser configuration.
+ *
+ * Matches the file's basename against patterns in the parser config to find
+ * the correct parser module. Falls back to the HTML parser if no pattern matches.
+ *
+ * @param file - The file to find a parser for
+ * @param parserConfig - A mapping of file extension patterns to parser module names
+ * @param parserOptions - Parser options to pass through
+ * @returns The resolved parser, its module name, parser options, and whether a pattern matched
+ */
 export declare function resolveParser(file: Readonly<MLFile>, parserConfig?: ParserConfig, parserOptions?: ParserOptions): Promise<{
     parserModName: string;
     parser: MLParser | MLMarkupLanguageParser;

package/lib/resolve-parser.js

@@ -2,6 +2,17 @@ import path from 'node:path';
 import { generalImport } from './general-import.js';
 import { toRegexp } from './utils.js';
 const parsers = new Map();
+/**
+ * Resolves the appropriate parser for a given file based on the parser configuration.
+ *
+ * Matches the file's basename against patterns in the parser config to find
+ * the correct parser module. Falls back to the HTML parser if no pattern matches.
+ *
+ * @param file - The file to find a parser for
+ * @param parserConfig - A mapping of file extension patterns to parser module names
+ * @param parserOptions - Parser options to pass through
+ * @returns The resolved parser, its module name, parser options, and whether a pattern matched
+ */
 export async function resolveParser(file, parserConfig, parserOptions) {
     parserConfig = {
         ...parserConfig,

package/lib/resolve-pretenders.d.ts

@@ -1,4 +1,11 @@
 import type { OptimizedConfig, Pretender } from '@markuplint/ml-config';
 type PretendersConfig = OptimizedConfig['pretenders'];
+/**
+ * Resolves pretender definitions from files, imported modules, and inline data
+ * in the configuration.
+ *
+ * @param config - The pretenders configuration section from the optimized config
+ * @returns An array of all resolved pretender definitions
+ */
 export declare function resolvePretenders(config: PretendersConfig): Promise<Pretender[]>;
 export {};

package/lib/resolve-pretenders.js

@@ -1,4 +1,11 @@
 import { generalImport } from './general-import.js';
+/**
+ * Resolves pretender definitions from files, imported modules, and inline data
+ * in the configuration.
+ *
+ * @param config - The pretenders configuration section from the optimized config
+ * @returns An array of all resolved pretender definitions
+ */
 export async function resolvePretenders(config) {
     if (!config) {
         return [];

package/lib/resolve-rules.d.ts

@@ -1,4 +1,16 @@
 import type { AnyMLRule, Ruleset, Plugin } from '@markuplint/ml-core';
+/**
+ * Resolves all rules from preset rules, plugins, and auto-loaded rules into
+ * a flat array of {@link MLRule} instances.
+ *
+ * @param plugins - The resolved plugins that may provide custom rules
+ * @param ruleset - The current ruleset (used for auto-loading)
+ * @param importPreset - Whether to import the built-in preset rules from `@markuplint/rules`
+ * @param autoLoad - Whether to auto-load rules referenced in the ruleset
+ * @returns An array of all resolved MLRule instances
+ *
+ * @deprecated The `autoLoad` parameter is deprecated
+ */
 export declare function resolveRules(plugins: readonly Plugin[], ruleset: Ruleset, importPreset: boolean, 
 /**
  * @deprecated

package/lib/resolve-rules.js

@@ -1,6 +1,18 @@
 import { MLRule } from '@markuplint/ml-core';
 import { autoLoadRules } from './auto-load-rules.js';
 let cachedPresetRules = null;
+/**
+ * Resolves all rules from preset rules, plugins, and auto-loaded rules into
+ * a flat array of {@link MLRule} instances.
+ *
+ * @param plugins - The resolved plugins that may provide custom rules
+ * @param ruleset - The current ruleset (used for auto-loading)
+ * @param importPreset - Whether to import the built-in preset rules from `@markuplint/rules`
+ * @param autoLoad - Whether to auto-load rules referenced in the ruleset
+ * @returns An array of all resolved MLRule instances
+ *
+ * @deprecated The `autoLoad` parameter is deprecated
+ */
 export async function resolveRules(plugins, ruleset, importPreset, 
 /**
  * @deprecated

package/lib/resolve-specs.d.ts

@@ -26,9 +26,9 @@ import type { ExtendedSpec, MLMLSpec } from '@markuplint/ml-spec';
  * }
  * ```
  *
- * @param filePath The lintee file path
- * @param specConfig The `spec` property part of the config
- * @returns
+ * @param filePath - The path of the file being linted, used for pattern matching
+ * @param specConfig - The `specs` property from the config, mapping file patterns to spec module names
+ * @returns An object containing the base HTML spec and any matched extended specs as a schemas tuple
  */
 export declare function resolveSpecs(filePath: string, specConfig?: SpecConfig): Promise<{
     schemas: readonly [MLMLSpec, ...ExtendedSpec[]];

package/lib/resolve-specs.js

@@ -28,9 +28,9 @@ const caches = new Map();
  * }
  * ```
  *
- * @param filePath The lintee file path
- * @param specConfig The `spec` property part of the config
- * @returns
+ * @param filePath - The path of the file being linted, used for pattern matching
+ * @param specConfig - The `specs` property from the config, mapping file patterns to spec module names
+ * @returns An object containing the base HTML spec and any matched extended specs as a schemas tuple
  */
 export async function resolveSpecs(filePath, specConfig) {
     const htmlSpec = await importSpecs('@markuplint/html-spec');

package/lib/types.d.ts

@@ -1,11 +1,22 @@
 import type { OptimizedConfig } from '@markuplint/ml-config';
 import type { Plugin } from '@markuplint/ml-core';
+/**
+ * A fully resolved configuration set including merged config, plugins, source file paths,
+ * and any errors encountered during resolution.
+ */
 export interface ConfigSet {
+    /** The merged and optimized configuration */
     readonly config: OptimizedConfig;
+    /** The resolved plugins */
     readonly plugins: readonly Plugin[];
+    /** The set of config file paths that contributed to this configuration */
     readonly files: ReadonlySet<string>;
+    /** Errors encountered during config loading or resolution */
     readonly errs: readonly Readonly<Error>[];
 }
+/**
+ * A lint target: either a file path/glob string, or an inline source code object.
+ */
 export type Target = string | {
     /**
      * Target source code of evaluation

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "4.9.17",
+	"version": "4.18.0",
 	"description": "The file resolver of markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -24,24 +24,24 @@
 		"clean": "tsc --build --clean"
 	},
 	"devDependencies": {
-		"@types/node": "24.5.1"
+		"@types/node": "24.12.2"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "4.6.22",
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/ml-config": "4.8.14",
-		"@markuplint/ml-core": "4.13.2",
-		"@markuplint/ml-spec": "4.10.1",
-		"@markuplint/parser-utils": "4.8.10",
-		"@markuplint/selector": "4.7.7",
-		"@markuplint/shared": "4.4.12",
-		"cosmiconfig": "9.0.0",
+		"@markuplint/html-parser": "4.18.0",
+		"@markuplint/ml-ast": "4.18.0",
+		"@markuplint/ml-config": "4.18.0",
+		"@markuplint/ml-core": "4.18.0",
+		"@markuplint/ml-spec": "4.18.0",
+		"@markuplint/parser-utils": "4.18.0",
+		"@markuplint/selector": "4.18.0",
+		"@markuplint/shared": "4.18.0",
+		"cosmiconfig": "9.0.1",
 		"debug": "4.4.3",
-		"glob": "11.0.3",
+		"glob": "13.0.6",
 		"ignore": "7.0.5",
 		"import-meta-resolve": "4.2.0",
 		"jsonc": "2.0.0",
-		"minimatch": "10.0.3"
+		"minimatch": "10.2.5"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "1885af6349def3f19df975b9e9c399dd47361de1"
 }