@markuplint/ml-config 4.8.14 → 5.0.0-alpha.0

package/CHANGELOG.md

@@ -3,13 +3,52 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.8.14](https://github.com/markuplint/markuplint/compare/@markuplint/ml-config@4.8.13...@markuplint/ml-config@4.8.14) (2025-11-05)
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
 
-**Note:** Version bump only for package @markuplint/ml-config
+### Bug Fixes
+
+- use explicit `export type` for type-only re-exports ([7c77c05](https://github.com/markuplint/markuplint/commit/7c77c05619518c8d18a183132040f5b2cd0ab6ec))
+
+### Code Refactoring
+
+- **ml-config:** remove deprecated rule types ([e5d2b2d](https://github.com/markuplint/markuplint/commit/e5d2b2d6b5d7f6a060e1ea2160be97ad3ca02084))
+
+- refactor(ml-config)!: change pretenders merge behavior ([e7b00ab](https://github.com/markuplint/markuplint/commit/e7b00abd80dd75a6060697b30d59d0371ae3694b))
+- refactor(ml-config)!: change rule value array merge to override ([05c23ac](https://github.com/markuplint/markuplint/commit/05c23ace31a3429233b3411c8b95ae62438be6e5)), closes [#1104](https://github.com/markuplint/markuplint/issues/1104)
+- refactor(ml-config)!: replace deepmerge with shallow merge ([15b4945](https://github.com/markuplint/markuplint/commit/15b494546b9016189a790b2ea49fcc2bb38c85c4))
+
+### Features
+
+- **ml-config:** add name and specConformance properties to nodeRule types ([af53042](https://github.com/markuplint/markuplint/commit/af5304218f7a207a1d8e61464c81c42d5ee1bf01))
+- **ml-config:** add named rule group types, merge logic, and type guards ([9f625fd](https://github.com/markuplint/markuplint/commit/9f625fdcd9bc821d2be53668ac0eb676597aa935))
+- **ml-config:** add ruleCommonSettings.ariaVersion option ([f2cd713](https://github.com/markuplint/markuplint/commit/f2cd7132311c00c22d68c4685b4a280b77ee6463))
 
+### BREAKING CHANGES
 
+- Pretender files/imports are now overridden instead
+  of deep-merged. Pretender data continues to be appended.
 
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 
+- Rule value arrays are now overridden instead of
+- Object properties in config are now shallow-merged
+  instead of deep-merged. Nested objects within parser, specs, etc.
+  will be replaced entirely by the overriding config.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+- **ml-config:** RuleV2, RuleConfigV2, AnyRuleV2 types are removed.
+  The deprecated `option` field is no longer supported; use `options`.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+## [4.8.15](https://github.com/markuplint/markuplint/compare/@markuplint/ml-config@4.8.14...@markuplint/ml-config@4.8.15) (2026-02-10)
+
+**Note:** Version bump only for package @markuplint/ml-config
+
+## [4.8.14](https://github.com/markuplint/markuplint/compare/@markuplint/ml-config@4.8.13...@markuplint/ml-config@4.8.14) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/ml-config
 
 ## [4.8.13](https://github.com/markuplint/markuplint/compare/@markuplint/ml-config@4.8.12...@markuplint/ml-config@4.8.13) (2025-08-24)
 

package/SKILL.md

@@ -0,0 +1,114 @@
+---
+description: Maintenance tasks for @markuplint/ml-config
+globs:
+  - packages/@markuplint/ml-config/src/**/*.ts
+alwaysApply: false
+---
+
+# ml-config-maintenance
+
+Perform maintenance tasks for `@markuplint/ml-config`: add config properties,
+modify merge strategies, and update rule merge logic.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                  | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| `add-config-property` | Add a new property to the Config type and implement its merge strategy |
+| `add-merge-strategy`  | Change an existing property's merge strategy                           |
+| `modify-rule-merge`   | Modify the rule merge logic in mergeRule()                             |
+
+If omitted, defaults to `add-config-property`.
+
+## Reference
+
+Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
+for the full guide. The recipes there are the source of truth for procedures.
+
+Also read:
+
+- `ARCHITECTURE.md` -- Package overview, type system, merge algorithm details, and template rendering
+- `src/types.ts` -- All type definitions (source of truth for Config, Rule, Pretender types)
+- `src/merge-config.ts` -- Merge algorithm (source of truth for mergeConfig, mergeRule, helpers)
+- `src/utils.ts` -- Template rendering and utility functions
+
+## Task: add-config-property
+
+Add a new property to the Config type and implement its merge strategy. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Define the type
+
+1. Read `src/types.ts`
+2. Add the readonly property to the `Config` type
+3. If the property needs a different type in the optimized form, update `OptimizedConfig` (use `Omit` + re-define)
+4. Decide whether to include it in `OverrideConfig` (add to `NoInherit` if it should be top-level only)
+
+### Step 2: Implement the merge strategy
+
+1. Read `src/merge-config.ts`
+2. Add the merge logic inside `mergeConfig()`, choosing the appropriate strategy:
+   - `mergeObject()` for object shallow merge
+   - `concatArray()` for array concatenation
+   - `b.prop ?? a.prop` for simple right-side precedence
+3. If the property needs format conversion (like plugins or pretenders), implement a conversion helper
+
+### Step 3: Verify
+
+1. Add test cases in `src/merge-config.spec.ts`
+2. Build: `yarn build --scope @markuplint/ml-config`
+3. Test: `yarn test --scope @markuplint/ml-config`
+
+## Task: add-merge-strategy
+
+Change an existing property's merge strategy. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Understand the current strategy
+
+1. Read `src/merge-config.ts` and locate the property in `mergeConfig()`
+2. Read `ARCHITECTURE.md` section "Per-Property Merge Strategy Table" for context
+
+### Step 2: Modify the strategy
+
+1. Replace the current merge call with the new strategy
+2. Available strategies: `mergeObject()`, `concatArray()`, `b.prop ?? a.prop`, or a custom helper
+
+### Step 3: Verify
+
+1. Update existing tests or add new ones in `src/merge-config.spec.ts`
+2. Build: `yarn build --scope @markuplint/ml-config`
+3. Test: `yarn test --scope @markuplint/ml-config`
+
+## Task: modify-rule-merge
+
+Modify the rule merge logic in `mergeRule()`. Follow recipe #3 in `docs/maintenance.md`.
+
+### Step 1: Understand the current flow
+
+1. Read `src/merge-config.ts` and locate the `mergeRule()` function
+2. Current flow: `false` check -> `undefined` checks -> value type check -> object type merge
+3. Read `ARCHITECTURE.md` section "mergeRule()" for the detailed flowchart
+
+### Step 2: Modify the logic
+
+1. Make changes to `mergeRule()`, paying attention to:
+   - The `false` absolute disable behavior
+   - Array values override (right-side wins)
+   - Shallow merge for options via `mergeObject()`
+   - Right-side precedence for severity, value, reason
+
+### Step 3: Verify
+
+1. Verify existing tests still pass (especially the edge cases in `src/merge-config.spec.ts`)
+2. Add new test cases for the modified behavior
+3. Build: `yarn build --scope @markuplint/ml-config`
+4. Test: `yarn test --scope @markuplint/ml-config`
+
+## Rules
+
+1. **All Config properties are `readonly`** -- use `readonly` for all fields in type definitions.
+2. **Choose merge strategies carefully** -- refer to the strategy table in `ARCHITECTURE.md` when deciding how to merge a new property.
+3. **Test merge edge cases** -- always test with `undefined`, empty objects, and conflicting values.
+4. **Run `deleteUndefProp()` after merge** -- ensure no `undefined` properties leak into the result.
+5. **Add JSDoc comments** to all new public types and functions.

package/docs/maintenance.ja.md

@@ -0,0 +1,178 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                   | 説明                   |
+| ------------------------------------------ | ---------------------- |
+| `yarn build --scope @markuplint/ml-config` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/ml-config`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/ml-config` | ビルド成果物を削除     |
+| `yarn test --scope @markuplint/ml-config`  | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従い、`src/` ディレクトリに配置されています:
+
+| テストファイル         | カバレッジ                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `merge-config.spec.ts` | `mergeConfig()` 統合テスト（plugins, parser, overrides, rules）、`mergeRule()` エッジケース、pretender マージ |
+| `utils.spec.ts`        | `provideValue()` テンプレートレンダリング、`exchangeValueOnRule()` の value/options/reason 処理               |
+
+マージテストの主なパターン:
+
+```ts
+import { mergeConfig, mergeRule } from './merge-config.js';
+
+expect(mergeConfig(baseConfig, overrideConfig)).toStrictEqual({
+  // 期待されるマージ結果
+});
+```
+
+ルールマージのテスト:
+
+```ts
+expect(mergeRule(baseRule, overrideRule)).toStrictEqual({
+  // 期待されるマージ済みルール
+});
+```
+
+テンプレートレンダリングのテスト:
+
+```ts
+import { provideValue, exchangeValueOnRule } from './utils.js';
+
+expect(provideValue('{{ dataName }}', { dataName: 'value' })).toBe('value');
+expect(exchangeValueOnRule({ value: '{{ var }}' }, { var: 'x' })).toStrictEqual({ value: 'x' });
+```
+
+## レシピ
+
+### 1. Config 型への新しいプロパティ追加
+
+1. `src/types.ts` を読み、`Config` 型を確認
+2. `Config` に新しい readonly プロパティを追加:
+   ```ts
+   readonly newProp?: NewPropType;
+   ```
+3. `OptimizedConfig` に含めるかどうかを判断:
+   - マージ後に型が変わる場合（plugins の string -> object のように）、`Omit` + 再定義を使用
+   - 型が同じなら `OptimizedConfig` のスプレッドで自動的に継承される
+4. `OverrideConfig` に含めるかどうかを判断:
+   - トップレベル専用（`$schema`、`extends` のように）なら、`NoInherit` ユニオン型にプロパティ名を追加
+   - ファイルパターンごとにオーバーライド可能にする場合はそのまま（`Omit<Config, NoInherit>` 経由で `Config` から継承）
+5. `src/merge-config.ts` を読み、`mergeConfig()` 関数の config オブジェクト内にマージロジックを追加:
+   - オブジェクト shallow merge: `newProp: mergeObject(a.newProp, b.newProp)`
+   - 配列結合: `newProp: concatArray(a.newProp, b.newProp)`
+   - 配列結合+重複排除: `newProp: concatArray(a.newProp, b.newProp, true)`
+   - 単純な右辺優先: `newProp: b.newProp ?? a.newProp`（スプレッドで処理されるが、明示的な方が分かりやすい）
+6. `src/merge-config.spec.ts` にテストケースを追加
+7. ビルド: `yarn build --scope @markuplint/ml-config`
+8. テスト: `yarn test --scope @markuplint/ml-config`
+
+### 2. マージ戦略の変更
+
+1. `src/merge-config.ts` を読み、`mergeConfig()` 関数内のプロパティを確認
+2. 現在の戦略を特定（`ARCHITECTURE.md` の戦略テーブルを参照）
+3. マージ呼び出しを置換。利用可能な戦略:
+   - `mergeObject(a.prop, b.prop)` -- 右辺優先の shallow merge
+   - `concatArray(a.prop, b.prop)` -- 単純な配列結合
+   - `concatArray(a.prop, b.prop, true)` -- 重複排除付き結合
+   - `concatArray(a.prop, b.prop, true, 'name')` -- 名前付きプロパティで重複排除、同名オブジェクトをマージ
+   - `b.prop ?? a.prop` -- 単純な右辺優先（マージなし）
+   - カスタムヘルパー関数（複雑な変換用）
+4. `src/merge-config.spec.ts` のテストを更新または追加
+5. ビルド: `yarn build --scope @markuplint/ml-config`
+6. テスト: `yarn test --scope @markuplint/ml-config`
+
+### 3. ルールマージロジックの変更
+
+1. `src/merge-config.ts` を読み、`mergeRule()` 関数を確認
+2. 現在のフローを理解:
+   - `optimizeRule()` が両方の入力を正規化
+   - `false` チェック: override が `false` または `{value: false}` なら常に `false` を返す
+   - `undefined` チェック: 片方がない場合はもう片方を返す
+   - 値型チェック: override が直接値（primitive/null/array）ならベース値を上書き
+   - オブジェクト型マージ: severity/value/reason は右辺優先、options は shallow merge
+3. 変更を加える際、主要な不変条件を保持:
+   - `false` は常に絶対無効化になる必要がある
+   - 配列値は上書き（右辺優先）であり、連結ではない
+   - `options` は `mergeObject()` による shallow merge が必要
+4. `src/merge-config.spec.ts` の既存テストが通ることを確認
+5. 変更後の動作に対する新しいテストケースを追加
+6. ビルド: `yarn build --scope @markuplint/ml-config`
+7. テスト: `yarn test --scope @markuplint/ml-config`
+
+### 4. Pretender 型の拡張
+
+1. `src/types.ts` を読み、`Pretender`、`PretenderDetails`、`OriginalNode` を確認
+2. 適切な型に新しいフィールドを追加
+3. `src/merge-config.ts` を読み、`mergePretenders()` を確認:
+   - 配列形式を `{data: [...]}` に変換（`toPretenderDetails()`）
+   - `files`/`imports` は上書き（右辺優先）
+   - `data` 配列は連結（追加）
+   - `PretenderDetails` の新しいフィールドは `mergePretenders()` 内で明示的に処理が必要
+4. `src/merge-config.spec.ts` にテストケースを追加
+5. ビルド: `yarn build --scope @markuplint/ml-config`
+6. テスト: `yarn test --scope @markuplint/ml-config`
+
+## 上流パッケージ影響チェックリスト
+
+上流パッケージの変更がこのパッケージに影響する可能性があります:
+
+| パッケージ             | ml-config への影響                                   |
+| ---------------------- | ---------------------------------------------------- |
+| `@markuplint/ml-ast`   | `ParserOptions` 型の変更                             |
+| `@markuplint/selector` | `RegexSelector` 型の変更（再エクスポートされている） |
+| `@markuplint/shared`   | `Nullable` ユーティリティ型の変更                    |
+
+上流パッケージが更新された場合:
+
+```shell
+yarn test --scope @markuplint/ml-config
+```
+
+## トラブルシューティング
+
+### マージ後にプロパティが消える
+
+**症状:** 入力設定にプロパティが存在するが、`mergeConfig()` の結果に含まれない。
+
+**原因:** `deleteUndefProp()` が `undefined` 値のプロパティをすべて除去している。マージロジックがそのプロパティに対して `undefined` を生成している可能性がある。
+
+**解決策:**
+
+1. `mergeConfig()` 内のそのプロパティのマージ戦略を確認
+2. 両方の入力に値がある場合にヘルパー関数が `undefined` を返していないか検証
+3. `concatArray()` は空配列に対して `undefined` を返す -- 入力が空でないことを確認
+
+### ルール値が予期しない上書きになる
+
+**症状:** ルールの配列値がベースの値を保持せず、完全に置き換えられる。
+
+**原因:** `mergeRule()` は設計上、配列値を上書きする（右辺優先）。これは ESLint や Biome と一貫した動作。
+
+**解決策:** これは期待される動作です。両方の値が必要な場合は、単一の設定で手動で配列を統合:
+
+```json
+{ "value": ["base-tag-1", "base-tag-2", "new-tag-1"], "options": {} }
+```
+
+### プラグインの settings がマージされない
+
+**症状:** 同名プラグインの2つの設定で、片方の settings しか反映されない。
+
+**原因:** 片方が文字列形式（`"plugin-name"`）、もう片方がオブジェクト形式（`{name: "plugin-name", settings: {...}}`）の場合、文字列形式にはマージする settings がない。
+
+**解決策:** 両方でオブジェクト形式を使用:
+
+```json
+{ "name": "plugin-name", "settings": { "key": "value" } }
+```
+
+### false でルールを無効化できない
+
+**症状:** ローカル設定でルールを `false` に設定しても、extends を使用していると無効化されない。
+
+**原因:** `mergeConfig()` の呼び出し順序が逆になっている可能性がある。ローカル設定は第2引数（override）でなければならない。
+
+**解決策:** 呼び出し順序が `mergeConfig(extendedConfig, localConfig)` であることを確認。ローカル設定が右辺（override）引数になるようにする。

package/docs/maintenance.md

@@ -0,0 +1,178 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                    | Description            |
+| ------------------------------------------ | ---------------------- |
+| `yarn build --scope @markuplint/ml-config` | Build this package     |
+| `yarn dev --scope @markuplint/ml-config`   | Watch mode build       |
+| `yarn clean --scope @markuplint/ml-config` | Remove build artifacts |
+| `yarn test --scope @markuplint/ml-config`  | Run tests              |
+
+## Testing
+
+Test files follow the `*.spec.ts` naming convention and are located in the `src/` directory:
+
+| Test File              | Coverage                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `merge-config.spec.ts` | `mergeConfig()` integration (plugins, parser, overrides, rules), `mergeRule()` edge cases, pretender merging |
+| `utils.spec.ts`        | `provideValue()` template rendering, `exchangeValueOnRule()` with value/options/reason                       |
+
+The primary testing pattern for merge tests:
+
+```ts
+import { mergeConfig, mergeRule } from './merge-config.js';
+
+expect(mergeConfig(baseConfig, overrideConfig)).toStrictEqual({
+  // expected merged result
+});
+```
+
+For rule merge tests:
+
+```ts
+expect(mergeRule(baseRule, overrideRule)).toStrictEqual({
+  // expected merged rule
+});
+```
+
+For template rendering tests:
+
+```ts
+import { provideValue, exchangeValueOnRule } from './utils.js';
+
+expect(provideValue('{{ dataName }}', { dataName: 'value' })).toBe('value');
+expect(exchangeValueOnRule({ value: '{{ var }}' }, { var: 'x' })).toStrictEqual({ value: 'x' });
+```
+
+## Recipes
+
+### 1. Adding a New Property to Config
+
+1. Read `src/types.ts` and locate the `Config` type
+2. Add the new readonly property to `Config`:
+   ```ts
+   readonly newProp?: NewPropType;
+   ```
+3. Decide whether it belongs in `OptimizedConfig`:
+   - If the type changes after merging (like plugins string -> object), use `Omit` + re-define in `OptimizedConfig`
+   - If it stays the same, it is inherited automatically via the spread in `OptimizedConfig`
+4. Decide whether it belongs in `OverrideConfig`:
+   - If it should be top-level only (like `$schema`, `extends`), add the property name to the `NoInherit` union type
+   - If it should be overridable per file pattern, leave it as-is (it inherits from `Config` via `Omit<Config, NoInherit>`)
+5. Read `src/merge-config.ts` and add the merge logic inside the `mergeConfig()` function's config object:
+   - For object shallow merge: `newProp: mergeObject(a.newProp, b.newProp)`
+   - For array concatenation: `newProp: concatArray(a.newProp, b.newProp)`
+   - For array with deduplication: `newProp: concatArray(a.newProp, b.newProp, true)`
+   - For simple right-side precedence: `newProp: b.newProp ?? a.newProp` (handled by the spread, but explicit is clearer)
+6. Add test cases in `src/merge-config.spec.ts`
+7. Build: `yarn build --scope @markuplint/ml-config`
+8. Test: `yarn test --scope @markuplint/ml-config`
+
+### 2. Changing a Merge Strategy
+
+1. Read `src/merge-config.ts` and locate the property in the `mergeConfig()` function
+2. Identify the current strategy (see the strategy table in `ARCHITECTURE.md`)
+3. Replace the merge call. Available strategies:
+   - `mergeObject(a.prop, b.prop)` -- Shallow merge with right-side precedence
+   - `concatArray(a.prop, b.prop)` -- Simple array concatenation
+   - `concatArray(a.prop, b.prop, true)` -- Concat with deduplication
+   - `concatArray(a.prop, b.prop, true, 'name')` -- Concat with deduplication by named property, merging same-name objects
+   - `b.prop ?? a.prop` -- Simple right-side precedence (no merge)
+   - Custom helper function for complex transformations
+4. Update or add tests in `src/merge-config.spec.ts`
+5. Build: `yarn build --scope @markuplint/ml-config`
+6. Test: `yarn test --scope @markuplint/ml-config`
+
+### 3. Modifying Rule Merge Logic
+
+1. Read `src/merge-config.ts` and locate the `mergeRule()` function
+2. Understand the current flow:
+   - `optimizeRule()` normalizes both inputs
+   - `false` check: override `false` or `{value: false}` always returns `false`
+   - `undefined` checks: missing side returns the other side
+   - Value type check: if override is a direct value (primitive/null/array), it replaces the base value
+   - Object type merge: severity/value/reason use right-side precedence, options use shallow merge
+3. Make changes, preserving the key invariants:
+   - `false` must always result in absolute disable
+   - Array values must override (right-side wins), not concatenate
+   - `options` must use shallow merge via `mergeObject()`
+4. Verify existing tests pass in `src/merge-config.spec.ts`
+5. Add new test cases for the modified behavior
+6. Build: `yarn build --scope @markuplint/ml-config`
+7. Test: `yarn test --scope @markuplint/ml-config`
+
+### 4. Extending Pretender Types
+
+1. Read `src/types.ts` and locate `Pretender`, `PretenderDetails`, and `OriginalNode`
+2. Add new fields to the appropriate type
+3. Read `src/merge-config.ts` and check `mergePretenders()`:
+   - It converts array form to `{data: [...]}` via `toPretenderDetails()`
+   - `files`/`imports` are overridden (right-side wins)
+   - `data` arrays are concatenated (appended)
+   - New fields on `PretenderDetails` need explicit handling in `mergePretenders()`
+4. Add test cases in `src/merge-config.spec.ts`
+5. Build: `yarn build --scope @markuplint/ml-config`
+6. Test: `yarn test --scope @markuplint/ml-config`
+
+## Upstream Impact Checklist
+
+Changes to upstream packages can affect this package:
+
+| Package                | Impact on ml-config                        |
+| ---------------------- | ------------------------------------------ |
+| `@markuplint/ml-ast`   | `ParserOptions` type changes               |
+| `@markuplint/selector` | `RegexSelector` type changes (re-exported) |
+| `@markuplint/shared`   | `Nullable` utility type changes            |
+
+When upstream packages are updated, run:
+
+```shell
+yarn test --scope @markuplint/ml-config
+```
+
+## Troubleshooting
+
+### Properties disappear after merge
+
+**Symptom:** A property exists in the input config but is missing from the `mergeConfig()` result.
+
+**Cause:** `deleteUndefProp()` removes all properties with `undefined` values. The merge logic may be producing `undefined` for the property.
+
+**Solution:**
+
+1. Check the merge strategy for the property in `mergeConfig()`
+2. Verify the helper function does not return `undefined` when both inputs have values
+3. `concatArray()` returns `undefined` for empty arrays -- ensure the inputs are not empty
+
+### Rule values unexpectedly replaced
+
+**Symptom:** A rule's array value is replaced entirely instead of keeping both base and override values.
+
+**Cause:** `mergeRule()` overrides array values by design (right-side wins). This is consistent with ESLint and Biome behavior.
+
+**Solution:** This is the expected behavior. If you need both sets of values, manually combine the arrays in a single config:
+
+```json
+{ "value": ["base-tag-1", "base-tag-2", "new-tag-1"], "options": {} }
+```
+
+### Plugin settings are not merged
+
+**Symptom:** Two configs with the same plugin name result in settings from only one side.
+
+**Cause:** If one side uses the string form (`"plugin-name"`) and the other uses the object form (`{name: "plugin-name", settings: {...}}`), the string form has no settings to merge.
+
+**Solution:** Use the object form on both sides:
+
+```json
+{ "name": "plugin-name", "settings": { "key": "value" } }
+```
+
+### Rule cannot be disabled with false
+
+**Symptom:** Setting a rule to `false` in a local config does not disable it when using extends.
+
+**Cause:** The `mergeConfig()` call order may be reversed. The local config must be the second argument (override).
+
+**Solution:** Ensure the call order is `mergeConfig(extendedConfig, localConfig)` where the local config is the right-side (override) argument.

package/lib/index.d.ts

@@ -1,3 +1,3 @@
 export * from './merge-config.js';
 export * from './utils.js';
-export * from './types.js';
+export type * from './types.js';

package/lib/index.js

@@ -1,3 +1,2 @@
 export * from './merge-config.js';
 export * from './utils.js';
-export * from './types.js';

package/lib/merge-config.d.ts

@@ -1,4 +1,30 @@
-import type { Config, AnyRule, AnyRuleV2, OptimizedConfig } from './types.js';
+import type { Config, AnyRule, OptimizedConfig } from './types.js';
 import type { Nullable } from '@markuplint/shared';
+/**
+ * Merges two markuplint configurations into an optimized result.
+ *
+ * Plugins, arrays, and rules are merged with specific strategies:
+ * - Plugins are concatenated and deduplicated by name (settings shallow-merged)
+ * - Arrays (excludeFiles, nodeRules, childNodeRules) are concatenated
+ * - Rules are merged per-key with right-side precedence
+ * - Objects (parser, specs, etc.) are shallow-merged
+ * - The `extends` property is removed from the result when `b` is provided
+ *
+ * @param a - The base configuration
+ * @param b - The configuration to merge on top of `a`
+ * @returns The merged and optimized configuration
+ */
 export declare function mergeConfig(a: Config, b?: Config): OptimizedConfig;
-export declare function mergeRule(a: Nullable<AnyRule | AnyRuleV2>, b: AnyRule | AnyRuleV2): AnyRule;
+/**
+ * Merges two rule configurations with right-side precedence.
+ *
+ * If `b` is `false`, the rule is unconditionally disabled.
+ * If `b` is a direct value (including arrays), it overrides `a`.
+ * If both are full config objects, their properties are merged
+ * (severity/value/reason: right-side wins, options: shallow-merged).
+ *
+ * @param a - The base rule configuration (may be `null` or `undefined`)
+ * @param b - The rule configuration to merge on top
+ * @returns The merged rule configuration
+ */
+export declare function mergeRule(a: Nullable<AnyRule>, b: AnyRule): AnyRule;