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

package/docs/ml-dom/element.md

@@ -8,20 +8,18 @@ HTML/SVG/MathML element node. Extends `MLParentNode` and implements `Element`, `
 
 The element has multiple name-related properties that serve different purposes:
 
-| Property        | HTML `<DIV>`                   | SVG `<foreignObject>` | Pretender (`MyButton` → `button`) |
-| --------------- | ------------------------------ | --------------------- | --------------------------------- |
-| `localName`     | `"div"`                        | `"foreignObject"`     | `"button"`                        |
-| `nodeName`      | `"DIV"`                        | `"foreignObject"`     | `"BUTTON"`                        |
-| `rawName`       | `"DIV"`                        | `"foreignObject"`     | `"MyButton"`                      |
-| `fixedNodeName` | `"DIV"` (or `"div"` after fix) | `"foreignObject"`     | `"MyButton"`                      |
-| `tagName`       | `"DIV"`                        | `"foreignObject"`     | `"BUTTON"`                        |
+| Property    | HTML `<DIV>` | SVG `<foreignObject>` | Pretender (`MyButton` → `button`) |
+| ----------- | ------------ | --------------------- | --------------------------------- |
+| `localName` | `"div"`      | `"foreignObject"`     | `"button"`                        |
+| `nodeName`  | `"DIV"`      | `"foreignObject"`     | `"BUTTON"`                        |
+| `rawName`   | `"DIV"`      | `"foreignObject"`     | `"MyButton"`                      |
+| `tagName`   | `"DIV"`      | `"foreignObject"`     | `"BUTTON"`                        |
 
 **Rules:**
 
 - **`localName`**: HTML elements → lowercased. Foreign elements or non-`'html'` elementType → as-is. Pretender context → pretender's `localName`. If `tagNameCaseSensitive` is `true` → no lowercasing.
 - **`nodeName`**: HTML elements → uppercased (DOM convention). Foreign elements or non-`'html'` elementType → as-is from AST. Pretender context → pretender's `nodeName`.
 - **`rawName`**: Always the original AST `nodeName`, with no normalization and no pretender influence.
-- **`fixedNodeName`**: Starts as `rawName`. Updated by `fixNodeName(name)` when a lint fix modifies the tag name.
 - **`tagName`**: Same as `nodeName` (follows pretender context).
 
 ## Element Type Resolution
@@ -98,7 +96,6 @@ For comprehensive documentation on the pretender system's architecture, initiali
 
 | Method                   | Signature                                         | Description                                                                                                  |
 | ------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `fixNodeName`            | `fixNodeName(name: string): void`                 | Updates `fixedNodeName` for lint auto-fix of the tag name                                                    |
 | `getAccessibleName`      | `getAccessibleName(version: ARIAVersion): string` | Computes the accessible name via `getAccname()`                                                              |
 | `toNormalizeString`      | `toNormalizeString(): string`                     | Returns a normalized representation for comparison (cached). Recursively normalizes children and attributes. |
 | `nextElementSibling`     | `get nextElementSibling: MLElement \| null`       | Next sibling element                                                                                         |
@@ -134,7 +131,7 @@ Elements with `isOmitted === true` were implicitly inserted by the parser (e.g.,
 
 - Have no corresponding source tokens
 - Are skipped by `prevToken` (to maintain valid offset chains)
-- Return `raw` from `toString(fixed)` (no fix is applied since there's nothing in the source to fix)
+- Return `raw` from `toString()` (there's nothing in the source to represent)
 - Are flattened by `getChildElementsAndTextNodeWithoutWhitespaces()`
 
 ## Close Tag
@@ -143,21 +140,9 @@ Elements with `isOmitted === true` were implicitly inserted by the parser (e.g.,
 | ---------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
 | `closeTag` | `MLElementCloseTag \| null` | Paired close tag. `null` for void elements, self-closing elements, or when `endTag === 'never'`. |
 
-## `toString(fixed?)`
+## `toString()`
 
-Reconstructs the element's source string with fixes applied.
-
-- `fixed=false` or pretender/omitted/`#`-prefixed nodeName → return `raw`
-- `fixed=true`:
-  1. Build a list of replaceable nodes: `[tagOpenChar + fixedNodeName, ...overriddenCommentNodes, ...attributes]`
-  2. For each node, splice `node.toString(true)` at the correct offset
-  3. Track cumulative offset differences for accurate positioning
-
-```
-Original: <DIV class="foo" >
-Fixed:    <div class="foo" >
-          ^^^^              (fixedNodeName changed from "DIV" to "div")
-```
+Returns the element's raw source string. This method simply returns the original `raw` source text as it appeared in the parsed document. Fixes are no longer applied through DOM node mutation; instead, fix operations produce `TextEdit[]` via `RuleFixer`, and `FixApplier.applyFixes()` applies all edits directly to the source text.
 
 ## Other Properties
 

