markuplint 4.14.0 → 4.18.0

package/docs/maintenance.ja.md

@@ -0,0 +1,207 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                        | 説明                   |
+| ------------------------------- | ---------------------- |
+| `yarn build --scope markuplint` | このパッケージをビルド |
+| `yarn dev --scope markuplint`   | ウォッチモードでビルド |
+| `yarn clean --scope markuplint` | ビルド成果物を削除     |
+| `yarn test --scope markuplint`  | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
+
+| テストファイル                     | カバレッジ                                                            |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| `api/ml-engine.spec.ts`            | MLEngine ライフサイクル（イベント、watch モード、設定解決、fromCode） |
+| `cli/index.spec.ts`                | CLI 統合テスト（stdout 出力、fix モード、JSON 形式、フラグ）          |
+| `index.spec.ts`                    | パッケージ統合テスト（HTML ファイル linting エンドツーエンド）        |
+| `reporter/github-reporter.spec.ts` | GitHub Actions アノテーション出力形式                                 |
+| `cli/init/*.spec.ts`               | 初期化ウィザード（設定生成、モジュール選択）                          |
+| `i18n.spec.ts`                     | ロケール読み込みとフォールバック動作                                  |
+
+MLEngine テストの主なパターン:
+
+```ts
+import { MLEngine } from './api/index.js';
+
+const engine = await MLEngine.fromCode(sourceCode, {
+  config: { rules: { 'rule-name': true } },
+  locale: 'en',
+});
+const result = await engine.exec();
+expect(result?.violations).toStrictEqual([
+  // 期待される違反
+]);
+```
+
+テストユーティリティを使用したテスト:
+
+```ts
+import { mlRuleTest } from './testing-tool/index.js';
+
+const { violations } = await mlRuleTest(ruleSeed, '<div></div>', { rule: true });
+expect(violations).toStrictEqual([
+  // ruleId を含まない期待される違反
+]);
+```
+
+## レシピ
+
+### 1. 新しい CLI フラグの追加
+
+1. `src/cli/bootstrap.ts` を読み、`meow()` 内の `flags` オブジェクトを確認
+2. 新しいフラグ定義を追加:
+   ```ts
+   newFlag: {
+     type: 'boolean', // または 'string', 'number'
+     default: false,
+     shortFlag: 'n', // オプション
+   },
+   ```
+3. ファイル上部の `help` 文字列を更新し、新しいフラグをドキュメント化
+4. 注意: `CLIOptions` 型は自動更新される（`typeof cli.flags` から推論）
+5. `src/cli/command.ts` を読み、`options` からフラグ値を取得:
+   ```ts
+   const newFlag = options.newFlag;
+   ```
+6. `command()` 内にフラグの動作を実装、または `MLEngine` オプションに渡す
+7. フラグが API レイヤーに影響する場合、`src/api/types.ts` の `APIOptions` に対応プロパティを追加
+8. `src/cli/index.spec.ts` にテストを追加
+9. ビルド: `yarn build --scope markuplint`
+10. テスト: `yarn test --scope markuplint`
+
+### 2. 新しいレポーターの追加
+
+1. `src/reporter/` の既存レポーターを読みパターンを理解:
+   - 関数は `MLResultInfo`（およびオプションで `CLIOptions`）を受け取る
+   - `string[]` を返す（1要素 = 1出力行）
+2. `src/reporter/<name>-reporter.ts` を作成:
+
+   ```ts
+   import type { MLResultInfo } from '../types.js';
+
+   export function <name>Reporter(results: MLResultInfo) {
+     const out: string[] = [];
+     for (const violation of results.violations) {
+       out.push(/* 違反をフォーマット */);
+     }
+     return out;
+   }
+   ```
+
+3. `src/reporter/index.ts` からエクスポート:
+   ```ts
+   export * from './<name>-reporter.js';
+   ```
+4. `src/cli/output.ts` を読み、`switch` 文にケースを追加:
+   ```ts
+   case '<name>': {
+     out = <name>Reporter(results);
+     break;
+   }
+   ```
+5. `src/reporter/<name>-reporter.spec.ts` にテストを追加
+6. ビルド: `yarn build --scope markuplint`
+7. テスト: `yarn test --scope markuplint`
+
+### 3. 設定解決ロジックの変更
+
+1. `src/api/ml-engine.ts` を読み、`resolveConfig()` を確認
+2. 現在の優先順位を理解:
+   - `options.config`（インライン設定オブジェクト）
+   - `options.configFile`（明示的ファイルパス）
+   - `ConfigProvider.search()`（自動探索、`--no-search-config` でなければ）
+   - `options.defaultConfig`（フォールバック）
+   - `markuplint:recommended`（他に設定がない場合のデフォルト）
+3. `@markuplint/file-resolver` の `ConfigProvider` を理解:
+   - `set(config)` で設定を登録しキーを返す
+   - `search(file)` でターゲットに最も近い設定ファイルを検索
+   - `resolve(file, keys, cache)` で全設定レイヤーをマージ
+4. イベント発行（`this.emit('config', ...)`）を保持しつつ `resolveConfig()` を変更
+5. 新しい API オプションを追加する場合、`src/api/types.ts` の `APIOptions` を更新
+6. `src/api/ml-engine.spec.ts` にテストを追加
+7. ビルド: `yarn build --scope markuplint`
+8. テスト: `yarn test --scope markuplint`
+
+### 4. MLEngine イベントの追加
+
+1. `src/api/types.ts` を読み、`MLEngineEventMap` を確認
+2. 新しいイベント型定義を追加:
+   ```ts
+   'new-event': [filePath: string, data: SomeType, message?: string];
+   ```
+3. `src/api/ml-engine.ts` を読み、パイプラインの適切な箇所に `this.emit('new-event', ...)` を追加
+4. `src/api/ml-engine.spec.ts` に `engine.on('new-event', ...)` を使ったテストを追加
+5. ビルド: `yarn build --scope markuplint`
+6. テスト: `yarn test --scope markuplint`
+
+## 上流パッケージ影響チェックリスト
+
+上流パッケージの変更がこのパッケージに影響する可能性があります:
+
+| パッケージ                  | markuplint への影響                                                            |
+| --------------------------- | ------------------------------------------------------------------------------ |
+| `@markuplint/file-resolver` | ConfigProvider API の変更、ファイル解決の変更、パーサー/スキーマリゾルバの変更 |
+| `@markuplint/ml-config`     | Config 型の変更、mergeConfig の動作変更                                        |
+| `@markuplint/ml-core`       | MLCore API の変更、MLRule インターフェースの変更、ViolationCollector の変更    |
+| `@markuplint/rules`         | ルールの追加/削除がビルトインルールセットに影響                                |
+| `@markuplint/cli-utils`     | CLI 出力ユーティリティの変更、インストーラ API の変更                          |
+| `@markuplint/i18n`          | LocaleSet 型の変更、ロケールファイル形式の変更                                 |
+
+上流パッケージが更新された場合:
+
+```shell
+yarn test --scope markuplint
+```
+
+## トラブルシューティング
+
+### ファイルが linting されない
+
+**症状:** 対象ファイルが存在するが lint 結果が返らない。
+
+**原因:** 拡張子の不一致、または `excludeFiles` でファイルが除外されている。
+
+**解決策:**
+
+1. `--ignore-ext` で拡張子チェックを無効化
+2. 設定の `excludeFiles` を確認
+3. `--verbose` でどのファイルがスキップされているか、その理由を確認
+
+### 設定が適用されない
+
+**症状:** ルールが有効にならない、設定ファイルが認識されない。
+
+**原因:** `--no-search-config` が設定されている、または設定ファイルが探索パスにない。
+
+**解決策:**
+
+1. `--config` で設定ファイルパスを明示的に指定
+2. `--show-config` で計算済み設定を確認
+3. 設定ファイルが対象ファイルの親ディレクトリにあることを確認
+
+### Watch モードで設定変更後に再 lint されない
+
+**症状:** 設定ファイルを変更しても再 linting が行われない。
+
+**原因:** 設定ファイルが `configSet.files`（ウォッチャーが追跡するファイルセット）に含まれていない。
+
+**解決策:**
+
+1. `--verbose` でウォッチャーが追跡しているファイルを確認
+2. `ConfigProvider.search()` の結果に設定ファイルが含まれていることを確認
+3. chokidar がファイルを正しく監視しているか確認（プラットフォーム固有の問題）
+
+### mlTest() で違反が検出されない
+
+**症状:** `mlTest()` が空の violations 配列を返す。
+
+**原因:** 第3引数にカスタム `rules` を渡すと、`importPresetRules` がデフォルトで `false` になる。
+
+**解決策:**
+
+1. `rules` パラメータを省略してすべてのビルトインルールを使用
+2. または必要なルールを明示的に渡し、ルール設定でそれらが有効になっていることを確認

