@markuplint/ml-core 5.0.0-alpha.1 → 5.0.0-alpha.3

package/ARCHITECTURE.ja.md

@@ -49,9 +49,11 @@ src/
 ├── ml-rule/
 │   ├── ml-rule.ts                    — MLRule クラス（ルール実行）
 │   ├── ml-rule-context.ts            — MLRuleContext（レポート収集）
+│   ├── rule-fixer.ts                 — RuleFixer（fix コールバック用の TextEdit ビルダー）
 │   ├── create-rule.ts                — createRule ファクトリ
 │   ├── create-test-rule.ts           — テスト用ルールファクトリ
 │   └── types.ts                      — RuleSeed, Checker 型
+├── fix-applier.ts                    — applyFixes（重複検出付き TextEdit 適用エンジン）
 ├── ruleset/
 │   └── index.ts                      — Ruleset クラス（rules + nodeRules + childNodeRules）
 ├── plugin/
@@ -143,8 +145,8 @@ flowchart LR
 
 1. **パース**: `MLCore` は設定されたパーサー（`MLParser`）を呼び出し、`MLASTDocument` を生成
 2. **ドキュメント作成**: AST を `MLDocument` でラップし、`createNode()` ファクトリで MLDOM ツリー全体を構築。`RuleMapper` が各ノードのルール設定を解決
-3. **検証**: 各 `MLRule` に対して、`document.setRule(rule)` を呼び出した後 `rule.verify(document)` を実行。ルールは `document.walkOn()` で対象ノードを走査し、`MLRuleContext` を通じて違反を報告
-4. **修正**（オプション）: `fix=true` の場合、ルールが `node.fix()` でトークン内容を変更。`document.toString(true)` で修正後のソースを生成
+3. **検証**: 各 `MLRule` に対して、`document.setRule(rule)` を呼び出した後 `rule.verify(document)` を実行。ルールは `document.walkOn()` で対象ノードを走査し、`MLRuleContext` を通じて違反を報告。ルールは report にインライン `fix` コールバックを付与して `TextEdit` オブジェクトを返す
+4. **修正**（オプション）: `fix=true` の場合、report の fix コールバックが `RuleFixer` を使って `TextEdit[]` を生成。`FixApplier.applyFixes(sourceCode, fixes)` が全編集をソーステキストに一括適用（重複検出付き）
 
 ## MLDOM クラス階層
 
@@ -210,10 +212,9 @@ MLToken<A extends MLASTToken>
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `walkOn(type, walker)`            | 指定した型（`'Element'`, `'Text'`, `'Comment'`, `'Attr'`, `'ElementCloseTag'`）のノードを走査                       |
 | `setRule(rule)`                   | 現在のルールを設定（検証時に `MLCore` が使用）                                                                      |
-| `getTokenList()`                  | ソース再構築用の全トークンを返す                                                                                    |
 | `searchNodeByLocation(line, col)` | 指定したソース位置のノードを検索                                                                                    |
 | `getAccessibilityProp(node)`      | ARIA アクセシビリティプロパティを計算（`MLElement.getAccessibleName()` のキャッシュ経由でアクセシブルネームを取得） |
-| `toString(fixed?)`                | ソースコードを再構築（オプションで修正適用）                                                                        |
+| `toString()`                      | ドキュメントの生のソースコードを返す                                                                                |
 
 ## MLElement
 