package/docs/rule-system.ja.md

@@ -189,7 +189,7 @@ constructor(document: MLDocument<T, O>, locale: LocaleSet)
 
 ### `provide(): ProvidedContext`
 
-`RuleSeed.verify()` と `RuleSeed.fix()` に渡されるコンテキストオブジェクトを返します：
+`RuleSeed.verify()` に渡されるコンテキストオブジェクトを返します。自動修正ロジックは個々の `report()` 呼び出しのインライン `fix` コールバックとして提供されます：
 
 ```typescript
 {

package/docs/rule-system.md

@@ -189,7 +189,7 @@ Creates translator from locale, stores document reference.
 
 ### `provide(): ProvidedContext`
 
-Returns the context object passed to `RuleSeed.verify()` and `RuleSeed.fix()`:
+Returns the context object passed to `RuleSeed.verify()`. Auto-fix logic is provided as an inline `fix` callback on individual `report()` calls:
 
 ```typescript
 {

package/lib/cursor-offset.d.ts

@@ -0,0 +1,13 @@
+import type { TextEdit } from '@markuplint/ml-config';
+/**
+ * Computes the new cursor offset after text edits have been applied.
+ *
+ * For each edit before the cursor: delta += text.length - (end - start).
+ * If the cursor falls inside a replaced range [start, end), it is placed
+ * at start + text.length (immediately after the replacement).
+ *
+ * @param appliedEdits - Applied edits sorted by range[0] ascending
+ * @param cursorOffset - Original 0-based cursor offset
+ * @returns New cursor offset in the fixed code
+ */
+export declare function computeCursorOffset(appliedEdits: readonly TextEdit[], cursorOffset: number): number;

package/lib/cursor-offset.js

@@ -0,0 +1,34 @@
+/**
+ * Computes the new cursor offset after text edits have been applied.
+ *
+ * For each edit before the cursor: delta += text.length - (end - start).
+ * If the cursor falls inside a replaced range [start, end), it is placed
+ * at start + text.length (immediately after the replacement).
+ *
+ * @param appliedEdits - Applied edits sorted by range[0] ascending
+ * @param cursorOffset - Original 0-based cursor offset
+ * @returns New cursor offset in the fixed code
+ */
+export function computeCursorOffset(appliedEdits, cursorOffset) {
+    let newOffset = cursorOffset;
+    for (const edit of appliedEdits) {
+        const [start, end] = edit.range;
+        const delta = edit.text.length - (end - start);
+        if (start > cursorOffset) {
+            // Edit is after cursor — no effect
+            break;
+        }
+        if (end <= cursorOffset) {
+            // Edit is entirely before cursor — shift by delta.
+            // Range is half-open [start, end), so cursor at `end` is outside the edit.
+            newOffset += delta;
+        }
+        else {
+            // Cursor falls inside the replaced range [start, end)
+            newOffset = start + edit.text.length;
+            break;
+        }
+    }
+    // Defensive guard: should never go negative with well-formed, non-overlapping edits
+    return Math.max(0, newOffset);
+}

package/lib/fix-applier.d.ts

@@ -0,0 +1,32 @@
+import type { FixData, TextEdit } from '@markuplint/ml-config';
+/**
+ * The result of applying fixes to source code.
+ */
+export type FixResult = {
+    /** The resulting source code after applying fixes */
+    readonly output: string;
+    /** Fixes that were successfully applied */
+    readonly applied: readonly FixData[];
+    /** Fixes that were skipped due to overlapping ranges */
+    readonly skipped: readonly FixData[];
+    /** Flat list of successfully applied edits, sorted by range[0] ascending */
+    readonly appliedEdits: readonly TextEdit[];
+};
+/**
+ * Applies a set of text edits to the source code.
+ *
+ * **Constraint**: Edits within a single FixData must not overlap each other,
+ * and should ideally be ordered by range[0]. Inter-FixData overlap is handled
+ * by the skip mechanism, but intra-FixData overlap leads to undefined behavior.
+ *
+ * Algorithm (modeled after ESLint's SourceCodeFixer):
+ * 1. Flatten all FixData.edits into individual edits, each tagged with its parent FixData
+ * 2. Sort by range[0] ascending (ties broken by range[1] descending)
+ * 3. Apply edits sequentially; skip any edit whose range overlaps a previously applied edit
+ * 4. Classify each FixData as applied (all edits applied) or skipped (any edit skipped)
+ *
+ * @param sourceCode - The original source code
+ * @param fixes - The fix data to apply
+ * @returns The result containing the fixed code and applied/skipped classification
+ */
+export declare function applyFixes(sourceCode: string, fixes: readonly FixData[]): FixResult;

package/lib/fix-applier.js

@@ -0,0 +1,75 @@
+/**
+ * Applies a set of text edits to the source code.
+ *
+ * **Constraint**: Edits within a single FixData must not overlap each other,
+ * and should ideally be ordered by range[0]. Inter-FixData overlap is handled
+ * by the skip mechanism, but intra-FixData overlap leads to undefined behavior.
+ *
+ * Algorithm (modeled after ESLint's SourceCodeFixer):
+ * 1. Flatten all FixData.edits into individual edits, each tagged with its parent FixData
+ * 2. Sort by range[0] ascending (ties broken by range[1] descending)
+ * 3. Apply edits sequentially; skip any edit whose range overlaps a previously applied edit
+ * 4. Classify each FixData as applied (all edits applied) or skipped (any edit skipped)
+ *
+ * @param sourceCode - The original source code
+ * @param fixes - The fix data to apply
+ * @returns The result containing the fixed code and applied/skipped classification
+ */
+export function applyFixes(sourceCode, fixes) {
+    if (fixes.length === 0) {
+        return { output: sourceCode, applied: [], skipped: [], appliedEdits: [] };
+    }
+    // Tag each edit with its parent FixData index
+    const taggedEdits = [];
+    for (const [i, fix] of fixes.entries()) {
+        for (const edit of fix.edits) {
+            taggedEdits.push({ edit, fixIndex: i });
+        }
+    }
+    // Sort: range[0] ascending, then range[1] descending (so larger ranges come first at the same start)
+    taggedEdits.sort((a, b) => {
+        const startDiff = a.edit.range[0] - b.edit.range[0];
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        return startDiff || b.edit.range[1] - a.edit.range[1];
+    });
+    // Track which FixData indices had at least one skipped edit
+    const skippedFixIndices = new Set();
+    const appliedEdits = [];
+    let lastAppliedEnd = -1;
+    const parts = [];
+    let cursor = 0;
+    for (const { edit, fixIndex } of taggedEdits) {
+        const [start, end] = edit.range;
+        // Overlap check: if this edit starts before the end of the last applied edit, skip it.
+        // Also skip if a sibling edit from the same FixData was already skipped —
+        // edits within a single FixData are atomic (all-or-nothing).
+        if (start < lastAppliedEnd || skippedFixIndices.has(fixIndex)) {
+            skippedFixIndices.add(fixIndex);
+            continue;
+        }
+        // Append the source text between the last edit and this one
+        parts.push(sourceCode.slice(cursor, start), edit.text);
+        appliedEdits.push(edit);
+        cursor = end;
+        lastAppliedEnd = end;
+    }
+    // Append remaining source text
+    parts.push(sourceCode.slice(cursor));
+    // Classify FixData as applied or skipped
+    const applied = [];
+    const skipped = [];
+    for (const [i, fix] of fixes.entries()) {
+        if (skippedFixIndices.has(i)) {
+            skipped.push(fix);
+        }
+        else {
+            applied.push(fix);
+        }
+    }
+    return {
+        output: parts.join(''),
+        applied,
+        skipped,
+        appliedEdits,
+    };
+}

package/lib/index.d.ts

@@ -2,6 +2,9 @@ export type { RuleInfo, RuleConfig, RuleConfigValue } from '@markuplint/ml-confi
 export { ariaSpecs, contentModelCategoryToTagNames, getAttrSpecs, getComputedRole, getImplicitRole, getPermittedRoles, getRoleSpec, getSpec, resolveNamespace, } from '@markuplint/ml-spec';
 export { Ruleset } from './ruleset/index.js';
 export { enableDebug } from './debug.js';
+export { computeCursorOffset } from './cursor-offset.js';
+export { applyFixes } from './fix-applier.js';
+export type { FixResult } from './fix-applier.js';
 export { getIndent } from './ml-dom/helper/get-indent.js';
 export * from './convert-ruleset.js';
 export * from './ml-core.js';

package/lib/index.js

@@ -1,6 +1,8 @@
 export { ariaSpecs, contentModelCategoryToTagNames, getAttrSpecs, getComputedRole, getImplicitRole, getPermittedRoles, getRoleSpec, getSpec, resolveNamespace, } from '@markuplint/ml-spec';
 export { Ruleset } from './ruleset/index.js';
 export { enableDebug } from './debug.js';
+export { computeCursorOffset } from './cursor-offset.js';
+export { applyFixes } from './fix-applier.js';
 export { getIndent } from './ml-dom/helper/get-indent.js';
 export * from './convert-ruleset.js';
 export * from './ml-core.js';

package/lib/ml-core.d.ts

@@ -1,7 +1,45 @@
 import type { MLFabric } from './types.js';
-import type { PlainData, RuleConfigValue, Violation } from '@markuplint/ml-config';
+import type { PlainData, RuleConfigValue, TextEdit, Violation } from '@markuplint/ml-config';
 import { ParserError } from '@markuplint/parser-utils';
 import { Document } from './ml-dom/index.js';
+/**
+ * Summary of the multi-pass fix process.
+ */
+export type FixSummary = {
+    /** Number of fix passes executed (i.e., the number of times applyFixes was called) */
+    readonly passCount: number;
+    /** Total fixes applied across all passes */
+    readonly totalApplied: number;
+    /** Total fixes skipped (overlap) across all passes */
+    readonly totalSkipped: number;
+    /** Whether the maximum pass count was reached */
+    readonly reachedMaxPasses: boolean;
+    /**
+     * Applied edits from the FIRST pass only.
+     * These reference the original source code offsets, making them suitable
+     * for cursor offset computation via {@link computeCursorOffset}.
+     * Note: `firstPassEdits.length` may differ from `totalApplied` when
+     * multiple passes are executed.
+     */
+    readonly firstPassEdits: readonly TextEdit[];
+};
+/**
+ * Options for {@link MLCore.verify}.
+ */
+export type VerifyOptions = {
+    readonly fix?: boolean;
+};
+/**
+ * The result of running {@link MLCore.verify}.
+ */
+export type VerifyResult = {
+    /** Violations found during verification */
+    readonly violations: readonly Violation[];
+    /** The source code after applying fixes. `undefined` when fix is not enabled. */
+    readonly fixedCode: string | undefined;
+    /** Fix process summary. Present when fix=true. */
+    readonly fixSummary?: FixSummary;
+};
 /**
  * Parameters for constructing an {@link MLCore} instance.
  * Extends {@link MLFabric} with the source code, filename, and debug flag.
@@ -26,7 +64,7 @@ export declare class MLCore {
     /**
      * The parsed document, or a {@link ParserError} if parsing failed.
      */
-    get document(): ParserError | Document<RuleConfigValue, PlainData>;
+    get document(): Document<RuleConfigValue, PlainData> | ParserError;
     /**
      * Replaces the source code and re-parses the document.
      *
@@ -46,11 +84,18 @@ export declare class MLCore {
      * If the document failed to parse, a single parse-error violation is returned
      * (unless parse errors are suppressed via severity options).
      *
-     * @param fix - Whether to attempt auto-fixing violations
-     * @returns An array of violations found during verification
+     * When `fix` is true, fix callbacks are executed and the resulting TextEdits
+     * are applied via a multi-pass loop to produce `fixedCode`.
+     *
+     * **Important**: `violations` reflects the *first* pass only, while `fixedCode`
+     * may be the result of multiple fix passes. This means some violations in the
+     * array may already be resolved in `fixedCode`, and new violations introduced
+     * during later passes are not included in the array. Callers needing an accurate
+     * violation list for the fixed code should re-verify the output.
+     *
+     * @param fixOrOptions - Whether to attempt auto-fixing violations, or an options object
+     * @returns Violations from the initial analysis and the (possibly fixed) source code
      */
-    verify(fix?: boolean): Promise<Violation[]>;
-    private _createDocument;
-    private _createParseError;
-    private _parse;
+    verify(fix?: boolean): Promise<VerifyResult>;
+    verify(options?: VerifyOptions): Promise<VerifyResult>;
 }