package/docs/maintenance.md

@@ -0,0 +1,207 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                         | Description            |
+| ------------------------------- | ---------------------- |
+| `yarn build --scope markuplint` | Build this package     |
+| `yarn dev --scope markuplint`   | Watch mode build       |
+| `yarn clean --scope markuplint` | Remove build artifacts |
+| `yarn test --scope markuplint`  | Run tests              |
+
+## Testing
+
+Test files follow the `*.spec.ts` naming convention and are located in the `src/` directory:
+
+| Test File                          | Coverage                                                             |
+| ---------------------------------- | -------------------------------------------------------------------- |
+| `api/ml-engine.spec.ts`            | MLEngine lifecycle (events, watch mode, config resolution, fromCode) |
+| `cli/index.spec.ts`                | CLI integration (stdout output, fix mode, JSON format, flags)        |
+| `index.spec.ts`                    | Package integration (HTML file linting end-to-end)                   |
+| `reporter/github-reporter.spec.ts` | GitHub Actions annotation output format                              |
+| `cli/init/*.spec.ts`               | Initialization wizard (config generation, module selection)          |
+| `i18n.spec.ts`                     | Locale loading and fallback behavior                                 |
+
+The primary testing pattern for MLEngine tests:
+
+```ts
+import { MLEngine } from './api/index.js';
+
+const engine = await MLEngine.fromCode(sourceCode, {
+  config: { rules: { 'rule-name': true } },
+  locale: 'en',
+});
+const result = await engine.exec();
+expect(result?.violations).toStrictEqual([
+  // expected violations
+]);
+```
+
+For testing with the testing utilities:
+
+```ts
+import { mlRuleTest } from './testing-tool/index.js';
+
+const { violations } = await mlRuleTest(ruleSeed, '<div></div>', { rule: true });
+expect(violations).toStrictEqual([
+  // expected violations without ruleId
+]);
+```
+
+## Recipes
+
+### 1. Adding a New CLI Flag
+
+1. Read `src/cli/bootstrap.ts` and locate the `flags` object inside `meow()`
+2. Add the new flag definition:
+   ```ts
+   newFlag: {
+     type: 'boolean', // or 'string', 'number'
+     default: false,
+     shortFlag: 'n', // optional
+   },
+   ```
+3. Update the `help` string at the top of the file to document the new flag
+4. Note: `CLIOptions` type updates automatically (it is `typeof cli.flags`)
+5. Read `src/cli/command.ts` and extract the flag value from `options`:
+   ```ts
+   const newFlag = options.newFlag;
+   ```
+6. Implement the flag's behavior in `command()` or pass it to `MLEngine` options
+7. If the flag affects the API layer, add a corresponding property to `APIOptions` in `src/api/types.ts`
+8. Add tests in `src/cli/index.spec.ts`
+9. Build: `yarn build --scope markuplint`
+10. Test: `yarn test --scope markuplint`
+
+### 2. Adding a New Reporter
+
+1. Read existing reporters in `src/reporter/` to understand the pattern:
+   - Function takes `MLResultInfo` (and optionally `CLIOptions`)
+   - Returns `string[]` (one element per output line)
+2. Create `src/reporter/<name>-reporter.ts`:
+
+   ```ts
+   import type { MLResultInfo } from '../types.js';
+
+   export function <name>Reporter(results: MLResultInfo) {
+     const out: string[] = [];
+     for (const violation of results.violations) {
+       out.push(/* format violation */);
+     }
+     return out;
+   }
+   ```
+
+3. Export from `src/reporter/index.ts`:
+   ```ts
+   export * from './<name>-reporter.js';
+   ```
+4. Read `src/cli/output.ts` and add a case to the `switch` statement:
+   ```ts
+   case '<name>': {
+     out = <name>Reporter(results);
+     break;
+   }
+   ```
+5. Add tests in `src/reporter/<name>-reporter.spec.ts`
+6. Build: `yarn build --scope markuplint`
+7. Test: `yarn test --scope markuplint`
+
+### 3. Modifying Configuration Resolution Logic
+
+1. Read `src/api/ml-engine.ts` and locate `resolveConfig()`
+2. Understand the current priority:
+   - `options.config` (inline config object)
+   - `options.configFile` (explicit file path)
+   - `ConfigProvider.search()` (auto-discovery, unless `--no-search-config`)
+   - `options.defaultConfig` (fallback)
+   - `markuplint:recommended` (default when nothing else is configured)
+3. Understand `ConfigProvider` from `@markuplint/file-resolver`:
+   - `set(config)` registers a config and returns a key
+   - `search(file)` finds the nearest config file for a target
+   - `resolve(file, keys, cache)` merges all config layers
+4. Make changes to `resolveConfig()`, preserving the event emissions (`this.emit('config', ...)`)
+5. If adding new API options, update `APIOptions` in `src/api/types.ts`
+6. Add tests in `src/api/ml-engine.spec.ts`
+7. Build: `yarn build --scope markuplint`
+8. Test: `yarn test --scope markuplint`
+
+### 4. Adding an MLEngine Event
+
+1. Read `src/api/types.ts` and locate `MLEngineEventMap`
+2. Add the new event type definition:
+   ```ts
+   'new-event': [filePath: string, data: SomeType, message?: string];
+   ```
+3. Read `src/api/ml-engine.ts` and add `this.emit('new-event', ...)` at the appropriate point in the pipeline
+4. Add tests in `src/api/ml-engine.spec.ts` using `engine.on('new-event', ...)`
+5. Build: `yarn build --scope markuplint`
+6. Test: `yarn test --scope markuplint`
+
+## Upstream Impact Checklist
+
+Changes to upstream packages can affect this package:
+
+| Package                     | Impact on markuplint                                                                |
+| --------------------------- | ----------------------------------------------------------------------------------- |
+| `@markuplint/file-resolver` | ConfigProvider API changes, file resolution changes, parser/schema resolver changes |
+| `@markuplint/ml-config`     | Config type changes, mergeConfig behavior changes                                   |
+| `@markuplint/ml-core`       | MLCore API changes, MLRule interface changes, ViolationCollector changes            |
+| `@markuplint/rules`         | Rule additions/removals affect the built-in rule set                                |
+| `@markuplint/cli-utils`     | CLI output utility changes, installer API changes                                   |
+| `@markuplint/i18n`          | LocaleSet type changes, locale file format changes                                  |
+
+When upstream packages are updated, run:
+
+```shell
+yarn test --scope markuplint
+```
+
+## Troubleshooting
+
+### Files are not being linted
+
+**Symptom:** A target file exists but no lint results are returned.
+
+**Cause:** Extension mismatch or the file is excluded by `excludeFiles`.
+
+**Solution:**
+
+1. Use `--ignore-ext` to disable extension checking
+2. Check the `excludeFiles` setting in the configuration
+3. Use `--verbose` to see which files are being skipped and why
+
+### Configuration is not applied
+
+**Symptom:** Rules are not active, the config file is not recognized.
+
+**Cause:** `--no-search-config` is set, or the config file is not in the search path.
+
+**Solution:**
+
+1. Use `--config` to explicitly specify the config file path
+2. Use `--show-config` to inspect the computed configuration
+3. Check that the config file is in a parent directory of the target file
+
+### Watch mode does not re-lint on config changes
+
+**Symptom:** Config file is modified but re-linting does not happen.
+
+**Cause:** The config file is not in `configSet.files` (the set of files tracked by the watcher).
+
+**Solution:**
+
+1. Use `--verbose` to see which files the watcher is tracking
+2. Verify that `ConfigProvider.search()` includes the config file in its result
+3. Check that chokidar is correctly watching the file (platform-specific issues)
+
+### mlTest() does not detect violations
+
+**Symptom:** `mlTest()` returns an empty violations array.
+
+**Cause:** When custom `rules` are passed as the third argument, `importPresetRules` defaults to `false`.
+
+**Solution:**
+
+1. Omit the `rules` parameter to use all built-in rules
+2. Or explicitly pass the rules you need and ensure the rule configuration enables them

