@markuplint/ml-config 4.8.13 → 4.8.15

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 deep 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 concatenation for value arrays
+   - Deep 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,180 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                   | 説明                   |
+| ------------------------------------------ | ---------------------- |
+| `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 オブジェクト内にマージロジックを追加:
+   - オブジェクト deep 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)` -- 右辺優先の deep 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()` が両方の入力を正規化（非推奨の `option` -> `options` を処理）
+   - `false` チェック: override が `false` または `{value: false}` なら常に `false` を返す
+   - `undefined` チェック: 片方がない場合はもう片方を返す
+   - 値型チェック: override が直接値（primitive/null/array）なら置換または連結
+   - オブジェクト型マージ: severity/value/reason は右辺優先、options は deep merge
+3. 変更を加える際、主要な不変条件を保持:
+   - `false` は常に絶対無効化になる必要がある
+   - 配列値は連結される（置換ではない）
+   - `options` は `mergeObject()` による deep 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: [...]}` に変換（`convertPretenersToDetails()`）
+   - `mergeObject()` で deep merge
+   - `PretenderDetails` の新しいフィールドは自動的に deep merge される
+   - `Pretender`（`data` 配列内）の新しいフィールドは deepmerge の配列マージで処理
+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()` はベースとオーバーライドの両方が配列の場合、設計上連結する。
+
+**解決策:** 配列値を完全に上書きするには、override 側でオブジェクト形式を使用:
+
+```json
+{ "value": ["new", "values"], "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,180 @@
+# 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 deep 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)` -- Deep 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 (handles deprecated `option` -> `options`)
+   - `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 or concatenates
+   - Object type merge: severity/value/reason use right-side precedence, options use deep merge
+3. Make changes, preserving the key invariants:
+   - `false` must always result in absolute disable
+   - Array values must be concatenated (not replaced)
+   - `options` must use deep 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 `convertPretenersToDetails()`
+   - Then deep merges with `mergeObject()`
+   - New fields on `PretenderDetails` are automatically deep merged
+   - New fields on `Pretender` (inside `data` array) are handled by deepmerge's array merge
+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 are concatenated instead of replaced
+
+**Symptom:** A rule's array value keeps growing instead of being overwritten.
+
+**Cause:** `mergeRule()` concatenates array values by design when both base and override are arrays.
+
+**Solution:** To completely replace an array value, use the object form in the override:
+
+```json
+{ "value": ["new", "values"], "options": {} }
+```
+
+This replaces the value entirely instead of concatenating.
+
+### 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/merge-config.d.ts

@@ -1,4 +1,28 @@
 import type { Config, AnyRule, AnyRuleV2, OptimizedConfig } from './types.js';
 import type { Nullable } from '@markuplint/shared';
+/**
+ * Deep-merges two markuplint configurations into an optimized result.
+ *
+ * Plugins, arrays, and rules are merged with specific strategies:
+ * - Plugins are concatenated and deduplicated by name
+ * - Arrays (excludeFiles, nodeRules, childNodeRules) are concatenated
+ * - Rules are merged per-key with right-side precedence
+ * - 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;
+/**
+ * Merges two rule configurations with right-side precedence.
+ *
+ * If `b` is `false`, the rule is unconditionally disabled.
+ * If `b` is a direct value, it replaces or extends `a`.
+ * If both are full config objects, their properties are 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 | AnyRuleV2>, b: AnyRule | AnyRuleV2): AnyRule;

package/lib/merge-config.js

@@ -1,5 +1,18 @@
 import deepmerge from 'deepmerge';
 import { deleteUndefProp, cleanOptions, isRuleConfigValue } from './utils.js';
+/**
+ * Deep-merges two markuplint configurations into an optimized result.
+ *
+ * Plugins, arrays, and rules are merged with specific strategies:
+ * - Plugins are concatenated and deduplicated by name
+ * - Arrays (excludeFiles, nodeRules, childNodeRules) are concatenated
+ * - Rules are merged per-key with right-side precedence
+ * - 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 function mergeConfig(a, b) {
     const deleteExtendsProp = !!b;
     b = b ?? {};
@@ -36,6 +49,17 @@ export function mergeConfig(a, b) {
     deleteUndefProp(config);
     return config;
 }
+/**
+ * Merges two rule configurations with right-side precedence.
+ *
+ * If `b` is `false`, the rule is unconditionally disabled.
+ * If `b` is a direct value, it replaces or extends `a`.
+ * If both are full config objects, their properties are 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 function mergeRule(a, b) {
     const oA = optimizeRule(a);
     const oB = optimizeRule(b);