@@ -292,7 +293,7 @@ type RuleSeed<T, O> = {
 - `translate` / `t` — ロケール対応のメッセージ翻訳
 - `report(report)` — ノード、メッセージ、オプションの修正とともに違反を報告
 
-`provide()` メソッドは `RuleSeed.verify()` と `RuleSeed.fix()` に渡されるコンテキストオブジェクトを返します。
+`provide()` メソッドは `RuleSeed.verify()` に渡されるコンテキストオブジェクトを返します。自動修正ロジックは、個々の `report()` 呼び出しのインライン `fix` コールバックとして提供され、独立したライフサイクルメソッドではありません。
 
 ### ルール設定の解決
 
@@ -367,6 +368,158 @@ Named nodeRule（設定）                  仮想 MLRule（ランタイム）
 2. **グループ無効化**: `rules["custom/multi"]: false`（複数エントリの named nodeRule 用）
 3. **名前空間ワイルドカード**: `rules["a11y/*"]: false`（`a11y/` で始まるすべての仮想ルールを無効化）
 
+## 自動修正（Autofix）システム
+
+自動修正システムは、ルールが違反に対する自動修正を提供する仕組みです。**RuleFixer**（TextEdit ビルダー）、**fix コールバック**（ルール作者が記述するロジック）、**FixApplier**（編集適用エンジン）の 3 つのコンポーネントで構成されます。
+
+### 自動修正のデータフロー
+
+```mermaid
+flowchart LR
+    subgraph RulePhase ["ルールフェーズ"]
+        report["context.report({\n  message,\n  scope,\n  fix: コールバック\n})"]
+    end
+
+    subgraph FixPhase ["Fix コールバック実行"]
+        callback["fix(fixer) → TextEdit[]"]
+        fixer["RuleFixer\n(共有インスタンス)"]
+        callback --> fixer
+    end
+
+    subgraph ApplyPhase ["適用フェーズ"]
+        fixdata["FixData\n{ edits: TextEdit[] }"]
+        applier["applyFixes(\n  sourceCode,\n  allFixes\n)"]
+        output["fixedCode"]
+        fixdata --> applier --> output
+    end
+
+    report --> callback
+    fixer --> fixdata
+```
+
+### Fix コールバックの動作
+
+ルールは各 `report()` 呼び出しにオプションの `fix` コールバックを付与します。このコールバックはルール検証中には**実行されず**、保存されるだけです。`MLCore.verify()` に `fix=true` が渡された場合にのみ呼び出されます。
+
+```mermaid
+sequenceDiagram
+    participant Rule as ルール (verify)
+    participant Ctx as MLRuleContext
+    participant MLR as MLRule.verify()
+    participant Fixer as RuleFixer
+    participant Core as MLCore.verify()
+    participant FA as applyFixes()
+
+    Rule->>Ctx: report({ scope, message, fix })
+    Note over Ctx: fix コールバック付きレポートを格納
+
+    MLR->>Ctx: context.reports
+    loop fix コールバックを持つ各レポート
+        MLR->>Fixer: report.fix(sharedFixer)
+        Fixer-->>MLR: TextEdit | TextEdit[]
+        MLR->>MLR: FixData { edits } としてラップ
+    end
+    MLR-->>Core: Violation[]（FixData 付き）
+
+    Core->>Core: 全 Violation から FixData を収集
+    Core->>FA: applyFixes(sourceCode, allFixes)
+    FA-->>Core: FixResult { output, applied, skipped }
+```
+
+### RuleFixer API
+
+`RuleFixer` は `IRuleFixer`（`@markuplint/ml-config` で定義）を実装します。**ステートレス**なヘルパーであり、全ルールで 1 つのインスタンスを共有します。各メソッドはソースコードのレンジ置換を記述する `TextEdit` オブジェクトを生成します。
+
+| メソッド                    | 入力                                 | 生成される TextEdit                     |
+| --------------------------- | ------------------------------------ | --------------------------------------- |
+| `replaceText(token, text)`  | `startOffset` + `raw` を持つトークン | `range: [start, start+len], text`       |
+| `replaceRange(range, text)` | 明示的な `[start, end)` レンジ       | `range: [start, end], text`             |
+| `insertBefore(token, text)` | `startOffset` を持つトークン         | `range: [start, start], text`（ゼロ幅） |
+| `insertAfter(token, text)`  | `startOffset` + `raw` を持つトークン | `range: [end, end], text`（ゼロ幅）     |
+| `remove(token)`             | `startOffset` + `raw` を持つトークン | `range: [start, start+len], text: ""`   |
+| `removeRange(range)`        | 明示的な `[start, end)` レンジ       | `range: [start, end], text: ""`         |
+
+`token` パラメータは `FixToken` 型（`@markuplint/ml-config` で定義）を満たす任意のオブジェクト — つまり `{ startOffset: number; raw: string }` — を受け付けます。MLDOM トークン（`MLToken`, `MLAttr` 等）は自然にこの要件を満たします。
+
+### FixApplier アルゴリズム
+
+`applyFixes()`（`fix-applier.ts`）は全ルールの `FixData` をマージし、1 パスで適用します：
+
+```mermaid
+flowchart TD
+    A["展開: FixData[] → タグ付き TextEdit[]"]
+    B["ソート: range start 昇順、\nthen range end 降順"]
+    C["逐次適用:\n各 edit の重複をチェック"]
+    D{{"edit.start < lastAppliedEnd?"}}
+    E["スキップ\n（親 FixData をスキップとしてマーク）"]
+    F["適用\n（出力にスプライス）"]
+    G["分類: 各 FixData を\napplied または skipped に"]
+    H["FixResult を返す\n{ output, applied, skipped }"]
+
+    A --> B --> C --> D
+    D -- Yes --> E --> C
+    D -- No --> F --> C
+    C -. "全 edit 処理完了" .-> G --> H
+```
+
+主要な制約:
+
+- 1 つの `FixData` 内の edit は互いに重複してはならない
+- `FixData` 間の重複はスキップ機構で処理される
+- `FixData` 内のいずれかの edit がスキップされると、その `FixData` 全体がスキップとして分類される
+
+### マルチパス Fix ループ
+
+`applyFixes()` がレンジの重複により一部の fix をスキップした場合、エンジンはマルチパスループ（`_multiPassFix()`）に入り、再パース・再検証を繰り返して修正可能な違反をすべて解決します:
+
+```mermaid
+flowchart TD
+    A["violations から fix を抽出"] --> B["applyFixes(code, fixes)"]
+    B --> C{"applied.length === 0?"}
+    C -- Yes --> Z["現在のコードを返す"]
+    C -- No --> D{"output === currentCode?"}
+    D -- Yes --> Z
+    D -- No --> E{"サイクル検出?\n(2パス前の出力と一致)"}
+    E -- Yes --> Z
+    E -- No --> F{"skipped.length === 0?"}
+    F -- Yes --> Z["修正済みコードを返す\n(全 fix 適用完了)"]
+    F -- No --> G["再パース + 再検証"]
+    G --> H{"ParserError?"}
+    H -- Yes --> Z["最後の正常なコードに戻す"]
+    H -- No --> I{"新たな修正可能な違反?"}
+    I -- No --> Z
+    I -- Yes --> B
+```
+
+主な設計ポイント:
+
+- **ゼロコストパス**: fix を持つ violation がなければ、マルチパスループは完全にスキップされる
+- **シングルパス高速パス**: `skipped.length === 0` のとき即座にループを抜ける（Phase 1 と同等の動作）
+- **サイクル検出**: 2パス前の出力と比較し、A→B→A の振動パターンを検出
+- **安全上限**: 最大10パス（ESLint の `SourceCodeFixer` と同じ）
+- **状態復元**: `verify()` は `try/finally` で `#sourceCode`、`#ast`、`#document` を保存・復元
+
+**重要**: `VerifyResult` の `violations` 配列は初回パスの結果のみを反映し、`fixedCode` は複数パスの結果である場合があります。修正後コードの正確な違反リストが必要な場合は、出力を再検証してください。
+
+### 実例: ルールの Fix 実装
+
+```typescript
+// ルールの verify 関数内:
+context.report({
+  scope: node,
+  message: '属性値にはダブルクォートを使用してください',
+  fix: fixer => fixer.replaceText(node.attrValueToken, `"${value}"`),
+});
+```
+
+これにより以下の処理が行われます:
+
+1. **レポート** → `MLRuleContext` に格納
+2. **Fix コールバック** → `(fixer) => fixer.replaceText(token, text)`（まだ呼び出されない）
+3. **`fix=true` の場合** → 共有 `RuleFixer` でコールバック実行 → `TextEdit` を返す
+4. **TextEdit** → `FixData { edits: [{ range: [12, 17], text: '"hello"' }] }` としてラップ
+5. **applyFixes** → ソースコードに置換を適用
+
 ## Pretender システム
 
 pretender システムにより、コンポーネントをリンティング時にセマンティック HTML 要素として扱うことができます。これにより、ルールがカスタムコンポーネント（例：`<MyButton>`）を標準要素（例：`<button>`）として検証できます。

package/ARCHITECTURE.md

@@ -49,9 +49,12 @@ src/
 ├── ml-rule/
 │   ├── ml-rule.ts                    — MLRule class (rule execution)
 │   ├── ml-rule-context.ts            — MLRuleContext (report collection)
+│   ├── rule-fixer.ts                 — RuleFixer (TextEdit builder for fix callbacks)
 │   ├── create-rule.ts                — createRule factory
 │   ├── create-test-rule.ts           — Test rule factory
 │   └── types.ts                      — RuleSeed, Checker types
+├── cursor-offset.ts                  — computeCursorOffset (cursor remapping after edits)
+├── fix-applier.ts                    — applyFixes (overlap-aware TextEdit applicator)
 ├── ruleset/
 │   └── index.ts                      — Ruleset class (rules + nodeRules + childNodeRules)
 ├── plugin/
@@ -131,7 +134,7 @@ flowchart LR
     A["MLCore\nconstructor"]
     B["_parse()\nParser → MLASTDocument"]
     C["_createDocument()\nMLASTDocument → MLDocument"]
-    D["verify(fix?)\nFor each rule:"]
+    D["verify(fix? | options?)\nFor each rule:"]
     E["document.setRule(rule)\nRuleMapper maps config → nodes"]
     F["rule.verify(document)\nMLRuleContext collects reports"]
     G["Violations[]"]
@@ -143,8 +146,8 @@ flowchart LR
 
 1. **Parse**: `MLCore` invokes the configured parser (`MLParser`) to produce an `MLASTDocument`
 2. **Create Document**: The AST is wrapped in an `MLDocument`, which builds the full MLDOM tree via `createNode()` factory. `RuleMapper` resolves rule configuration for every node
-3. **Verify**: For each `MLRule`, the engine calls `document.setRule(rule)` then `rule.verify(document)`. The rule walks relevant nodes via `document.walkOn()` and reports violations through `MLRuleContext`
-4. **Fix** (optional): When `fix=true`, rules may call `node.fix()` to modify token content. `document.toString(true)` produces the fixed source
+3. **Verify**: For each `MLRule`, the engine calls `document.setRule(rule)` then `rule.verify(document)`. The rule walks relevant nodes via `document.walkOn()` and reports violations through `MLRuleContext`. Rules may attach inline `fix` callbacks to reports that return `TextEdit` objects
+4. **Fix** (optional): When `fix=true`, fix callbacks on reports are executed via `RuleFixer` to produce `TextEdit[]`. `FixApplier.applyFixes(sourceCode, fixes)` applies all edits to the source text with overlap detection. When fixes require multiple passes, `_multiPassFix()` orchestrates re-parsing and re-verification, returning a `FixSummary` with pass count, applied/skipped totals, and first-pass edits for cursor offset computation
 
 ## MLDOM Class Hierarchy
 
@@ -210,10 +213,9 @@ The constructor receives an `MLASTDocument`, a `Ruleset`, and an `MLSchema` tupl
 | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `walkOn(type, walker)`            | Walks nodes of a given type (`'Element'`, `'Text'`, `'Comment'`, `'Attr'`, `'ElementCloseTag'`)                  |
 | `setRule(rule)`                   | Sets the current rule, used by `MLCore` during verification                                                      |
-| `getTokenList()`                  | Returns all tokens for source reconstruction                                                                     |
 | `searchNodeByLocation(line, col)` | Finds the node at a given source position                                                                        |
 | `getAccessibilityProp(node)`      | Computes ARIA accessibility properties (delegates to `MLElement.getAccessibleName()` for cached accessible name) |
-| `toString(fixed?)`                | Reconstructs source code, optionally with fixes applied                                                          |
+| `toString()`                      | Returns the raw source code of the document                                                                      |
 
 ## MLElement
 
@@ -292,7 +294,7 @@ type RuleSeed<T, O> = {
 - `translate` / `t` — Locale-aware message translator
 - `report(report)` — Reports a violation with node, message, and optional fix
 
-The `provide()` method returns the context object passed to `RuleSeed.verify()` and `RuleSeed.fix()`.
+The `provide()` method returns the context object passed to `RuleSeed.verify()`. Auto-fix logic is provided as an inline `fix` callback on individual `report()` calls, not as a separate lifecycle method.
 
 ### Rule Configuration Resolution
 
@@ -367,6 +369,207 @@ Virtual rules can be disabled at three levels in the `rules` config:
 2. **Group disable**: `rules["custom/multi"]: false` (for multi-entry named nodeRules)
 3. **Namespace wildcard**: `rules["a11y/*"]: false` (disables all virtual rules starting with `a11y/`)
 
+## Autofix System
+
+The autofix system allows rules to provide automatic fixes for violations. It operates through three components: **RuleFixer** (TextEdit builder), **fix callbacks** (rule-authored logic), and **FixApplier** (edit application engine).
+
+### Autofix Data Flow
+
+```mermaid
+flowchart LR
+    subgraph RulePhase ["Rule Phase"]
+        report["context.report({\n  message,\n  scope,\n  fix: callback\n})"]
+    end
+
+    subgraph FixPhase ["Fix Callback Execution"]
+        callback["fix(fixer) → TextEdit[]"]
+        fixer["RuleFixer\n(shared instance)"]
+        callback --> fixer
+    end
+
+    subgraph ApplyPhase ["Apply Phase"]
+        fixdata["FixData\n{ edits: TextEdit[] }"]
+        applier["applyFixes(\n  sourceCode,\n  allFixes\n)"]
+        output["fixedCode"]
+        fixdata --> applier --> output
+    end
+
+    report --> callback
+    fixer --> fixdata
+```
+
+### How Fix Callbacks Work
+
+Rules attach an optional `fix` callback to each `report()` call. The callback is **not** executed during rule verification — it is stored and only invoked when `fix=true` is passed to `MLCore.verify()`.
+
+```mermaid
+sequenceDiagram
+    participant Rule as Rule (verify)
+    participant Ctx as MLRuleContext
+    participant MLR as MLRule.verify()
+    participant Fixer as RuleFixer
+    participant Core as MLCore.verify()
+    participant FA as applyFixes()
+
+    Rule->>Ctx: report({ scope, message, fix })
+    Note over Ctx: Stores report with fix callback
+
+    MLR->>Ctx: context.reports
+    loop Each report with fix callback
+        MLR->>Fixer: report.fix(sharedFixer)
+        Fixer-->>MLR: TextEdit | TextEdit[]
+        MLR->>MLR: Wrap as FixData { edits }
+    end
+    MLR-->>Core: Violation[] (with FixData)
+
+    Core->>Core: Collect all FixData from violations
+    Core->>FA: applyFixes(sourceCode, allFixes)
+    FA-->>Core: FixResult { output, applied, skipped, appliedEdits }
+```
+
+### RuleFixer API
+
+`RuleFixer` implements `IRuleFixer` (defined in `@markuplint/ml-config`). It is a **stateless** helper — a single instance is shared across all rules. Each method builds a `TextEdit` object describing a range replacement on the source code.
+
+| Method                      | Input                            | TextEdit Produced                          |
+| --------------------------- | -------------------------------- | ------------------------------------------ |
+| `replaceText(token, text)`  | Token with `startOffset` + `raw` | `range: [start, start+len], text`          |
+| `replaceRange(range, text)` | Explicit `[start, end)` range    | `range: [start, end], text`                |
+| `insertBefore(token, text)` | Token with `startOffset`         | `range: [start, start], text` (zero-width) |
+| `insertAfter(token, text)`  | Token with `startOffset` + `raw` | `range: [end, end], text` (zero-width)     |
+| `remove(token)`             | Token with `startOffset` + `raw` | `range: [start, start+len], text: ""`      |
+| `removeRange(range)`        | Explicit `[start, end)` range    | `range: [start, end], text: ""`            |
+
+The `token` parameter accepts any object satisfying the `FixToken` type (defined in `@markuplint/ml-config`) — i.e., `{ startOffset: number; raw: string }`. MLDOM tokens (`MLToken`, `MLAttr`, etc.) satisfy this naturally.
+
+### FixApplier Algorithm
+
+`applyFixes()` (in `fix-applier.ts`) merges all `FixData` from all rules and applies them in a single pass:
+
+```mermaid
+flowchart TD
+    A["Flatten: FixData[] → tagged TextEdit[]"]
+    B["Sort: by range start ascending,\nthen range end descending"]
+    C["Apply sequentially:\nfor each edit, check overlap"]
+    D{{"edit.start < lastAppliedEnd?"}}
+    E["Skip edit\n(mark parent FixData as skipped)"]
+    F["Apply edit\n(splice into output)"]
+    G["Classify: each FixData as\napplied or skipped"]
+    H["Return FixResult\n{ output, applied, skipped, appliedEdits }"]
+
+    A --> B --> C --> D
+    D -- Yes --> E --> C
+    D -- No --> F --> C
+    C -. "all edits processed" .-> G --> H
+```
+
+Key constraints:
+
+- Edits within a single `FixData` must not overlap each other
+- Inter-`FixData` overlap is handled by the skip mechanism
+- If any edit in a `FixData` is skipped, the entire `FixData` is classified as skipped
+- `appliedEdits` is a flat list of all successfully applied `TextEdit` objects, sorted by `range[0]` ascending — used for cursor offset computation
+
+### Multi-Pass Fix Loop
+
+When `applyFixes()` skips some fixes due to range overlap, the engine enters a multi-pass loop (`_multiPassFix()`) that re-parses and re-verifies until all fixable violations are resolved:
+
+```mermaid
+flowchart TD
+    A["Extract fixes from violations"] --> B["applyFixes(code, fixes)"]
+    B --> C{"applied.length === 0?"}
+    C -- Yes --> Z["Return current code"]
+    C -- No --> D{"output === currentCode?"}
+    D -- Yes --> Z
+    D -- No --> E{"Cycle detected?\n(output === code from 2 passes ago)"}
+    E -- Yes --> Z
+    E -- No --> F{"skipped.length === 0?"}
+    F -- Yes --> Z["Return fixed code\n(all fixes applied)"]
+    F -- No --> G["Re-parse + re-verify"]
+    G --> H{"ParserError?"}
+    H -- Yes --> Z["Revert to last good code"]
+    H -- No --> I{"New fixable violations?"}
+    I -- No --> Z
+    I -- Yes --> B
+```
+
+Key design points:
+
+- **Zero-cost path**: If no violations have fixes, the multi-pass loop is skipped entirely
+- **Single-pass fast path**: When `skipped.length === 0`, the loop exits immediately — equivalent to Phase 1 behavior
+- **Cycle detection**: Compares current output against the output from two passes ago to detect A→B→A oscillation
+- **Safety cap**: Maximum 10 passes (same as ESLint's `SourceCodeFixer`)
+- **State restoration**: `verify()` saves and restores `#sourceCode`, `#ast`, and `#document` via `try/finally`
+
+**Important**: The `violations` array in `VerifyResult` reflects the first pass only, while `fixedCode` may be the result of multiple passes. Callers needing an accurate violation list for the fixed code should re-verify the output.
+
+### VerifyResult and FixSummary
+
+`MLCore.verify()` accepts either a `boolean` or a `VerifyOptions` object:
+
+```typescript
+verify(fix?: boolean): Promise<VerifyResult>;
+verify(options?: VerifyOptions): Promise<VerifyResult>;
+```
+
+`VerifyResult` contains:
+
+| Field        | Type                      | Description                                                   |
+| ------------ | ------------------------- | ------------------------------------------------------------- |
+| `violations` | `readonly Violation[]`    | Violations from the first verification pass                   |
+| `fixedCode`  | `string \| undefined`     | Source after all fix passes; `undefined` when fix is disabled |
+| `fixSummary` | `FixSummary \| undefined` | Fix process summary; present when `fix=true`                  |
+
+`FixSummary` provides diagnostics about the multi-pass fix process:
+
+| Field              | Type                  | Description                                                      |
+| ------------------ | --------------------- | ---------------------------------------------------------------- |
+| `passCount`        | `number`              | Number of fix passes executed                                    |
+| `totalApplied`     | `number`              | Total fixes applied across all passes                            |
+| `totalSkipped`     | `number`              | Total fixes skipped (overlap) across all passes                  |
+| `reachedMaxPasses` | `boolean`             | Whether the 10-pass safety cap was reached                       |
+| `firstPassEdits`   | `readonly TextEdit[]` | Applied edits from the first pass only (original source offsets) |
+
+`firstPassEdits` references the original source code offsets, making them suitable for cursor remapping via `computeCursorOffset()`.
+
+### Cursor Offset Computation
+
+`computeCursorOffset()` (in `cursor-offset.ts`) maps a cursor position from the original source to the fixed source using the first-pass applied edits:
+
+```typescript
+import { computeCursorOffset } from '@markuplint/ml-core';
+
+const newOffset = computeCursorOffset(fixSummary.firstPassEdits, originalCursorOffset);
+```
+
+Algorithm:
+
+1. Walk through edits sorted by `range[0]` ascending
+2. For each edit before the cursor: accumulate `delta = text.length - (end - start)`
+3. For edits after the cursor: stop (no effect)
+4. If the cursor falls inside a replaced range `[start, end)`: place at `start + text.length`
+
+Ranges use half-open intervals: a cursor at position `end` is considered **outside** the edit.
+
+### Example: Rule Fix in Practice
+
+```typescript
+// In a rule's verify function:
+context.report({
+  scope: node,
+  message: 'Attribute value must use double quotes',
+  fix: fixer => fixer.replaceText(node.attrValueToken, `"${value}"`),
+});
+```
+
+This produces:
+
+1. **Report** → stored in `MLRuleContext`
+2. **Fix callback** → `(fixer) => fixer.replaceText(token, text)` (not yet called)
+3. **When `fix=true`** → callback invoked with shared `RuleFixer` → returns `TextEdit`
+4. **TextEdit** → wrapped as `FixData { edits: [{ range: [12, 17], text: '"hello"' }] }`
+5. **applyFixes** → splices the replacement into source code
+
 ## Pretender System
 
 The pretender system allows components to be treated as semantic HTML elements during linting. This enables rules to validate custom components (e.g., `<MyButton>`) as if they were standard elements (e.g., `<button>`).

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-alpha.3](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.2...v5.0.0-alpha.3) (2026-02-26)
+
+### Bug Fixes
+
+- **ml-core:** treat edits within a single FixData as atomic unit ([0bb980b](https://github.com/markuplint/markuplint/commit/0bb980b7cc6fc9b89a82f3d4df58b7137a6b8766))
+
+### Features
+
+- **ml-core:** add cursor offset computation and fix summary metadata ([74b6e28](https://github.com/markuplint/markuplint/commit/74b6e28e4be2802e841697899f57f6ae04e4ffe9))
+- **ml-core:** add multi-pass fix loop and cycle detection ([866b1d5](https://github.com/markuplint/markuplint/commit/866b1d54199ed1f1b5195cd0f61f3ee392b1d8a7))
+
+# [5.0.0-alpha.2](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.1...v5.0.0-alpha.2) (2026-02-23)
+
+### Features
+
+- **ml-core:** implement autofix engine with fix-applier and rule-fixer ([36efcec](https://github.com/markuplint/markuplint/commit/36efcecb17e2f4e0729390b1684e571c13c38a38))
+
+### BREAKING CHANGES
+
+- **ml-core:** verify() now returns VerifyResult instead of
+  Violation[]. RuleSeed.fix() is removed in favor of inline fix
+  callbacks on report().
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
 # [5.0.0-alpha.1](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.0...v5.0.0-alpha.1) (2026-02-22)
 
 **Note:** Version bump only for package @markuplint/ml-core

package/docs/ml-dom/document.ja.md

@@ -109,15 +109,9 @@ await document.walkOn(
 
 `AccessibilityProperties` を返します（[型ユーティリティ](./helpers.ja.md#型ユーティリティ)を参照）。
 
-## `toString(fixed?)`
+## `toString()`
 
-トークンリストからソースコードを再構築します。
-
-- `fixed=false`（デフォルト）：元の `raw` 文字列を返す
-- `fixed=true`：オフセット追跡による置換を適用する：
-  1. `getTokenList()` を取得する（`startOffset` でソート済み）
-  2. 各トークンに対して：`toString(true) !== raw` の場合、修正済みコンテンツを文字列にスプライスする
-  3. 正確な位置を維持するために累積オフセット差を追跡する
+ドキュメントの元の `raw` ソース文字列を返します。修正は DOM ノードの変更とトークンリストの再構築を通じて適用されなくなりました。代わりに、レポートの修正コールバックが `RuleFixer` を通じて実行され、`TextEdit[]` を生成します。`FixApplier.applyFixes()` がすべての編集をソーステキストに直接適用します。
 
 ## `defaultView`
 
@@ -125,12 +119,11 @@ await document.walkOn(
 
 ## その他のメソッド
 
-| メソッド               | シグネチャ                                        | 説明                                                                                                 |
-| ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `setRule`              | `setRule(rule: MLRule \| null): void`             | 現在評価中のルールを設定/クリアする                                                                  |
-| `getTokenList`         | `getTokenList(): ReadonlyArray<MLToken>`          | ソース再構築用のすべてのトークン。オフセットでソート済み（キャッシュ）。ノードと閉じタグの両方を含む |
-| `searchNodeByLocation` | `searchNodeByLocation(line, col): MLNode \| null` | 1始まりのソース位置でノードを検索する                                                                |
-| `debugMap`             | `debugMap(): string[]`                            | ドキュメントツリー構造のデバッグ出力                                                                 |
+| メソッド               | シグネチャ                                        | 説明                                  |
+| ---------------------- | ------------------------------------------------- | ------------------------------------- |
+| `setRule`              | `setRule(rule: MLRule \| null): void`             | 現在評価中のルールを設定/クリアする   |
+| `searchNodeByLocation` | `searchNodeByLocation(line, col): MLNode \| null` | 1始まりのソース位置でノードを検索する |
+| `debugMap`             | `debugMap(): string[]`                            | ドキュメントツリー構造のデバッグ出力  |
 
 ## endTag モード
 

package/docs/ml-dom/document.md

@@ -109,15 +109,9 @@ Computes ARIA accessibility properties for a node.
 
 Returns `AccessibilityProperties` (see [Type Utilities](./helpers.md#type-utilities)).
 
-## `toString(fixed?)`
+## `toString()`
 
-Reconstructs the source code from the token list.
-
-- `fixed=false` (default): Returns the original `raw` string
-- `fixed=true`: Applies offset-tracked replacement:
-  1. Get `getTokenList()` (sorted by `startOffset`)
-  2. For each token: if `toString(true) !== raw`, splice the fixed content into the string
-  3. Track cumulative offset differences to maintain correct positions
+Returns the original `raw` source string of the document. Fixes are no longer applied through DOM node mutation and token-list reconstruction. Instead, fix callbacks on reports are executed via `RuleFixer` to produce `TextEdit[]`. `FixApplier.applyFixes()` applies all edits to the source text.
 
 ## `defaultView`
 
@@ -125,12 +119,11 @@ Returns a mock window object providing `getComputedStyle()` that returns an obje
 
 ## Other Methods
 
-| Method                 | Signature                                         | Description                                                                                          |
-| ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `setRule`              | `setRule(rule: MLRule \| null): void`             | Set/clear the current rule being evaluated                                                           |
-| `getTokenList`         | `getTokenList(): ReadonlyArray<MLToken>`          | All tokens for source reconstruction, sorted by offset (cached). Includes both nodes and close tags. |
-| `searchNodeByLocation` | `searchNodeByLocation(line, col): MLNode \| null` | Find node at a 1-based source position                                                               |
-| `debugMap`             | `debugMap(): string[]`                            | Debug output of document tree structure                                                              |
+| Method                 | Signature                                         | Description                                |
+| ---------------------- | ------------------------------------------------- | ------------------------------------------ |
+| `setRule`              | `setRule(rule: MLRule \| null): void`             | Set/clear the current rule being evaluated |
+| `searchNodeByLocation` | `searchNodeByLocation(line, col): MLNode \| null` | Find node at a 1-based source position     |
+| `debugMap`             | `debugMap(): string[]`                            | Debug output of document tree structure    |
 
 ## endTag Modes
 

package/docs/ml-dom/element.ja.md

@@ -8,20 +8,18 @@ HTML/SVG/MathML の要素ノードです。`MLParentNode` を継承し、`Elemen
 
 要素には異なる目的に使用される複数の名前関連プロパティがあります：
 
-| プロパティ      | HTML `<DIV>`                | SVG `<foreignObject>` | Pretender（`MyButton` → `button`） |
-| --------------- | --------------------------- | --------------------- | ---------------------------------- |
-| `localName`     | `"div"`                     | `"foreignObject"`     | `"button"`                         |
-| `nodeName`      | `"DIV"`                     | `"foreignObject"`     | `"BUTTON"`                         |
-| `rawName`       | `"DIV"`                     | `"foreignObject"`     | `"MyButton"`                       |
-| `fixedNodeName` | `"DIV"`（修正後は `"div"`） | `"foreignObject"`     | `"MyButton"`                       |
-| `tagName`       | `"DIV"`                     | `"foreignObject"`     | `"BUTTON"`                         |
+| プロパティ  | HTML `<DIV>` | SVG `<foreignObject>` | Pretender（`MyButton` → `button`） |
+| ----------- | ------------ | --------------------- | ---------------------------------- |
+| `localName` | `"div"`      | `"foreignObject"`     | `"button"`                         |
+| `nodeName`  | `"DIV"`      | `"foreignObject"`     | `"BUTTON"`                         |
+| `rawName`   | `"DIV"`      | `"foreignObject"`     | `"MyButton"`                       |
+| `tagName`   | `"DIV"`      | `"foreignObject"`     | `"BUTTON"`                         |
 
 **ルール：**
 
 - **`localName`**: HTML 要素 → 小文字化。外部要素または非 `'html'` の elementType → そのまま。pretender コンテキスト → pretender の `localName`。`tagNameCaseSensitive` が `true` の場合 → 小文字化しない。
 - **`nodeName`**: HTML 要素 → 大文字化（DOM 慣例）。外部要素または非 `'html'` の elementType → AST からそのまま。pretender コンテキスト → pretender の `nodeName`。
 - **`rawName`**: 常に元の AST `nodeName`。正規化なし、pretender の影響なし。
-- **`fixedNodeName`**: 初期値は `rawName`。リント修正がタグ名を変更した場合に `fixNodeName(name)` で更新される。
 - **`tagName`**: `nodeName` と同じ（pretender コンテキストに従う）。
 
 ## 要素型の判定
@@ -98,7 +96,6 @@ Pretender システムのアーキテクチャ、初期化フロー、プロパ
 
 | メソッド                 | シグネチャ                                        | 説明                                                                               |
 | ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `fixNodeName`            | `fixNodeName(name: string): void`                 | リント自動修正用に `fixedNodeName` を更新する                                      |
 | `getAccessibleName`      | `getAccessibleName(version: ARIAVersion): string` | `getAccname()` を通じてアクセシブル名を計算する                                    |
 | `toNormalizeString`      | `toNormalizeString(): string`                     | 比較用の正規化された表現を返す（キャッシュ済み）。子要素と属性を再帰的に正規化する |
 | `nextElementSibling`     | `get nextElementSibling: MLElement \| null`       | 次の兄弟要素                                                                       |
@@ -134,7 +131,7 @@ Pretender システムのアーキテクチャ、初期化フロー、プロパ
 
 - 対応するソーストークンを持たない
 - `prevToken` によってスキップされる（有効なオフセットチェーンを維持するため）
-- `toString(fixed)` から `raw` を返す（ソースに修正すべきものがないため修正は適用されない）
+- `toString()` から `raw` を返す（ソースに対応するものがないため）
 - `getChildElementsAndTextNodeWithoutWhitespaces()` によってフラット化される
 
 ## 閉じタグ
@@ -143,21 +140,9 @@ Pretender システムのアーキテクチャ、初期化フロー、プロパ
 | ---------- | --------------------------- | ------------------------------------------------------------------------------------ |
 | `closeTag` | `MLElementCloseTag \| null` | ペアの閉じタグ。void 要素、自己閉じ要素、または `endTag === 'never'` の場合は `null` |
 
-## `toString(fixed?)`
+## `toString()`
 
-修正を適用して要素のソース文字列を再構築します。
-
-- `fixed=false` または pretender/省略要素/`#` プレフィックスの nodeName → `raw` を返す
-- `fixed=true`:
-  1. 置換可能なノードのリストを構築する：`[tagOpenChar + fixedNodeName, ...overriddenCommentNodes, ...attributes]`
-  2. 各ノードに対して、正しいオフセットで `node.toString(true)` をスプライスする
-  3. 正確な位置決めのために累積オフセット差を追跡する
-
-```
-Original: <DIV class="foo" >
-Fixed:    <div class="foo" >
-          ^^^^              (fixedNodeName が "DIV" から "div" に変更)
-```
+要素の生のソース文字列を返します。このメソッドはパースされたドキュメントに記述されたままの元の `raw` ソーステキストを単純に返します。修正は DOM ノードの変更を通じて適用されなくなりました。代わりに、修正操作は `RuleFixer` を通じて `TextEdit[]` を生成し、`FixApplier.applyFixes()` がすべての編集をソーステキストに直接適用します。
 
 ## その他のプロパティ