package/lib/api/index.d.ts

@@ -1,2 +1,10 @@
+/**
+ * @module api
+ *
+ * Public API entry point for markuplint.
+ * Re-exports the lint engine and the standalone lint function used for programmatic access.
+ */
+/** The primary linting engine that manages file resolution, configuration, and rule execution. */
 export { MLEngine, FromCodeOptions } from './ml-engine.js';
+/** Standalone function to lint one or more files or source code strings. */
 export { lint } from './lint.js';

package/lib/api/index.js

@@ -1,2 +1,10 @@
+/**
+ * @module api
+ *
+ * Public API entry point for markuplint.
+ * Re-exports the lint engine and the standalone lint function used for programmatic access.
+ */
+/** The primary linting engine that manages file resolution, configuration, and rule execution. */
 export { MLEngine } from './ml-engine.js';
+/** Standalone function to lint one or more files or source code strings. */
 export { lint } from './lint.js';

package/lib/api/lint.d.ts

@@ -1,4 +1,11 @@
 import type { APIOptions } from './types.js';
 import type { MLResultInfo } from '../types.js';
 import type { Target } from '@markuplint/file-resolver';
+/**
+ * Lints multiple targets (files or inline sources) and returns results for each.
+ *
+ * @param targetList - An array of file paths/globs or inline source code targets
+ * @param options - API options for configuration, locale, rules, and behavior
+ * @returns An array of lint results, one per processed file
+ */
 export declare function lint(targetList: readonly Readonly<Target>[], options?: APIOptions): Promise<MLResultInfo[]>;

