@honua/app-platform 0.0.20-alpha.0

package/core/wfs-filter.js

@@ -0,0 +1,634 @@
+/**
+ * FES 2.0 Filter Encoding emitter for the WFS adapter. Two responsibilities:
+ *
+ * - Compile the canonical `Query.where` SQL-92-ish expression into a small
+ *   FES AST. The supported subset is documented in `docs/wfs.md` —
+ *   comparison operators, `IN`, `BETWEEN`, `LIKE`, `IS NULL`, boolean
+ *   combinators, parenthesization, and string / number literals. Anything
+ *   richer (subqueries, function calls, vendor extensions) yields the
+ *   sentinel `"unsupported"` so the caller throws
+ *   `HonuaCapabilityNotSupportedError("query")` rather than ship a
+ *   silent partial filter.
+ *
+ * - Translate `Query.spatialFilter` into a spatial FES predicate. Only the
+ *   simple geometries the canonical surface emits are supported — envelope,
+ *   point, polygon, polyline. Curves and surfaces are out of scope; callers
+ *   that need them reach the wire through `Source.protocol("wfs")`.
+ *
+ * The emitter never reaches `fetch`; it returns plain strings the adapter
+ * splices into the URL (KVP `filter=`) or the POST body (`<fes:Filter>`).
+ *
+ * @module
+ */
+/**
+ * Sentinel used by the `where` compiler when the input contains a construct
+ * the FES emitter does not know how to translate. Callers should treat this
+ * as "fail the query" rather than "emit a partial filter".
+ */
+export const UNSUPPORTED_FES = "unsupported";
+/**
+ * Compile a `Query.where` SQL-92 string into FES AST. Returns
+ * `UNSUPPORTED_FES` for inputs the emitter cannot translate; the adapter
+ * promotes this to `HonuaCapabilityNotSupportedError("query")`.
+ */
+export function compileWhere(input) {
+    if (input === undefined)
+        return { kind: "and", operands: [] };
+    const trimmed = input.trim();
+    if (trimmed.length === 0 || trimmed === "1=1")
+        return { kind: "and", operands: [] };
+    const tokens = tokenize(trimmed);
+    if (!tokens)
+        return UNSUPPORTED_FES;
+    const parser = new Parser(tokens);
+    try {
+        const node = parser.parseExpression();
+        if (!parser.atEnd())
+            return UNSUPPORTED_FES;
+        return node;
+    }
+    catch {
+        return UNSUPPORTED_FES;
+    }
+}
+/**
+ * Compile the canonical `SpatialFilter` (Esri-flavored) into the FES spatial
+ * leaf the adapter splices into the request. Default geometry property
+ * name is `the_geom`; callers may override (some servers use `geometry`,
+ * `shape`, etc.).
+ */
+export function compileSpatialFilter(filter, options) {
+    const property = options.geometryProperty;
+    const srsName = options.srsName;
+    const op = mapSpatialRel(filter.spatialRel);
+    if (filter.geometryType === "esriGeometryEnvelope") {
+        const env = filter.geometry;
+        if (typeof env.xmin !== "number" ||
+            typeof env.ymin !== "number" ||
+            typeof env.xmax !== "number" ||
+            typeof env.ymax !== "number") {
+            return UNSUPPORTED_FES;
+        }
+        // <fes:BBOX> is envelope-intersects only. For any other relation the
+        // adapter must lower the envelope to a polygon and emit the requested
+        // FES spatial op explicitly so non-intersects relations preserve their
+        // semantics.
+        if (op === "Intersects") {
+            const envelope = {
+                xmin: env.xmin,
+                ymin: env.ymin,
+                xmax: env.xmax,
+                ymax: env.ymax,
+            };
+            if (srsName)
+                envelope.srsName = srsName;
+            return { kind: "bbox", property, envelope };
+        }
+        if (!op)
+            return UNSUPPORTED_FES;
+        const gml = envelopeToPolygonGml(env.xmin, env.ymin, env.xmax, env.ymax, srsName);
+        return { kind: "spatial", op, property, gml };
+    }
+    if (!op)
+        return UNSUPPORTED_FES;
+    const gml = geometryToGml(filter.geometry, filter.geometryType, srsName);
+    if (gml === undefined)
+        return UNSUPPORTED_FES;
+    return { kind: "spatial", op, property, gml };
+}
+function envelopeToPolygonGml(xmin, ymin, xmax, ymax, srsName) {
+    const srsAttr = srsName ? ` srsName=${attr(srsName)}` : "";
+    const latLon = srsAxisIsLatLon(srsName);
+    const c = (x, y) => formatCoord(x, y, latLon);
+    const ring = `${c(xmin, ymin)} ${c(xmax, ymin)} ${c(xmax, ymax)} ${c(xmin, ymax)} ${c(xmin, ymin)}`;
+    return `<gml:Polygon${srsAttr}><gml:exterior><gml:LinearRing><gml:posList>${ring}</gml:posList></gml:LinearRing></gml:exterior></gml:Polygon>`;
+}
+/**
+ * Well-known geographic (latitude/longitude) EPSG codes. In URN
+ * (`urn:ogc:def:crs:EPSG::4326`) or OGC-HTTP
+ * (`http://www.opengis.net/def/crs/EPSG/0/4326`) form, WFS 2.0 / GML 3.2 require
+ * authority axis order — latitude,longitude — for these CRSes, whereas the
+ * legacy short `EPSG:4326` form and `CRS84` stay longitude,latitude. Projected
+ * CRSes (easting,northing) already match the canonical x,y order, so they are
+ * intentionally excluded.
+ */
+const LATLON_GEOGRAPHIC_EPSG = new Set([
+    4326, 4979, 4258, 4269, 4267, 4203, 4283, 4759, 4490, 4674, 4617, 4612, 4619, 4668, 4555,
+]);
+/**
+ * Decide whether a `srsName` implies latitude,longitude axis order. Defaults to
+ * longitude,latitude (the canonical x,y order) for the legacy short EPSG form,
+ * CRS84, unknown codes, and an absent srsName — preserving existing behavior and
+ * avoiding regressions for callers that already supply lon,lat-oriented CRSes.
+ */
+function srsAxisIsLatLon(srsName) {
+    if (!srsName)
+        return false;
+    const value = srsName.trim();
+    // CRS84 / CRS:84 are explicitly longitude,latitude regardless of form.
+    if (/(?:^|[:/])CRS:?84$/i.test(value) || /CRS84/i.test(value))
+        return false;
+    // URN form: urn:ogc:def:crs:EPSG::4326 (the version segment may be empty).
+    const urn = value.match(/^urn:[\w-]+:def:crs:EPSG:[^:]*:(\d+)$/i);
+    // OGC HTTP form: http://www.opengis.net/def/crs/EPSG/0/4326
+    const http = value.match(/def\/crs\/EPSG\/[^/]+\/(\d+)$/i);
+    const code = urn?.[1] ?? http?.[1];
+    // The legacy short "EPSG:4326" form keeps GIS-conventional lon,lat order.
+    if (!code)
+        return false;
+    return LATLON_GEOGRAPHIC_EPSG.has(Number(code));
+}
+/** Serialize a coordinate pair honoring the resolved CRS axis order. */
+function formatCoord(x, y, latLon) {
+    return latLon ? `${y} ${x}` : `${x} ${y}`;
+}
+function mapSpatialRel(rel) {
+    switch (rel) {
+        case undefined:
+        case "esriSpatialRelIntersects":
+        case "esriSpatialRelEnvelopeIntersects":
+            return "Intersects";
+        case "esriSpatialRelContains":
+            return "Contains";
+        case "esriSpatialRelWithin":
+            return "Within";
+        case "esriSpatialRelCrosses":
+            return "Crosses";
+        case "esriSpatialRelOverlaps":
+            return "Overlaps";
+        case "esriSpatialRelTouches":
+            return "Touches";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Serialize a list of FES nodes into a single `<fes:Filter>` element. Used
+ * for both the POST GetFeature body and (URL-encoded) the KVP `filter=`
+ * query parameter.
+ *
+ * The FES namespace prefix is always `fes` and is bound on the root
+ * `<fes:Filter>` element so the result is self-contained.
+ */
+export function serializeFes(nodes, options) {
+    const inner = nodes.length === 0
+        ? ""
+        : nodes.length === 1
+            ? serializeNode(nodes[0])
+            : serializeNode({ kind: "and", operands: nodes });
+    const typeNameAttr = options?.typeName ? ` typeNames=${attr(options.typeName)}` : "";
+    return `<fes:Filter xmlns:fes="http://www.opengis.net/fes/2.0" xmlns:gml="http://www.opengis.net/gml/3.2"${typeNameAttr}>${inner}</fes:Filter>`;
+}
+function serializeNode(node) {
+    switch (node.kind) {
+        case "and":
+            if (node.operands.length === 0)
+                return "";
+            if (node.operands.length === 1)
+                return serializeNode(node.operands[0]);
+            return `<fes:And>${node.operands.map(serializeNode).join("")}</fes:And>`;
+        case "or":
+            if (node.operands.length === 1)
+                return serializeNode(node.operands[0]);
+            return `<fes:Or>${node.operands.map(serializeNode).join("")}</fes:Or>`;
+        case "not":
+            return `<fes:Not>${serializeNode(node.operand)}</fes:Not>`;
+        case "compare":
+            return `<fes:${compareOpElement(node.op)}><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference><fes:Literal>${literalText(node.value)}</fes:Literal></fes:${compareOpElement(node.op)}>`;
+        case "between":
+            return `<fes:PropertyIsBetween><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference><fes:LowerBoundary><fes:Literal>${literalText(node.lower)}</fes:Literal></fes:LowerBoundary><fes:UpperBoundary><fes:Literal>${literalText(node.upper)}</fes:Literal></fes:UpperBoundary></fes:PropertyIsBetween>`;
+        case "in": {
+            if (node.values.length === 0)
+                return `<fes:PropertyIsEqualTo><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference><fes:Literal>${literalText({ kind: "string", value: "__honua_empty_in__" })}</fes:Literal></fes:PropertyIsEqualTo>`;
+            const parts = node.values.map((v) => `<fes:PropertyIsEqualTo><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference><fes:Literal>${literalText(v)}</fes:Literal></fes:PropertyIsEqualTo>`);
+            if (parts.length === 1)
+                return parts[0];
+            return `<fes:Or>${parts.join("")}</fes:Or>`;
+        }
+        case "like":
+            return `<fes:PropertyIsLike wildCard="%" singleChar="_" escapeChar="\\"><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference><fes:Literal>${escapeXml(node.pattern)}</fes:Literal></fes:PropertyIsLike>`;
+        case "isNull":
+            return `<fes:PropertyIsNull><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference></fes:PropertyIsNull>`;
+        case "spatial":
+            return `<fes:${node.op}><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference>${node.gml}</fes:${node.op}>`;
+        case "bbox":
+            return `<fes:BBOX><fes:ValueReference>${escapeXml(node.property)}</fes:ValueReference>${envelopeGml(node.envelope)}</fes:BBOX>`;
+    }
+}
+function compareOpElement(op) {
+    switch (op) {
+        case "=":
+            return "PropertyIsEqualTo";
+        case "<>":
+            return "PropertyIsNotEqualTo";
+        case "<":
+            return "PropertyIsLessThan";
+        case "<=":
+            return "PropertyIsLessThanOrEqualTo";
+        case ">":
+            return "PropertyIsGreaterThan";
+        case ">=":
+            return "PropertyIsGreaterThanOrEqualTo";
+    }
+}
+function literalText(value) {
+    return value.kind === "number" ? String(value.value) : escapeXml(value.value);
+}
+function escapeXml(input) {
+    return input
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function attr(value) {
+    return `"${value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;")}"`;
+}
+function envelopeGml(env) {
+    const srsAttr = env.srsName ? ` srsName=${attr(env.srsName)}` : "";
+    const latLon = srsAxisIsLatLon(env.srsName);
+    return `<gml:Envelope${srsAttr}><gml:lowerCorner>${formatCoord(env.xmin, env.ymin, latLon)}</gml:lowerCorner><gml:upperCorner>${formatCoord(env.xmax, env.ymax, latLon)}</gml:upperCorner></gml:Envelope>`;
+}
+/**
+ * Translate a GeoJSON-style geometry into a tiny GML 3.2 fragment. Only the
+ * primitive shapes the canonical surface emits are supported (point, line,
+ * polygon). Curves and surfaces return `undefined`; callers promote that to
+ * `UNSUPPORTED_FES`.
+ */
+function geometryToGml(geometry, geometryType, srsName) {
+    const srsAttr = srsName ? ` srsName=${attr(srsName)}` : "";
+    const latLon = srsAxisIsLatLon(srsName);
+    switch (geometryType) {
+        case "esriGeometryPoint": {
+            const x = geometry.x;
+            const y = geometry.y;
+            if (typeof x !== "number" || typeof y !== "number")
+                return undefined;
+            return `<gml:Point${srsAttr}><gml:pos>${formatCoord(x, y, latLon)}</gml:pos></gml:Point>`;
+        }
+        case "esriGeometryPolyline": {
+            const paths = geometry.paths;
+            if (!Array.isArray(paths) || paths.length === 0)
+                return undefined;
+            // Honua emits a single line; downstream curves are out of scope.
+            const path = paths[0];
+            if (!Array.isArray(path))
+                return undefined;
+            const coords = path
+                .map((p) => (Array.isArray(p) ? formatCoord(p[0], p[1], latLon) : ""))
+                .filter(Boolean)
+                .join(" ");
+            if (!coords)
+                return undefined;
+            return `<gml:LineString${srsAttr}><gml:posList>${coords}</gml:posList></gml:LineString>`;
+        }
+        case "esriGeometryPolygon": {
+            const rings = geometry.rings;
+            if (!Array.isArray(rings) || rings.length === 0)
+                return undefined;
+            const exterior = ringToPosList(rings[0], latLon);
+            if (!exterior)
+                return undefined;
+            const interiors = [];
+            for (let i = 1; i < rings.length; i += 1) {
+                const inner = ringToPosList(rings[i], latLon);
+                if (!inner)
+                    return undefined;
+                interiors.push(`<gml:interior><gml:LinearRing><gml:posList>${inner}</gml:posList></gml:LinearRing></gml:interior>`);
+            }
+            return `<gml:Polygon${srsAttr}><gml:exterior><gml:LinearRing><gml:posList>${exterior}</gml:posList></gml:LinearRing></gml:exterior>${interiors.join("")}</gml:Polygon>`;
+        }
+        default:
+            return undefined;
+    }
+}
+function ringToPosList(ring, latLon) {
+    if (!Array.isArray(ring) || ring.length < 3)
+        return undefined;
+    return ring
+        .map((p) => (Array.isArray(p) ? formatCoord(p[0], p[1], latLon) : ""))
+        .filter(Boolean)
+        .join(" ");
+}
+/**
+ * Convert a canonical `CanonicalFeature.geometry` (GeoJSON) into a GML 3.2
+ * fragment for `<wfs:Insert>` / `<wfs:Update>` payloads.
+ */
+export function geoJsonGeometryToGml(geometry, srsName) {
+    if (typeof geometry !== "object" || geometry === null)
+        return undefined;
+    const geom = geometry;
+    const srsAttr = srsName ? ` srsName=${attr(srsName)}` : "";
+    // Honor GML 3.2 axis order for the resolved CRS, mirroring the query-path
+    // emitters: authority (URN/HTTP) forms of geographic CRSes are lat,lon while
+    // the legacy short `EPSG:4326` form and CRS84 stay lon,lat.
+    const latLon = srsAxisIsLatLon(srsName);
+    const c = (p) => formatCoord(p[0], p[1], latLon);
+    switch (geom.type) {
+        case "Point": {
+            const coord = geom.coordinates;
+            if (!Array.isArray(coord) || typeof coord[0] !== "number" || typeof coord[1] !== "number")
+                return undefined;
+            return `<gml:Point${srsAttr}><gml:pos>${c(coord)}</gml:pos></gml:Point>`;
+        }
+        case "LineString": {
+            const coords = geom.coordinates;
+            if (!Array.isArray(coords) || coords.length === 0)
+                return undefined;
+            const posList = coords.map(c).join(" ");
+            return `<gml:LineString${srsAttr}><gml:posList>${posList}</gml:posList></gml:LineString>`;
+        }
+        case "Polygon": {
+            const coords = geom.coordinates;
+            if (!Array.isArray(coords) || coords.length === 0)
+                return undefined;
+            const exterior = coords[0].map(c).join(" ");
+            const interiors = coords
+                .slice(1)
+                .map((ring) => `<gml:interior><gml:LinearRing><gml:posList>${ring.map(c).join(" ")}</gml:posList></gml:LinearRing></gml:interior>`)
+                .join("");
+            return `<gml:Polygon${srsAttr}><gml:exterior><gml:LinearRing><gml:posList>${exterior}</gml:posList></gml:LinearRing></gml:exterior>${interiors}</gml:Polygon>`;
+        }
+        default:
+            return undefined;
+    }
+}
+function tokenize(input) {
+    const tokens = [];
+    const len = input.length;
+    let i = 0;
+    while (i < len) {
+        const ch = input[i];
+        if (/\s/.test(ch)) {
+            i += 1;
+            continue;
+        }
+        if (ch === "(") {
+            tokens.push({ kind: "lparen" });
+            i += 1;
+            continue;
+        }
+        if (ch === ")") {
+            tokens.push({ kind: "rparen" });
+            i += 1;
+            continue;
+        }
+        if (ch === ",") {
+            tokens.push({ kind: "comma" });
+            i += 1;
+            continue;
+        }
+        if (ch === "'") {
+            let j = i + 1;
+            let value = "";
+            while (j < len) {
+                if (input[j] === "'") {
+                    if (input[j + 1] === "'") {
+                        value += "'";
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                value += input[j];
+                j += 1;
+            }
+            if (j >= len)
+                return undefined;
+            tokens.push({ kind: "string", value });
+            i = j + 1;
+            continue;
+        }
+        if (/[0-9]/.test(ch) || (ch === "-" && /[0-9]/.test(input[i + 1] ?? ""))) {
+            let j = i + 1;
+            while (j < len && /[0-9.]/.test(input[j]))
+                j += 1;
+            const numText = input.slice(i, j);
+            const n = Number(numText);
+            if (!Number.isFinite(n))
+                return undefined;
+            tokens.push({ kind: "number", value: n });
+            i = j;
+            continue;
+        }
+        if (ch === "<" || ch === ">") {
+            const next = input[i + 1];
+            if (next === "=" || (ch === "<" && next === ">")) {
+                tokens.push({ kind: "op", value: ch + next });
+                i += 2;
+                continue;
+            }
+            tokens.push({ kind: "op", value: ch });
+            i += 1;
+            continue;
+        }
+        if (ch === "=" || ch === "!") {
+            if (ch === "!" && input[i + 1] === "=") {
+                tokens.push({ kind: "op", value: "<>" });
+                i += 2;
+                continue;
+            }
+            if (ch === "=") {
+                tokens.push({ kind: "op", value: "=" });
+                i += 1;
+                continue;
+            }
+            return undefined;
+        }
+        if (/[A-Za-z_]/.test(ch)) {
+            let j = i + 1;
+            while (j < len && /[A-Za-z0-9_.]/.test(input[j]))
+                j += 1;
+            const value = input.slice(i, j);
+            tokens.push({ kind: "ident", value });
+            i = j;
+            continue;
+        }
+        return undefined;
+    }
+    return tokens;
+}
+class Parser {
+    tokens;
+    pos = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    atEnd() {
+        return this.pos >= this.tokens.length;
+    }
+    parseExpression() {
+        return this.parseOr();
+    }
+    parseOr() {
+        let left = this.parseAnd();
+        while (this.matchKeyword("OR")) {
+            const right = this.parseAnd();
+            left = combine("or", left, right);
+        }
+        return left;
+    }
+    parseAnd() {
+        let left = this.parseNot();
+        while (this.matchKeyword("AND")) {
+            const right = this.parseNot();
+            left = combine("and", left, right);
+        }
+        return left;
+    }
+    parseNot() {
+        if (this.matchKeyword("NOT")) {
+            return { kind: "not", operand: this.parseNot() };
+        }
+        return this.parsePrimary();
+    }
+    parsePrimary() {
+        const token = this.peek();
+        if (!token)
+            throw new Error("unexpected end of expression");
+        if (token.kind === "lparen") {
+            this.pos += 1;
+            const expr = this.parseExpression();
+            this.expect("rparen");
+            return expr;
+        }
+        if (token.kind === "ident") {
+            const property = token.value;
+            this.pos += 1;
+            // IS NULL / IS NOT NULL
+            if (this.matchKeyword("IS")) {
+                const negate = this.matchKeyword("NOT");
+                if (!this.matchKeyword("NULL"))
+                    throw new Error("expected NULL");
+                const node = { kind: "isNull", property };
+                return negate ? { kind: "not", operand: node } : node;
+            }
+            // BETWEEN
+            if (this.matchKeyword("BETWEEN")) {
+                const lower = this.parseLiteral();
+                if (!this.matchKeyword("AND"))
+                    throw new Error("expected AND in BETWEEN");
+                const upper = this.parseLiteral();
+                return { kind: "between", property, lower, upper };
+            }
+            // NOT BETWEEN / NOT IN / NOT LIKE
+            if (this.matchKeyword("NOT")) {
+                if (this.matchKeyword("BETWEEN")) {
+                    const lower = this.parseLiteral();
+                    if (!this.matchKeyword("AND"))
+                        throw new Error("expected AND in BETWEEN");
+                    const upper = this.parseLiteral();
+                    return { kind: "not", operand: { kind: "between", property, lower, upper } };
+                }
+                if (this.matchKeyword("IN")) {
+                    return { kind: "not", operand: this.parseInList(property) };
+                }
+                if (this.matchKeyword("LIKE")) {
+                    const pattern = this.parseStringLiteral();
+                    return { kind: "not", operand: { kind: "like", property, pattern } };
+                }
+                throw new Error("unsupported NOT clause");
+            }
+            // IN
+            if (this.matchKeyword("IN")) {
+                return this.parseInList(property);
+            }
+            // LIKE
+            if (this.matchKeyword("LIKE")) {
+                const pattern = this.parseStringLiteral();
+                return { kind: "like", property, pattern };
+            }
+            // Comparison
+            const opTok = this.peek();
+            if (opTok && opTok.kind === "op") {
+                this.pos += 1;
+                const value = this.parseLiteral();
+                const op = opTok.value;
+                if (op !== "=" && op !== "<>" && op !== "<" && op !== "<=" && op !== ">" && op !== ">=") {
+                    throw new Error(`unsupported operator ${op}`);
+                }
+                return { kind: "compare", op, property, value };
+            }
+            throw new Error(`unexpected token after identifier "${property}"`);
+        }
+        throw new Error(`unexpected token ${token.kind}`);
+    }
+    parseInList(property) {
+        this.expect("lparen");
+        const values = [];
+        while (true) {
+            const tok = this.peek();
+            if (!tok)
+                throw new Error("unterminated IN list");
+            if (tok.kind === "rparen") {
+                this.pos += 1;
+                break;
+            }
+            values.push(this.parseLiteral());
+            const next = this.peek();
+            if (next?.kind === "comma") {
+                this.pos += 1;
+                continue;
+            }
+            if (next?.kind === "rparen") {
+                this.pos += 1;
+                break;
+            }
+            throw new Error("expected , or ) in IN list");
+        }
+        return { kind: "in", property, values };
+    }
+    parseLiteral() {
+        const tok = this.peek();
+        if (!tok)
+            throw new Error("expected literal");
+        if (tok.kind === "string") {
+            this.pos += 1;
+            return { kind: "string", value: tok.value };
+        }
+        if (tok.kind === "number") {
+            this.pos += 1;
+            return { kind: "number", value: tok.value };
+        }
+        throw new Error(`expected literal, got ${tok.kind}`);
+    }
+    parseStringLiteral() {
+        const tok = this.peek();
+        if (!tok || tok.kind !== "string")
+            throw new Error("expected string literal");
+        this.pos += 1;
+        return tok.value;
+    }
+    peek() {
+        return this.tokens[this.pos];
+    }
+    expect(kind) {
+        const tok = this.peek();
+        if (!tok || tok.kind !== kind)
+            throw new Error(`expected ${kind}`);
+        this.pos += 1;
+    }
+    matchKeyword(keyword) {
+        const tok = this.peek();
+        if (tok && tok.kind === "ident" && tok.value.toUpperCase() === keyword) {
+            this.pos += 1;
+            return true;
+        }
+        return false;
+    }
+}
+function combine(kind, left, right) {
+    const merged = [];
+    pushOperand(merged, kind, left);
+    pushOperand(merged, kind, right);
+    return { kind, operands: merged };
+}
+function pushOperand(target, kind, node) {
+    if (node.kind === kind) {
+        for (const op of node.operands)
+            target.push(op);
+        return;
+    }
+    target.push(node);
+}