@miy2/xml-api 0.9.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Kazuya Miyashita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# XML API
+
+An XML synchronization engine that maintains full fidelity between source code and the Document Object Model (DOM).
+
+This project provides a foundational XML parser and manipulation API designed for WYSIWYG editors and Integrated Development Environments (IDEs). It features a DOM-compatible interface that bidirectionally synchronizes intuitive application edits and source code modifications, all while preserving details like whitespace and indentation.
+
+## Key Features
+
+- **Full Fidelity**: Edits preserve all whitespace, indentation, and comments automatically in unmodified parts of the code.
+- **Bidirectional Sync**: Instantly synchronizes changes between the source code and the in-memory model, ensuring consistent state across operations.
+- **DOM Compatibility**: Provides a familiar interface (`Element`, `Document`, `setAttribute`, etc.) for intuitive application development.
+- **Incremental Updates**: High performance through incremental parsing and minimal text patching.
+
+## Architecture
+
+
+
+The system is built on a robust synchronization engine orchestrated by the **XMLAPI**:
+
+
+
+1.  **SyncEngine**: The core engine that manages state via Transactions and orchestrates updates.
+
+2.  **CST (Concrete Syntax Tree)**: Captures the exact physical structure of the source code, including formatting.
+
+3.  **Model**: The authoritative internal representation that maintains object identity, coordinates synchronization, and provides a semantic view for traversal.
+
+
+
+Additionally, a **DOM-compatible Interface** wraps the Model for familiar application development.
+
+## Basic Usage
+
+### Initialization
+
+```typescript
+import { XMLAPI } from '@miy2/xml-api';
+
+const xml = `<root>
+  <item id="1">Original Value</item>
+</root>`;
+
+const api = new XMLAPI(xml);
+```
+
+### Manipulating via DOM API (Recommended)
+
+You can use standard DOM methods to manipulate the XML. These changes are automatically reflected back to the source code with minimal patches.
+
+```typescript
+const doc = api.getDocument(); // Returns a DOM-like Document
+const item = doc.querySelector('item');
+
+if (item) {
+  item.setAttribute('status', 'active');
+  item.textContent = 'Updated Value';
+}
+
+console.log(api.input);
+/* 
+Output:
+<root>
+  <item id="1" status="active">Updated Value</item>
+</root>
+*/
+```
+
+### Low-level Incremental Updates
+
+```typescript
+// Update the source code directly at specific offsets
+api.updateInput(14, 28, "New Content");
+```
+
+## Documentation
+
+- **[Getting Started](docs/guide/getting-started.md)**: Installation and detailed usage.
+- **[Architecture](docs/architecture/overview.md)**: Deep dive into the system design.
+- **[Core Concepts](docs/guide/core-concepts.md)**: Understanding Fidelity and the Layered model.
+- **[API Reference](docs/api/reference/README.md)**: Auto-generated API documentation.
+
+## Development
+
+This project uses [pnpm](https://pnpm.io/).
+
+```bash
+pnpm install
+pnpm test
+pnpm docs:gen-api
+```
+
+## License
+
+[MIT](LICENSE.md)

package/dist/collab/bridge.d.ts

@@ -0,0 +1,13 @@
+import type { Transaction } from "../engine/transaction";
+/**
+ * Interface for connecting the SyncEngine to an external collaboration system (e.g., Yjs, Automerge).
+ */
+export interface CollabBridge {
+    /**
+     * Called by SyncEngine when a local transaction is successfully dispatched.
+     * The bridge implementations should convert this transaction into CRDT operations and broadcast them.
+     *
+     * @param tr The committed transaction.
+     */
+    receiveLocalTransaction(tr: Transaction): void;
+}

package/dist/collab/bridge.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cst/grammar.d.ts

@@ -0,0 +1,93 @@
+import type { CST } from "./xml-cst";
+/**
+ * A function that performs semantic or contextual validation on a parsed CST node.
+ *
+ * It is used to enforce rules that cannot be easily expressed by the grammar itself,
+ * such as matching start and end tag names or ensuring attribute uniqueness.
+ * If it returns false, the node's `wellFormed` flag is set to false, but the
+ * parsing process continues.
+ */
+export type Validator = (node: CST, input: string) => boolean;
+/**
+ * Fundamental building blocks of the grammar.
+ * These can be combined to represent various syntax structures equivalent to EBNF.
+ */
+export type Expression = 
+/** Matches a specific exact string. */
+{
+    type: "Literal";
+    value: string;
+}
+/** Matches a regular expression pattern. */
+ | {
+    type: "RegExpMatch";
+    pattern: string;
+}
+/** Matches multiple expressions in order (AND). */
+ | {
+    type: "Sequence";
+    expressions: Expression[];
+}
+/** Matches any one of the provided expressions (OR). */
+ | {
+    type: "Choice";
+    expressions: Expression[];
+}
+/** Matches an expression repeated a specified number of times. */
+ | {
+    type: "Repeat";
+    expression: Expression;
+    min: number;
+    max: number;
+}
+/** Matches expression A, provided that expression B does not match (negation/exclusion). */
+ | {
+    type: "Exclusion";
+    a: Expression;
+    b: Expression;
+}
+/** Invokes another named rule (used for recursive definitions). */
+ | {
+    type: "Reference";
+    name: string;
+};
+/** Defines a literal string match. */
+export declare const lit: (value: string) => Expression;
+/** Defines a regular expression match. */
+export declare const reg: (pattern: string) => Expression;
+/** Defines a sequence of matches in order. */
+export declare const seq: (...expressions: Expression[]) => Expression;
+/** Defines a choice between multiple alternatives. */
+export declare const alt: (...expressions: Expression[]) => Expression;
+/** Zero or more repetitions (equivalent to `*` in EBNF). */
+export declare const rep: (expression: Expression) => Expression;
+/** One or more repetitions (equivalent to `+` in EBNF). */
+export declare const plus: (expression: Expression) => Expression;
+/** Zero or one occurrence (equivalent to `?` in EBNF, optional). */
+export declare const opt: (expression: Expression) => Expression;
+/** Matches A but excludes B (e.g., matching PITarget as a Name excluding "xml"). */
+export declare const exc: (a: Expression, b: Expression) => Expression;
+/** References another rule by its name. */
+export declare const ref: (name: string) => Expression;
+export declare class Grammar {
+    readonly rules: {
+        [key: string]: Expression;
+    };
+    readonly validators: {
+        [key: string]: Validator;
+    };
+    readonly rootRule: string;
+    constructor(rules: {
+        [key: string]: Expression;
+    }, validators: {
+        [key: string]: Validator;
+    }, rootRule: string);
+}
+export declare class GrammarBuilder {
+    private rules;
+    private validators;
+    private rootRule;
+    rule(name: string, expression: Expression): void;
+    verifyRule(name: string, validator: Validator): void;
+    build(rootRule?: string): Grammar;
+}

package/dist/cst/grammar.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrammarBuilder = exports.Grammar = exports.ref = exports.exc = exports.opt = exports.plus = exports.rep = exports.alt = exports.seq = exports.reg = exports.lit = void 0;
+// Combinators
+/** Defines a literal string match. */
+const lit = (value) => ({ type: "Literal", value });
+exports.lit = lit;
+/** Defines a regular expression match. */
+const reg = (pattern) => ({
+    type: "RegExpMatch",
+    pattern,
+});
+exports.reg = reg;
+/** Defines a sequence of matches in order. */
+const seq = (...expressions) => ({
+    type: "Sequence",
+    expressions,
+});
+exports.seq = seq;
+/** Defines a choice between multiple alternatives. */
+const alt = (...expressions) => ({
+    type: "Choice",
+    expressions,
+});
+exports.alt = alt;
+/** Zero or more repetitions (equivalent to `*` in EBNF). */
+const rep = (expression) => ({
+    type: "Repeat",
+    expression,
+    min: 0,
+    max: Infinity,
+});
+exports.rep = rep;
+/** One or more repetitions (equivalent to `+` in EBNF). */
+const plus = (expression) => ({
+    type: "Repeat",
+    expression,
+    min: 1,
+    max: Infinity,
+});
+exports.plus = plus;
+/** Zero or one occurrence (equivalent to `?` in EBNF, optional). */
+const opt = (expression) => ({
+    type: "Repeat",
+    expression,
+    min: 0,
+    max: 1,
+});
+exports.opt = opt;
+/** Matches A but excludes B (e.g., matching PITarget as a Name excluding "xml"). */
+const exc = (a, b) => ({
+    type: "Exclusion",
+    a,
+    b,
+});
+exports.exc = exc;
+/** References another rule by its name. */
+const ref = (name) => ({ type: "Reference", name });
+exports.ref = ref;
+class Grammar {
+    constructor(rules, validators, rootRule) {
+        this.rules = rules;
+        this.validators = validators;
+        this.rootRule = rootRule;
+    }
+}
+exports.Grammar = Grammar;
+class GrammarBuilder {
+    constructor() {
+        this.rules = {};
+        this.validators = {};
+        this.rootRule = null;
+    }
+    rule(name, expression) {
+        if (this.rootRule === null) {
+            this.rootRule = name;
+        }
+        this.rules[name] = expression;
+    }
+    verifyRule(name, validator) {
+        if (!this.rules[name]) {
+            throw new Error(`Rule ${name} not found`);
+        }
+        this.validators[name] = validator;
+    }
+    build(rootRule) {
+        const root = rootRule || this.rootRule;
+        if (!root) {
+            throw new Error("No root rule defined");
+        }
+        // Return an immutable Grammar instance with a shallow copy of the definitions
+        return new Grammar({ ...this.rules }, { ...this.validators }, root);
+    }
+}
+exports.GrammarBuilder = GrammarBuilder;

package/dist/cst/parser.d.ts

@@ -0,0 +1,23 @@
+import type { Grammar } from "./grammar";
+import { CST } from "./xml-cst";
+export declare class Parser {
+    grammar: Grammar;
+    constructor(grammar: Grammar);
+    parse(input: string, rootRule?: string): CST | null;
+    /**
+     * Parses the input starting from a specific position using a given rule.
+     * Useful for incremental parsing.
+     */
+    parseAt(input: string, pos: number, ruleName: string): {
+        node: CST;
+        end: number;
+    } | null;
+    private execute;
+    private execLiteral;
+    private execRegExp;
+    private execSequence;
+    private execChoice;
+    private execRepeat;
+    private execExclusion;
+    private execReference;
+}

package/dist/cst/parser.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Parser = void 0;
+const xml_cst_1 = require("./xml-cst");
+class Parser {
+    constructor(grammar) {
+        this.grammar = grammar;
+    }
+    parse(input, rootRule) {
+        const startRule = rootRule || this.grammar.rootRule;
+        const ctx = { input, pos: 0, grammar: this.grammar };
+        // Treat the entry point as a Reference to the root rule.
+        // This ensures consistent behavior (validation, node type naming) with internal references.
+        const rootExpr = { type: "Reference", name: startRule };
+        const result = this.execute(rootExpr, ctx);
+        // Ensure the entire input is consumed and the result is well-formed
+        if (result && ctx.pos === input.length) {
+            // Note: Top-level validation is already handled by executeReference if rootExpr is a Reference.
+            // If result.wellFormed is false, we still return it, but the caller can check the flag.
+            return result;
+        }
+        return null;
+    }
+    /**
+     * Parses the input starting from a specific position using a given rule.
+     * Useful for incremental parsing.
+     */
+    parseAt(input, pos, ruleName) {
+        const ctx = { input, pos, grammar: this.grammar };
+        const rootExpr = { type: "Reference", name: ruleName };
+        const result = this.execute(rootExpr, ctx);
+        if (result) {
+            return { node: result, end: ctx.pos };
+        }
+        return null;
+    }
+    execute(expr, ctx) {
+        switch (expr.type) {
+            case "Literal":
+                return this.execLiteral(expr, ctx);
+            case "RegExpMatch":
+                return this.execRegExp(expr, ctx);
+            case "Sequence":
+                return this.execSequence(expr, ctx);
+            case "Choice":
+                return this.execChoice(expr, ctx);
+            case "Repeat":
+                return this.execRepeat(expr, ctx);
+            case "Exclusion":
+                return this.execExclusion(expr, ctx);
+            case "Reference":
+                return this.execReference(expr, ctx);
+        }
+    }
+    execLiteral(expr, ctx) {
+        if (ctx.input.startsWith(expr.value, ctx.pos)) {
+            const start = ctx.pos;
+            ctx.pos += expr.value.length;
+            return new xml_cst_1.CST("literal", undefined, start, ctx.pos);
+        }
+        return null;
+    }
+    execRegExp(expr, ctx) {
+        const regex = new RegExp(expr.pattern, "y");
+        regex.lastIndex = ctx.pos;
+        const match = regex.exec(ctx.input);
+        if (match) {
+            const start = ctx.pos;
+            ctx.pos += match[0].length;
+            return new xml_cst_1.CST("regex", undefined, start, ctx.pos);
+        }
+        return null;
+    }
+    execSequence(expr, ctx) {
+        const startPos = ctx.pos;
+        const children = [];
+        let wellFormed = true;
+        for (const childExpr of expr.expressions) {
+            const result = this.execute(childExpr, ctx);
+            if (result === null) {
+                ctx.pos = startPos;
+                return null;
+            }
+            children.push(result);
+            if (!result.wellFormed) {
+                wellFormed = false;
+            }
+        }
+        return new xml_cst_1.CST("sequence", undefined, startPos, ctx.pos, children, wellFormed);
+    }
+    execChoice(expr, ctx) {
+        for (const childExpr of expr.expressions) {
+            const startPos = ctx.pos;
+            const result = this.execute(childExpr, ctx);
+            if (result !== null) {
+                return result;
+            }
+            ctx.pos = startPos;
+        }
+        return null;
+    }
+    execRepeat(expr, ctx) {
+        const startPos = ctx.pos;
+        const children = [];
+        let count = 0;
+        let wellFormed = true;
+        while (count < expr.max) {
+            const checkpoint = ctx.pos;
+            const result = this.execute(expr.expression, ctx);
+            if (result === null || ctx.pos === checkpoint)
+                break;
+            children.push(result);
+            if (!result.wellFormed) {
+                wellFormed = false;
+            }
+            count++;
+        }
+        if (count < expr.min) {
+            ctx.pos = startPos;
+            return null;
+        }
+        return new xml_cst_1.CST("repeat", undefined, startPos, ctx.pos, children, wellFormed);
+    }
+    execExclusion(expr, ctx) {
+        const startPos = ctx.pos;
+        const resultA = this.execute(expr.a, ctx);
+        if (resultA === null)
+            return null;
+        const endPosA = ctx.pos;
+        ctx.pos = startPos;
+        const resultB = this.execute(expr.b, ctx);
+        // Check if B matches and is at least as long as A
+        if (resultB !== null &&
+            startPos + (resultB.end - resultB.start) >= endPosA) {
+            ctx.pos = startPos;
+            return null;
+        }
+        ctx.pos = endPosA;
+        return resultA;
+    }
+    execReference(expr, ctx) {
+        const rule = ctx.grammar.rules[expr.name];
+        if (!rule)
+            return null; // Should not happen if grammar is well-defined, or could throw error
+        const result = this.execute(rule, ctx);
+        if (result === null)
+            return null;
+        // Always wrap the result to preserve the rule name in the hierarchy.
+        const node = new xml_cst_1.CST(result.type, expr.name, result.start, result.end, [result], result.wellFormed);
+        // Apply validation
+        const validator = ctx.grammar.validators[expr.name];
+        if (validator) {
+            // Pass only necessary context (input string) to the validator
+            if (!validator(node, ctx.input)) {
+                node.wellFormed = false;
+            }
+        }
+        return node;
+    }
+}
+exports.Parser = Parser;

package/dist/cst/xml-cst.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Represents a node in the Concrete Syntax Tree (Parse Tree).
+ * Each node corresponds to a match of a grammatical structure or rule.
+ */
+export declare class CST {
+    /**
+     * The type of the grammatical structure matched.
+     * Common values include "literal", "regex", "sequence", "repeat".
+     * This describes the structural nature of the match, not the grammar rule name.
+     */
+    type: string;
+    /**
+     * The name of the grammar rule corresponding to this node (e.g., "element", "attribute").
+     * Defined only if this node represents a named rule reference; otherwise undefined.
+     */
+    name: string | undefined;
+    /**
+     * The 0-based starting index of this node in the entire input string (inclusive).
+     */
+    start: number;
+    /**
+     * The 0-based ending index of this node in the entire input string (exclusive).
+     * The length of the match is (end - start).
+     */
+    end: number;
+    /**
+     * Child nodes contained within this structure.
+     * Empty for leaf nodes like literals or regex matches.
+     */
+    children: CST[];
+    /**
+     * Indicates whether the node satisfies additional validation logic beyond basic parsing.
+     * If false, the node was parsed successfully according to the grammar structure
+     * but failed a semantic or contextual validation check.
+     */
+    wellFormed: boolean;
+    /**
+     * Reference to the parent node in the syntax tree.
+     * Null if this is the root node.
+     */
+    parent: CST | null;
+    constructor(
+    /**
+     * The type of the grammatical structure matched.
+     * Common values include "literal", "regex", "sequence", "repeat".
+     * This describes the structural nature of the match, not the grammar rule name.
+     */
+    type: string, 
+    /**
+     * The name of the grammar rule corresponding to this node (e.g., "element", "attribute").
+     * Defined only if this node represents a named rule reference; otherwise undefined.
+     */
+    name: string | undefined, 
+    /**
+     * The 0-based starting index of this node in the entire input string (inclusive).
+     */
+    start: number, 
+    /**
+     * The 0-based ending index of this node in the entire input string (exclusive).
+     * The length of the match is (end - start).
+     */
+    end: number, 
+    /**
+     * Child nodes contained within this structure.
+     * Empty for leaf nodes like literals or regex matches.
+     */
+    children?: CST[], 
+    /**
+     * Indicates whether the node satisfies additional validation logic beyond basic parsing.
+     * If false, the node was parsed successfully according to the grammar structure
+     * but failed a semantic or contextual validation check.
+     */
+    wellFormed?: boolean);
+    /**
+     * Retrieves the substring matching this node from the entire original input string.
+     */
+    getText(input: string): string;
+    /**
+     * Shifts the start and end positions of this node and its children.
+     * @param pos The position where the change occurred.
+     * @param delta The change in length.
+     */
+    shift(pos: number, delta: number): void;
+    /**
+     * Unwraps single-child Reference nodes to find the underlying structural node.
+     */
+    unwrap(): CST;
+}