batis-xml 0.1.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ESPINS <dlwlalsggg@gmail.com>
+
+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,152 @@
+# batis-xml
+
+WebAssembly bindings for [`batis-xml`](https://github.com/espins-labs/batis-xml)
+— a parser and dynamic-SQL flattener for MyBatis and iBatis mapper XML.
+
+```js
+const batisXml = require("batis-xml");
+
+const bytes = fs.readFileSync("OrderMapper.xml"); // Buffer, NOT a decoded string
+const result = JSON.parse(batisXml.parse(bytes)); // schema v1, see schema.d.ts
+const dialect = batisXml.detect(bytes); // "mybatis" | "ibatis" | "unknown" -- cheap pre-check
+```
+
+TypeScript consumers: `schema.d.ts` ships in this package (generated from
+`schema/batis-xml.v1.json`, drift-checked in CI) —
+`import type { ParseResult } from "batis-xml/schema"`.
+
+**Node.js target only — no browser/bundler build yet.** This package is
+built with `wasm-pack --target nodejs` (CommonJS, loads the `.wasm` via
+`fs.readFileSync` at require time). It will not work as-is in a browser
+or with a bundler expecting `--target web`/`--target bundler` output
+(`fetch`-based instantiation, ESM). That's a separate build target to
+add later, not a difference in the Rust source.
+
+## Four things that will bite you
+
+**(a) Feed raw bytes — never a host-pre-decoded string.** Always pass the
+file's original `Buffer`/`Uint8Array` to `parse`/`detect`, not a string
+you already decoded (e.g. `fs.readFileSync(path, "utf-8")` then
+re-encoded). `batis-xml` detects the encoding itself: a BOM sniff first
+(UTF-16 LE/BE select directly; a UTF-8 BOM is stripped), then a UTF-8
+attempt, then the XML declaration's own `encoding=` label
+(BOM/declared-label-driven, covering every WHATWG encoding via
+`encoding_rs` — Shift_JIS, GB18030, Big5, UTF-16, …), then an EUC-KR
+heuristic for declaration-less legacy files; anything else decodes
+lossily with a diagnostic. `result.encoding` reports which of these
+actually won (see (b)). Feeding it bytes that already went through a host
+UTF-8 decoder defeats all of that, since a genuinely non-UTF-8 file would
+already have been mangled (replacement characters) before `batis-xml`
+ever sees it. Read files as bytes and stay in bytes until you call in.
+
+**(b) Spans are byte offsets into the UTF-8 text `batis-xml` itself
+decoded — never JS string indices, and never the *original* file's raw
+bytes for anything but a UTF-8 source.** Every `ByteSpan { start, end }`
+in the JSON indexes into the UTF-8 bytes of the *decoded* text (see
+`ByteSpan`'s own doc in `schema.d.ts`), while a JS string is indexed by
+UTF-16 code units — these diverge the moment a multi-byte character
+appears before the offset you care about. Worse, for anything decoded
+from a non-UTF-8 encoding, the original file's raw bytes aren't even the
+same *length* as the UTF-8 re-encoding the spans are offsets into — do
+not slice the original `Buffer`/`Uint8Array` directly with these offsets.
+`result.encoding` (the WHATWG name `TextDecoder` accepts directly) is
+what makes this reproducible:
+
+```js
+// bytes is the same Buffer/Uint8Array you fed to parse()
+const decodedText = new TextDecoder(result.encoding).decode(bytes);
+const utf8Bytes = new TextEncoder().encode(decodedText); // byte-identical to batis-xml's own internal String
+const text = new TextDecoder("utf-8").decode(
+  utf8Bytes.subarray(span.start, span.end)
+);
+```
+
+If the input was plain UTF-8, `bytes` and `utf8Bytes` are already
+byte-identical (decoding then re-encoding UTF-8 is a no-op), so slicing
+`bytes` directly happens to work in that one case — but relying on that
+silently breaks the moment a file turns out to be Shift_JIS/EUC-KR/
+UTF-16/etc., which is exactly the failure mode `result.encoding` exists
+to prevent. Always go through the `TextDecoder`/`TextEncoder` round trip
+above regardless of what encoding you expect.
+
+**(c) Build qualified names as `ns.id`, suffixed `@databaseId` when
+present.** `Statement.database_id` is deliberately *not* folded into
+`id` — that's the consumer's call. If you build a "qualified name" key
+(e.g. `namespace.statementId`) and drop `database_id`, two dual-dialect
+variants of the same statement (`databaseId="oracle"` / `"mysql"`)
+collide onto one key. Recommended recipe:
+
+```ts
+// Both mapper.namespace (Option<Spanned<String>> — a namespace-less iBatis
+// sqlMap has none) and statement.id (Option<..>, absent + a
+// MissingStatementId diagnostic when the tag is missing an id attribute)
+// are nullable in the schema -- `statement.id` in particular is easy to
+// miss, since template literals silently accept `undefined` (stringified
+// as "undefined") instead of a type error, so `tsc --strict` alone won't
+// catch skipping this guard.
+if (statement.id == null) {
+  // No stable identifier for this statement at all -- MissingStatementId
+  // is already in result.diagnostics; skip it rather than fabricate a key.
+} else {
+  const namespace = mapper.namespace?.value ?? "";
+  const qualifiedName = statement.database_id
+    ? `${namespace}.${statement.id.value}@${statement.database_id.value}`
+    : `${namespace}.${statement.id.value}`;
+}
+```
+
+**(d) `<include>` expands *before* `<where>`/`<set>`/`<trim>` in MyBatis/
+iBatis — this crate doesn't expand it at all.** `IncludeRef` gives you the
+raw `refid` plus a best-effort `IncludeTarget`; substituting the
+referenced `<sql>` fragment's text in is on you.
+
+The marker's textual form is a **stable v1 contract**: it renders in the
+flattened SQL as the literal, fixed-prefix comment token
+`` /* batis:include(<raw>) */ ``, where `<raw>` is `IncludeRef.raw`
+verbatim (any literal `*/` inside it is replaced with `*_/` so it can't
+terminate the comment early) — the same whether the target is `Local`,
+`Qualified` (rendered with its original dot, e.g. `otherNs.frag`), or
+`Dynamic` (the unresolved `${...}` text rendered as-is). Since the prefix
+is fixed, `sqlText.indexOf("/* batis:include(")` (or a global regex) finds
+every token directly; match each one to its `Statement.includes`/
+`SqlFragment.includes` entry by reconstructing the exact token string
+from that entry's `raw` field:
+
+```js
+for (const inc of statement.includes) {
+  const token = `/* batis:include(${inc.value.raw.replaceAll("*/", "*_/")}) */`;
+  sqlText = sqlText.replace(token, resolveFragmentText(inc.value)); // your own lookup
+}
+```
+
+If the fragment you're substituting is itself multi-variant
+(`sql.variants` on the fragment's own flattened output has more than one
+entry), there's no single deterministic substitution — pick the
+fragment's variant whose `conditions` match the same parameter state as
+the *enclosing* statement's variant you're substituting into, not
+`variants[0]` arbitrarily.
+
+If you splice fragment text in *after* flattening (rather than before,
+like the real engines do), redo the wrapper's own cleanup against that
+substituted text: re-apply the leading-AND/OR strip or trailing-comma
+strip when the include token was first/last inside the wrapper, and
+treat a wrapper whose only content is an include token as conditional
+(the fragment might expand to nothing). `result.diagnostics` carries
+`include_at_wrapper_boundary` for every spot this applies to — each
+diagnostic's `span` is the same original-XML span as the matching
+`includes[]` entry's `span` (not a position in the flattened text) — see
+the core crate's README ("Include expansion order") for the full
+contract. As with any diagnostic, match on `code`
+(`"include_at_wrapper_boundary"`), never on `message` text — messages
+may be reworded between versions without that being a breaking change.
+
+One more ordering guarantee worth relying on: `result.mapper.statements`
+(and `fragments`/`result_maps`) preserve the source document's order.
+
+## One more thing
+
+`IncludeRef.raw` (the raw, unparsed `refid` text) is kept even when
+`IncludeTarget` is `Dynamic` (a `${}`-driven refid `batis-xml` can't
+resolve statically) — inspect it for a static prefix or pattern to
+attempt your own best-effort match, rather than treating every dynamic
+include as a dead end.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,36 @@
+This package's compiled WebAssembly binary statically links the Rust crate
+`encoding_rs` (https://docs.rs/encoding_rs), used for encoding detection and
+decoding. `encoding_rs` is itself dual-licensed under Apache-2.0 OR MIT (see
+LICENSE-APACHE / LICENSE-MIT in this package), but it also embeds encoding
+index/conversion data owned by WHATWG (Apple, Google, Mozilla, Microsoft)
+that is licensed separately under BSD-3-Clause. That notice is reproduced
+below, unmodified, per its own terms.
+
+-------------------------------------------------------------------------
+
+Copyright © WHATWG (Apple, Google, Mozilla, Microsoft).
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/batis_xml_wasm.d.ts

@@ -0,0 +1,37 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Cheap dialect pre-check (MM-01 logic only, no statement/fragment/
+ * resultMap capture or flattening) -- returns the plain string
+ * (`"mybatis"` / `"ibatis"` / `"unknown"`, matching the schema's enum
+ * spelling), not a JSON-quoted one: unlike `parse`, this returns a single
+ * scalar with no nested model to keep schema-faithful, so there's no
+ * reason to make callers `JSON.parse` it. Guaranteed to agree with
+ * `parse(bytes)`'s `dialect` field (see the core crate's contract test).
+ * Same `Uint8Array`/`Buffer` input validation as `parse` (A16).
+ *
+ * B32 (cold code review, minor): typed as the `Dialect` union
+ * (`unchecked_return_type`) rather than the generic `string` wasm-bindgen
+ * would otherwise infer from `Result<String, _>` -- callers get real
+ * autocomplete/type-narrowing on the three actual values instead of an
+ * unconstrained string.
+ */
+export function detect(input: Uint8Array): "mybatis" | "ibatis" | "unknown";
+
+/**
+ * Parses mapper XML bytes and returns the `ParseResult` (schema v1) as a
+ * JSON string. Never panics: encoding/parse failures already surface as
+ * diagnostics inside the JSON per the core crate's contract, and the
+ * (practically unreachable, since `ParseResult` has no non-string map
+ * keys) serialization failure case falls back to the JSON literal `null`
+ * rather than trapping the wasm instance. Throws a `TypeError` (rejecting
+ * the call, not silently coercing) if `input` isn't a `Uint8Array`/`Buffer`
+ * -- see [`require_bytes`].
+ */
+export function parse(input: Uint8Array): string;
+
+/**
+ * This crate's version, from `Cargo.toml`.
+ */
+export function version(): string;

package/batis_xml_wasm.js

@@ -0,0 +1,325 @@
+/* @ts-self-types="./batis_xml_wasm.d.ts" */
+
+/**
+ * Cheap dialect pre-check (MM-01 logic only, no statement/fragment/
+ * resultMap capture or flattening) -- returns the plain string
+ * (`"mybatis"` / `"ibatis"` / `"unknown"`, matching the schema's enum
+ * spelling), not a JSON-quoted one: unlike `parse`, this returns a single
+ * scalar with no nested model to keep schema-faithful, so there's no
+ * reason to make callers `JSON.parse` it. Guaranteed to agree with
+ * `parse(bytes)`'s `dialect` field (see the core crate's contract test).
+ * Same `Uint8Array`/`Buffer` input validation as `parse` (A16).
+ *
+ * B32 (cold code review, minor): typed as the `Dialect` union
+ * (`unchecked_return_type`) rather than the generic `string` wasm-bindgen
+ * would otherwise infer from `Result<String, _>` -- callers get real
+ * autocomplete/type-narrowing on the three actual values instead of an
+ * unconstrained string.
+ * @param {Uint8Array} input
+ * @returns {"mybatis" | "ibatis" | "unknown"}
+ */
+function detect(input) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ret = wasm.detect(input);
+        var ptr1 = ret[0];
+        var len1 = ret[1];
+        if (ret[3]) {
+            ptr1 = 0; len1 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+exports.detect = detect;
+
+/**
+ * Parses mapper XML bytes and returns the `ParseResult` (schema v1) as a
+ * JSON string. Never panics: encoding/parse failures already surface as
+ * diagnostics inside the JSON per the core crate's contract, and the
+ * (practically unreachable, since `ParseResult` has no non-string map
+ * keys) serialization failure case falls back to the JSON literal `null`
+ * rather than trapping the wasm instance. Throws a `TypeError` (rejecting
+ * the call, not silently coercing) if `input` isn't a `Uint8Array`/`Buffer`
+ * -- see [`require_bytes`].
+ * @param {Uint8Array} input
+ * @returns {string}
+ */
+function parse(input) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ret = wasm.parse(input);
+        var ptr1 = ret[0];
+        var len1 = ret[1];
+        if (ret[3]) {
+            ptr1 = 0; len1 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+exports.parse = parse;
+
+/**
+ * This crate's version, from `Cargo.toml`.
+ * @returns {string}
+ */
+function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.version();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+exports.version = version;
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_boolean_get_fa956cfa2d1bd751: function(arg0) {
+            const v = arg0;
+            const ret = typeof(v) === 'boolean' ? v : undefined;
+            return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
+        },
+        __wbg___wbindgen_is_null_ea9085d691f535d3: function(arg0) {
+            const ret = arg0 === null;
+            return ret;
+        },
+        __wbg___wbindgen_is_object_a27215656b807791: function(arg0) {
+            const val = arg0;
+            const ret = typeof(val) === 'object' && val !== null;
+            return ret;
+        },
+        __wbg___wbindgen_is_undefined_c05833b95a3cf397: function(arg0) {
+            const ret = arg0 === undefined;
+            return ret;
+        },
+        __wbg___wbindgen_number_get_394265ed1e1b84ee: function(arg0, arg1) {
+            const obj = arg1;
+            const ret = typeof(obj) === 'number' ? obj : undefined;
+            getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
+        },
+        __wbg___wbindgen_string_get_b0ca35b86a603356: function(arg0, arg1) {
+            const obj = arg1;
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_344f42d3211c4765: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_byteLength_41862ca4020b9c43: function(arg0) {
+            const ret = arg0.byteLength;
+            return ret;
+        },
+        __wbg_construct_4e1a16de27aea5b9: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.construct(arg0, arg1);
+            return ret;
+        }, arguments); },
+        __wbg_get_78f252d074a84d0b: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(arg0, arg1);
+            return ret;
+        }, arguments); },
+        __wbg_instanceof_Array_de0fa65266a8c7c0: function(arg0) {
+            let result;
+            try {
+                result = arg0 instanceof Array;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
+        __wbg_instanceof_Uint8Array_309b927aaf7a3fc7: function(arg0) {
+            let result;
+            try {
+                result = arg0 instanceof Uint8Array;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
+        __wbg_length_1f0964f4a5e2c6d8: function(arg0) {
+            const ret = arg0.length;
+            return ret;
+        },
+        __wbg_new_5e245ef5857d7f33: function(arg0, arg1) {
+            const ret = new TypeError(getStringFromWasm0(arg0, arg1));
+            return ret;
+        },
+        __wbg_of_85f52f8b6491a7ca: function(arg0) {
+            const ret = Array.of(arg0);
+            return ret;
+        },
+        __wbg_prototypesetcall_4770620bbe4688a0: function(arg0, arg1, arg2) {
+            Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
+        },
+        __wbg_static_accessor_GLOBAL_4ef717fb391d88b7: function() {
+            const ret = typeof global === 'undefined' ? null : global;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_GLOBAL_THIS_8d1badc68b5a74f4: function() {
+            const ret = typeof globalThis === 'undefined' ? null : globalThis;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_SELF_146583524fe1469b: function() {
+            const ret = typeof self === 'undefined' ? null : self;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_WINDOW_f2829a2234d7819e: function() {
+            const ret = typeof window === 'undefined' ? null : window;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./batis_xml_wasm_bg.js": import0,
+    };
+}
+
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+const wasmPath = `${__dirname}/batis_xml_wasm_bg.wasm`;
+const wasmBytes = require('fs').readFileSync(wasmPath);
+const wasmModule = new WebAssembly.Module(wasmBytes);
+let wasmInstance = new WebAssembly.Instance(wasmModule, __wbg_get_imports());
+let wasm = wasmInstance.exports;
+wasm.__wbindgen_start();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "batis-xml",
+  "collaborators": [
+    "ESPINS <dlwlalsggg@gmail.com>"
+  ],
+  "description": "WebAssembly bindings for batis-xml (MyBatis/iBatis mapper XML parser)",
+  "version": "0.1.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/espins-labs/batis-xml.git"
+  },
+  "files": [
+    "batis_xml_wasm_bg.wasm",
+    "batis_xml_wasm.js",
+    "batis_xml_wasm.d.ts",
+    "schema.d.ts",
+    "LICENSE-MIT",
+    "LICENSE-APACHE",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "main": "batis_xml_wasm.js",
+  "types": "batis_xml_wasm.d.ts",
+  "keywords": [
+    "mybatis",
+    "ibatis",
+    "wasm",
+    "parser"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./batis_xml_wasm.d.ts",
+      "default": "./batis_xml_wasm.js"
+    },
+    "./schema": {
+      "types": "./schema.d.ts"
+    }
+  }
+}

package/schema.d.ts

@@ -0,0 +1,320 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+/**
+ * Additions only; removal/renaming is breaking. `#[non_exhaustive]` because new codes may appear within v1 itself (see `schema/README.md`) -- an exhaustive `match` outside this crate must add a wildcard arm, which is exactly the forward-compat behavior consumers need (an unrecognized code is not an error). `Other` covers the equivalent case for *deserialization* (this build reading JSON produced by a newer version).
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "DiagCode".
+ */
+export type DiagCode =
+  | (
+      | "encoding_undetectable"
+      | "encoding_mismatch"
+      | "unclosed_tag"
+      | "duplicate_statement_id"
+      | "missing_statement_id"
+      | "branch_limit_exceeded"
+      | "unknown_element"
+    )
+  | "dangling_refid"
+  | "oversize_input"
+  | "duplicate_attribute"
+  | "invalid_entity"
+  | "unterminated_placeholder"
+  | "nesting_limit_exceeded"
+  | "include_at_wrapper_boundary"
+  | "other";
+/**
+ * Closed set: an exhaustive `match` is a consumer feature (there's no forward-compat concern the way there is for `DiagCode`/`SqlText`, since `Unknown` already covers "neither of the two known dialects"). Adding a third dialect would be a v2.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "Dialect".
+ */
+export type Dialect = "mybatis" | "ibatis" | "unknown";
+/**
+ * Closed set: an exhaustive `match` is a consumer feature. `Dynamic` already covers "can't be resolved statically" -- there's no third kind of refid target. Adding a variant here would be a v2.
+ *
+ * ## Expansion-order contract
+ *
+ * This crate never substitutes the referenced `<sql>` fragment's text in place of the `<include>` token -- resolving `IncludeTarget` to actual SQL and splicing it in is entirely the consumer's job. MyBatis/iBatis themselves expand `<include>` *before* evaluating `<where>`/`<set>`/ `<trim>` dynamic semantics, so a wrapper's leading-AND/OR strip or trailing-comma strip sees the fragment's real, substituted text. Flattening here with the token still in place means a consumer substituting fragment text in afterward must, at minimum:
+ *
+ * - re-apply the wrapper's leading-AND/OR / trailing-comma cleanup to the substituted text when the include token was first/last inside a `<where>`/`<set>`/`<trim>`, and - treat a wrapper whose only content is an include token as conditional (the fragment may expand to nothing).
+ *
+ * `DiagCode::IncludeAtWrapperBoundary` flags exactly the spots this applies to -- see the README's "Include expansion order" section for the full write-up.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "IncludeTarget".
+ */
+export type IncludeTarget =
+  | {
+      local: string;
+    }
+  | {
+      qualified: {
+        id: string;
+        ns: string;
+        [k: string]: unknown;
+      };
+    }
+  | "dynamic";
+/**
+ * Result of dynamic-tag flattening (MM-06). Branch combination cap N=32 — total candidates per statement, computed as the cartesian product of tag branches.
+ *
+ * `#[non_exhaustive]`: a third fallback representation is plausible future work, and consumers matching exhaustively today must not break at compile time if one's added.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "SqlText".
+ */
+export type SqlText =
+  | {
+      variants: SqlVariant[];
+    }
+  | {
+      union: {
+        /**
+         * A **lower bound**, not necessarily the exact branch count: flattening bails out of cartesian expansion as soon as it's certain the total exceeds the cap, without finishing the (possibly much larger) exact count. Treat this as "at least this many, over the cap" rather than a precise total.
+         */
+        branch_count: number;
+        text: SqlString;
+        [k: string]: unknown;
+      };
+    };
+/**
+ * Closed set: an exhaustive `match` is a consumer feature. `Generic` already covers "some other statement-like tag with no CRUD-verb equivalent" -- a new MyBatis/iBatis statement-like tag would be recognized by adding to `Generic`'s callers, not by growing this enum. Adding a variant here would be a v2.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "StatementKind".
+ */
+export type StatementKind = ("select" | "insert" | "update" | "delete" | "procedure") | "generic";
+
+export interface ParseResult {
+  /**
+   * Parsing never fails — every anomaly accumulates here.
+   */
+  diagnostics: Diagnostic[];
+  dialect: Dialect;
+  /**
+   * The WHATWG name of the encoding the detection chain actually decoded the input with (`"UTF-8"`, `"EUC-KR"`, `"Shift_JIS"`, `"UTF-16LE"`, ...; `encoding_rs::Encoding::name()`'s own values, which are WHATWG-standard labels). `None` only when no decode was attempted at all (the raw-byte oversize cap rejected the input before `encoding.rs` ever ran) -- `parse` (already-decoded `&str` input) always reports `"UTF-8"`, since that's the one encoding a Rust `&str` can ever be.
+   *
+   * This is what makes the [`ByteSpan`] re-encoding caveat actionable: every span in this result is a byte offset into the UTF-8 text *after* decoding, so a consumer working with the **original** input bytes must decode them the same way first -- `new TextDecoder(result.encoding)` (Node.js/browsers both accept WHATWG labels directly), re-encode that decoded text to UTF-8, and slice spans against *that* buffer, not the original input bytes directly (see `wasm/README.md` for a worked recipe).
+   *
+   * BOM handling: for a document that opened with a byte-order mark, the mark is consumed during decoding and never appears in the decoded text -- spans are relative to the BOM-stripped content, same as every other span in this crate (offsets into what this crate's own decoding produced, not the original file's raw byte layout). A consumer re-decoding the original file with `TextDecoder` gets BOM-stripping for free (that's standard `TextDecoder` behavior for UTF-8/UTF-16 with a matching BOM), so no extra adjustment is needed on the consumer's side either.
+   */
+  encoding?: string | null;
+  /**
+   * `None` when the root element is not a mapper/sqlMap (reason is reported as a diagnostic).
+   */
+  mapper?: Mapper | null;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "Diagnostic".
+ */
+export interface Diagnostic {
+  code: DiagCode;
+  message: string;
+  span?: ByteSpan | null;
+  [k: string]: unknown;
+}
+/**
+ * Half-open range `[start, end)`: byte offsets into the UTF-8 text as decoded by this crate (identical to raw input bytes for UTF-8 sources; see the caveat below for re-encoded documents).
+ *
+ * Caveat: this holds exactly for UTF-8 input, which decoding leaves byte-for-byte unchanged. For documents decoded from any other encoding (EUC-KR, Shift_JIS, GB18030, UTF-16, ... -- see `encoding.rs`, which supports every WHATWG encoding via a BOM/declared-label-driven chain, not just EUC-KR), decoding to UTF-8 changes byte *widths* per character, so spans on such documents are offsets into the re-encoded UTF-8 string, not the original raw bytes. This applies uniformly to every re-encoded document, not just Korean legacy files. Consumers reading spans back against a source file must decode that source the same way this crate did before slicing.
+ *
+ * A leading byte-order mark is never part of this text either way: a BOM is consumed during decoding for [`crate::parse_bytes`] (see [`ParseResult::encoding`]'s doc comment) and stripped from the input string itself for [`crate::parse`] (a caller can hand it an already-decoded string that still carries a BOM, e.g. read from a file without stripping it first) -- both entry points agree that every span is relative to the BOM-stripped content.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "ByteSpan".
+ */
+export interface ByteSpan {
+  end: number;
+  start: number;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "Mapper".
+ */
+export interface Mapper {
+  fragments: SqlFragment[];
+  /**
+   * Usually `None` for iBatis sqlMaps (observed in the wild: the prefix lives inside the statement id itself, e.g. `WidgetDAO.getWidget`).
+   */
+  namespace?: SpannedFor_String | null;
+  result_maps: ResultMap[];
+  statements: Statement[];
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "SqlFragment".
+ */
+export interface SqlFragment {
+  id: SpannedFor_String;
+  /**
+   * Nested includes inside the fragment (MM-04).
+   */
+  includes: SpannedFor_IncludeRef[];
+  /**
+   * Full original extent: opening-tag start → subtree end.
+   */
+  span: ByteSpan;
+  sql: SqlText;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "Spanned_for_String".
+ */
+export interface SpannedFor_String {
+  span: ByteSpan;
+  value: string;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "Spanned_for_IncludeRef".
+ */
+export interface SpannedFor_IncludeRef {
+  span: ByteSpan;
+  value: IncludeRef;
+  [k: string]: unknown;
+}
+/**
+ * The include-token textual contract -- a stable part of the v1 output.
+ *
+ * Every `<include refid="...">` marker renders into the flattened [`SqlText`] as a SQL block comment: an opening `/`+`*`, the literal text `batis:include(`, this struct's own `raw` field, a closing `)`, then the closing `*`+`/`. `raw` is rendered verbatim -- the unparsed `refid` attribute value -- **except** any literal `*` immediately followed by `/` inside it is rewritten to `*` + `_` + `/`, so the token can never terminate its own enclosing comment early (a `refid` is untrusted XML attribute content, not something this crate controls the shape of). This holds regardless of `target`'s classification: `Local("frag")` renders the comment around `frag` verbatim; `Qualified { ns: "otherNs", id: "frag" }` renders the *original, still-dotted* text `otherNs.frag` (`raw` is the whole unparsed attribute value; `ns`/`id` are just it split on the last dot for convenience, not a separate rendering); `Dynamic` renders the literal, unresolved `${...}` text as-is.
+ *
+ * **Locating tokens**: since the token's opening (`/`+`*` followed by the literal text `batis:include(`) is a fixed prefix, a plain substring search over the flattened SQL text finds every token directly -- no need to reconstruct it from `raw` first. Each token's position correlates 1:1 with one entry in the owning [`Statement::includes`]/[`SqlFragment::includes`] list: match by `Spanned::span`, which is the *original XML* span of the `<include>` element (not a position in the flattened text) -- the same span a [`DiagCode::IncludeAtWrapperBoundary`] diagnostic reports when this token sits at a `<where>`/`<set>`/`<trim>` boundary (see that variant's own doc comment, and the README's "Include expansion order" section, for the substitution contract itself).
+ *
+ * **Substituting a fragment with multiple variants**: a referenced `<sql>` fragment is itself flattened to a [`SqlText`], which may be `Variants` (several condition-gated alternatives) rather than one fixed string. There is no single deterministic substitution in that case -- the fragment's *own* active variant depends on the same runtime parameter state as the enclosing statement's variant does, so a consumer substituting fragment text into one variant of the parent statement must pick the matching variant of the fragment (by `conditions`), not an arbitrary one (e.g. `variants[0]`).
+ *
+ * **Document order**: [`Mapper::statements`] (and `fragments`/ `result_maps`) preserve source document order -- safe to assume when resolving forward/backward references across statements in one file.
+ *
+ * **Diagnostic messages are not a stable matching surface.** `message` strings may be reworded between versions without that being a breaking change; match on [`Diagnostic::code`] instead.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "IncludeRef".
+ */
+export interface IncludeRef {
+  raw: string;
+  target: IncludeTarget;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "SqlVariant".
+ */
+export interface SqlVariant {
+  /**
+   * The `test` expressions (verbatim) that activate this variant -- positive-only, and not a full boolean formula.
+   *
+   * Only the `test` conditions of `<if>`/dynamic tags whose branch is actually *taken* in this variant's path through the tag tree are recorded here, in document order. An `<if>`'s *not-taken* path contributes an alternative with `conditions: []` (empty) -- which is indistinguishable, at the type level, from a statement that had no `<if>` at all. This is by design (recording "this condition was false" would require inventing a negated-expression representation this crate doesn't have a use for elsewhere), but it means an empty `conditions` list is not itself proof that a variant is unconditional -- a consumer that needs that distinction has to correlate against the source XML's own dynamic-tag structure.
+   *
+   * `SqlText::Variants` as a whole lists *candidate* SQL shapes, not a runtime guarantee: this crate has no visibility into actual parameter values, so it cannot say which variant (if any single one) will execute for a given call -- only that these are the shapes the dynamic-tag tree can produce, gated by the conditions listed here.
+   */
+  conditions: string[];
+  text: SqlString;
+  [k: string]: unknown;
+}
+/**
+ * Flattened SQL text plus a mapping back to the source.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "SqlString".
+ */
+export interface SqlString {
+  /**
+   * (synthetic-text offset, original byte offset) segment-start pairs.
+   *
+   * Only the first column -- the synthetic-text offset (position in `text` above) -- is strictly increasing (B45, cold code review): each entry marks where a new mapped segment starts in the flattened output, so later entries always point further into `text` than earlier ones. The second column -- the original byte offset into the source document -- has no such guarantee, and legitimately repeats or goes backwards at synthetic tokens. Wrapper-added text (a `<trim>`/`<where>`/`<set>`/`<foreach>`'s `prefix`/`open`/`close`/`separator` etc.) has no original bytes of its own, so its span_map entry reuses the wrapper tag's own span start -- for *every* synthetic token the wrapper contributes, including a trailing `close`. E.g. `<foreach open="(" close=")">` around `#{id}` flattens to `"(?)"` with `span_map == [(0, wrapper_start), (1, <raw offset of #{id}>), (2, wrapper_start)]` -- the raw column rises across the body then drops back to `wrapper_start` for the closing `)`, which sits earlier in the source than the body it follows in `text`. Consumers must sort/dedupe on the first column only; the second is not monotonic and must not be assumed so.
+   */
+  span_map: [number, number][];
+  /**
+   * Placeholders already normalized: `#{..}` → `?`, `${..}` → `__BATIS_DYN__`.
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "ResultMap".
+ */
+export interface ResultMap {
+  extends?: SpannedFor_String | null;
+  id: SpannedFor_String;
+  mappings: ColumnMapping[];
+  /**
+   * Full original extent: opening-tag start → subtree end.
+   */
+  span: ByteSpan;
+  type_ref?: SpannedFor_ClassRef | null;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "ColumnMapping".
+ */
+export interface ColumnMapping {
+  column?: string | null;
+  property?: string | null;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "Spanned_for_ClassRef".
+ */
+export interface SpannedFor_ClassRef {
+  span: ByteSpan;
+  value: ClassRef;
+  [k: string]: unknown;
+}
+/**
+ * Alias resolution is the consumer's job — only the raw text is kept.
+ *
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "ClassRef".
+ */
+export interface ClassRef {
+  raw: string;
+  [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `ParseResult`'s JSON-Schema
+ * via the `definition` "Statement".
+ */
+export interface Statement {
+  /**
+   * MyBatis per-vendor branching (`databaseId="oracle"` etc.) — `None` when neither this statement nor (for a `<selectKey>`-synthesized statement) its parent declares one. Distinguishes otherwise duplicate ids (MM-03).
+   *
+   * Inheritance rule (A20/A22, cold code review): a `<selectKey>` child statement (synthesized as `"{parent_id}!selectKey"`, see `id`) reads its *own* `databaseId` attribute first; only when it has none does it inherit the parent statement's `databaseId`. An explicit `databaseId` on the `<selectKey>` itself always wins.
+   *
+   * When inherited, `span` points at the **parent's** `databaseId` attribute, not anywhere inside this child statement's own `span` -- the parent's attribute is textually outside the child's subtree (a `<selectKey>` never contains its enclosing statement's opening tag). This is the one case where a `Spanned` value's `span` is legitimately outside the `Statement` it's attached to; every other `Spanned`/`ByteSpan` field on `Statement` points within `span`.
+   */
+  database_id?: SpannedFor_String | null;
+  /**
+   * `None` when missing, plus a `MissingStatementId` diagnostic. Synthesized ids are never invented.
+   */
+  id?: SpannedFor_String | null;
+  includes: SpannedFor_IncludeRef[];
+  kind: StatementKind;
+  param_class?: SpannedFor_ClassRef | null;
+  /**
+   * Expression paths collected from `#{a.b}` / `${c}` (MM-07).
+   */
+  property_paths: SpannedFor_String[];
+  result_class?: SpannedFor_ClassRef | null;
+  result_map_ref?: SpannedFor_String | null;
+  /**
+   * Full original extent of the statement: opening-tag start → subtree end (i.e. past its closing tag, or its own end for a self-closed element).
+   */
+  span: ByteSpan;
+  sql: SqlText;
+  [k: string]: unknown;
+}