package/lib/api/lint.js

@@ -1,5 +1,12 @@
 import { resolveFiles } from '@markuplint/file-resolver';
 import { MLEngine } from './ml-engine.js';
+/**
+ * Lints multiple targets (files or inline sources) and returns results for each.
+ *
+ * @param targetList - An array of file paths/globs or inline source code targets
+ * @param options - API options for configuration, locale, rules, and behavior
+ * @returns An array of lint results, one per processed file
+ */
 export async function lint(targetList, options) {
     const res = [];
     const files = await resolveFiles(targetList);

package/lib/api/ml-engine.d.ts

@@ -8,19 +8,67 @@ type MLEngineOptions = {
     readonly debug?: boolean;
     readonly watch?: boolean;
 };
+/**
+ * Options for creating an {@link MLEngine} from inline source code.
+ */
 export type FromCodeOptions = APIOptions & MLEngineOptions & {
+    /** Optional filename for the inline source code */
     readonly name?: string;
+    /** Optional working directory for config resolution */
     readonly dirname?: string;
 };
+/**
+ * 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 declare class MLEngine extends Emitter<MLEngineEventMap> {
     #private;
+    /**
+     * 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 fromCode(sourceCode: string, options?: FromCodeOptions): Promise<MLEngine>;
+    /**
+     * 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 toMLFile(target: Target): Promise<MLFile | undefined>;
     constructor(file: Readonly<MLFile>, options?: APIOptions & MLEngineOptions);
+    /**
+     * The parsed document, or `null` if not yet set up or if parsing failed.
+     */
     get document(): Document<RuleConfigValue, PlainData> | null;
+    /**
+     * Closes the engine, removing all event listeners and stopping the file watcher.
+     */
     close(): Promise<void>;
+    /**
+     * 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
+     */
     exec(): Promise<MLResultInfo | null>;
+    /**
+     * Updates the source code and re-parses the document without re-resolving configuration.
+     *
+     * @param code - The new markup source code
+     */
     setCode(code: string): Promise<void>;
+    /**
+     * 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: boolean): void;
     private createCore;
     private i18n;

package/lib/api/ml-engine.js

@@ -20,7 +20,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,6 +51,12 @@ 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];
@@ -58,16 +77,29 @@ export class MLEngine extends Emitter {
         this.watchMode(!!__classPrivateFieldGet(this, _MLEngine_options, "f")?.watch);
         log('[MLEngine] Initialized: %s', __classPrivateFieldGet(this, _MLEngine_file, "f").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) {
             return null;
         }
         return __classPrivateFieldGet(this, _MLEngine_core, "f")?.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();
     }
+    /**
+     * 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();
@@ -115,6 +147,11 @@ export class MLEngine extends Emitter {
             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) {
@@ -123,6 +160,12 @@ export class MLEngine extends Emitter {
         __classPrivateFieldGet(this, _MLEngine_file, "f").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"),

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