@query-doctor/core 0.0.3 → 0.0.4

package/dist/sql/database.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export const PostgresVersion = z.string().brand("PostgresVersion");
+/**
+ * Drops a disabled index. Rollsback if it fails for any reason
+ * @returns Did dropping the index succeed?
+ */
+export async function dropIndex(tx, index) {
+    try {
+        await tx.exec(`
+      savepoint idx_drop;
+      drop index if exists ${index} cascade;
+    `);
+        return true;
+    }
+    catch (error) {
+        // no problem if droping the index fails. It should throw an error
+        await tx.exec(`rollback to idx_drop`);
+        return false;
+    }
+}

package/dist/sql/indexes.d.ts

@@ -0,0 +1,8 @@
+import type { IndexedTable } from "../optimizer/statistics.js";
+export declare function isIndexSupported(index: IndexedTable): boolean;
+/**
+ * Doesn't necessarily decide whether the index can be dropped but can be
+ * used to not even try dropping indexes that _definitely_ cannot be dropped
+ */
+export declare function isIndexProbablyDroppable(index: IndexedTable): boolean;
+//# sourceMappingURL=indexes.d.ts.map

package/dist/sql/indexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../../src/sql/indexes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,WAEnD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,YAAY,WAI3D"}

package/dist/sql/indexes.js

@@ -0,0 +1,12 @@
+export function isIndexSupported(index) {
+    return index.index_type === "btree";
+}
+/**
+ * Doesn't necessarily decide whether the index can be dropped but can be
+ * used to not even try dropping indexes that _definitely_ cannot be dropped
+ */
+export function isIndexProbablyDroppable(index) {
+    /* TODO: until we have a better solution, this is the best we have */
+    /* The is_unique check is problematic only if the column is declared as unique */
+    return !index.is_primary && !index.is_unique;
+}

package/dist/sql/nudges.js

@@ -0,0 +1,241 @@
+function is(node, kind) {
+    return kind in node;
+}
+function isANode(node) {
+    if (typeof node !== "object" || node === null) {
+        return false;
+    }
+    const keys = Object.keys(node);
+    return keys.length === 1 && /^[A-Z]/.test(keys[0]);
+}
+/**
+ * Detect nudges for a single node during AST traversal.
+ * Returns an array of nudges found for this node.
+ */
+export function parseNudges(node, stack) {
+    const nudges = [];
+    if (is(node, "A_Star")) {
+        nudges.push({
+            kind: "AVOID_SELECT_STAR",
+            severity: "INFO",
+            message: "Avoid using SELECT *",
+        });
+    }
+    // Detect functions on columns in WHERE clause
+    if (is(node, "FuncCall")) {
+        // Check if we're in a WHERE clause context
+        const inWhereClause = stack.some((item) => item === "whereClause");
+        if (inWhereClause && node.FuncCall.args) {
+            // Check if any function arguments contain column references
+            const hasColumnRef = containsColumnRef(node.FuncCall.args);
+            if (hasColumnRef) {
+                nudges.push({
+                    kind: "AVOID_FUNCTIONS_ON_COLUMNS_IN_WHERE",
+                    severity: "WARNING",
+                    message: "Avoid using functions on columns in WHERE clause",
+                });
+            }
+        }
+    }
+    // Detect unbounded queries (missing WHERE or LIMIT on table queries)
+    if (is(node, "SelectStmt")) {
+        // Only check top-level SELECT statements (not subqueries)
+        const isSubquery = stack.some((item) => item === "RangeSubselect" ||
+            item === "SubLink" ||
+            item === "CommonTableExpr");
+        if (!isSubquery) {
+            const hasFromClause = node.SelectStmt.fromClause && node.SelectStmt.fromClause.length > 0;
+            if (hasFromClause) {
+                // Check if this SELECT queries actual tables (not just subqueries or CTEs)
+                const hasActualTables = node.SelectStmt.fromClause.some((fromItem) => {
+                    return (is(fromItem, "RangeVar") ||
+                        (is(fromItem, "JoinExpr") && hasActualTablesInJoin(fromItem)));
+                });
+                if (hasActualTables) {
+                    // Check for missing WHERE clause
+                    if (!node.SelectStmt.whereClause) {
+                        nudges.push({
+                            kind: "MISSING_WHERE_CLAUSE",
+                            severity: "INFO",
+                            message: "Missing WHERE clause",
+                        });
+                    }
+                    // Check for missing LIMIT clause
+                    if (!node.SelectStmt.limitCount) {
+                        nudges.push({
+                            kind: "MISSING_LIMIT_CLAUSE",
+                            severity: "INFO",
+                            message: "Missing LIMIT clause",
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Detect NULL comparison issues (= NULL instead of IS NULL)
+    if (is(node, "A_Expr")) {
+        const isEqualityOp = node.A_Expr.kind === "AEXPR_OP" &&
+            node.A_Expr.name &&
+            node.A_Expr.name.length > 0 &&
+            is(node.A_Expr.name[0], "String") &&
+            (node.A_Expr.name[0].String.sval === "=" ||
+                node.A_Expr.name[0].String.sval === "!=" ||
+                node.A_Expr.name[0].String.sval === "<>");
+        if (isEqualityOp) {
+            const leftIsNull = isNullConstant(node.A_Expr.lexpr);
+            const rightIsNull = isNullConstant(node.A_Expr.rexpr);
+            if (leftIsNull || rightIsNull) {
+                nudges.push({
+                    kind: "USE_IS_NULL_NOT_EQUALS",
+                    severity: "WARNING",
+                    message: "Use IS NULL instead of = or != or <> for NULL comparisons",
+                });
+            }
+        }
+        // Detect LIKE with leading wildcards
+        const isLikeOp = node.A_Expr.kind === "AEXPR_LIKE" || node.A_Expr.kind === "AEXPR_ILIKE";
+        if (isLikeOp && node.A_Expr.rexpr) {
+            const patternString = getStringConstantValue(node.A_Expr.rexpr);
+            if (patternString && patternString.startsWith("%")) {
+                nudges.push({
+                    kind: "AVOID_LEADING_WILDCARD_LIKE",
+                    severity: "WARNING",
+                    message: "Avoid using LIKE with leading wildcards",
+                });
+            }
+        }
+    }
+    // Detect DISTINCT usage
+    if (is(node, "SelectStmt") && node.SelectStmt.distinctClause) {
+        nudges.push({
+            kind: "AVOID_DISTINCT_WITHOUT_REASON",
+            severity: "WARNING",
+            message: "Avoid using DISTINCT without a reason",
+        });
+    }
+    // Detect cartesian joins (missing JOIN conditions)
+    if (is(node, "JoinExpr")) {
+        // Check if JOIN has no qualification (ON clause)
+        if (!node.JoinExpr.quals) {
+            nudges.push({
+                kind: "MISSING_JOIN_CONDITION",
+                severity: "WARNING",
+                message: "Missing JOIN condition",
+            });
+        }
+    }
+    // Detect multiple tables in FROM without explicit JOINs (old-style cartesian joins)
+    if (is(node, "SelectStmt") &&
+        node.SelectStmt.fromClause &&
+        node.SelectStmt.fromClause.length > 1) {
+        // Check if there are multiple RangeVar (tables) directly in FROM clause
+        const tableCount = node.SelectStmt.fromClause.filter((item) => is(item, "RangeVar")).length;
+        if (tableCount > 1) {
+            nudges.push({
+                kind: "MISSING_JOIN_CONDITION",
+                severity: "WARNING",
+                message: "Missing JOIN condition",
+            });
+        }
+    }
+    // Detect too many OR conditions
+    if (is(node, "BoolExpr") && node.BoolExpr.boolop === "OR_EXPR") {
+        const orCount = countBoolOrConditions(node);
+        if (orCount >= 3) {
+            nudges.push({
+                kind: "CONSIDER_IN_INSTEAD_OF_MANY_ORS",
+                severity: "WARNING",
+                message: "Consider using IN instead of many ORs",
+            });
+        }
+    }
+    return nudges;
+}
+function containsColumnRef(args) {
+    // Recursively check if any argument contains a ColumnRef
+    for (const arg of args) {
+        if (hasColumnRefInNode(arg)) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasColumnRefInNode(node) {
+    if (isANode(node) && is(node, "ColumnRef")) {
+        return true;
+    }
+    if (typeof node !== "object" || node === null) {
+        return false;
+    }
+    if (Array.isArray(node)) {
+        return node.some((item) => hasColumnRefInNode(item));
+    }
+    if (isANode(node)) {
+        const keys = Object.keys(node);
+        // @ts-expect-error | nodes don't allow dynamic access but it's the only way to do it
+        return hasColumnRefInNode(node[keys[0]]);
+    }
+    for (const child of Object.values(node)) {
+        if (hasColumnRefInNode(child)) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasActualTablesInJoin(joinExpr) {
+    // Check left side of join
+    if (joinExpr.JoinExpr.larg && is(joinExpr.JoinExpr.larg, "RangeVar")) {
+        return true;
+    }
+    if (joinExpr.JoinExpr.larg && is(joinExpr.JoinExpr.larg, "JoinExpr")) {
+        if (hasActualTablesInJoin(joinExpr.JoinExpr.larg)) {
+            return true;
+        }
+    }
+    // Check right side of join
+    if (joinExpr.JoinExpr.rarg && is(joinExpr.JoinExpr.rarg, "RangeVar")) {
+        return true;
+    }
+    if (joinExpr.JoinExpr.rarg && is(joinExpr.JoinExpr.rarg, "JoinExpr")) {
+        if (hasActualTablesInJoin(joinExpr.JoinExpr.rarg)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isNullConstant(node) {
+    if (!node || typeof node !== "object") {
+        return false;
+    }
+    if (isANode(node) && is(node, "A_Const")) {
+        // Check if it's a NULL constant
+        return node.A_Const.isnull !== undefined;
+    }
+    return false;
+}
+function getStringConstantValue(node) {
+    if (!node || typeof node !== "object") {
+        return null;
+    }
+    if (isANode(node) && is(node, "A_Const") && node.A_Const.sval) {
+        return node.A_Const.sval.sval || null;
+    }
+    return null;
+}
+function countBoolOrConditions(node) {
+    if (node.BoolExpr.boolop !== "OR_EXPR" || !node.BoolExpr.args) {
+        return 1;
+    }
+    let count = 0;
+    for (const arg of node.BoolExpr.args) {
+        if (isANode(arg) &&
+            is(arg, "BoolExpr") &&
+            arg.BoolExpr.boolop === "OR_EXPR") {
+            count += countBoolOrConditions(arg);
+        }
+        else {
+            count += 1;
+        }
+    }
+    return count;
+}

package/dist/sql/permutations.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=permutations.test.d.ts.map

package/dist/sql/permutations.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permutations.test.d.ts","sourceRoot":"","sources":["../../src/sql/permutations.test.ts"],"names":[],"mappings":""}

package/dist/sql/permutations_test.js

@@ -0,0 +1,53 @@
+import { permuteWithFeedback, PROCEED, SKIP } from "../optimizer/genalgo.js";
+import assert from "node:assert";
+import test from "node:test";
+test("permutations", () => {
+    const fn = permuteWithFeedback([1, 2, 3]);
+    const next1 = fn.next(PROCEED);
+    const next2 = fn.next(PROCEED);
+    const next3 = fn.next(PROCEED);
+    const next4 = fn.next(PROCEED);
+    const next5 = fn.next(PROCEED);
+    const next6 = fn.next(PROCEED);
+    const next7 = fn.next(PROCEED);
+    const next8 = fn.next(PROCEED);
+    const next9 = fn.next(PROCEED);
+    const next10 = fn.next(PROCEED);
+    const next11 = fn.next(PROCEED);
+    const next12 = fn.next(PROCEED);
+    const next13 = fn.next(PROCEED);
+    const next14 = fn.next(PROCEED);
+    const next15 = fn.next(PROCEED);
+    const next16 = fn.next(PROCEED);
+    assert.deepStrictEqual(next1.value, [1]);
+    assert.deepStrictEqual(next2.value, [1, 2]);
+    assert.deepStrictEqual(next3.value, [1, 2, 3]);
+    assert.deepStrictEqual(next4.value, [1, 3]);
+    assert.deepStrictEqual(next5.value, [1, 3, 2]);
+    assert.deepStrictEqual(next6.value, [2]);
+    assert.deepStrictEqual(next7.value, [2, 1]);
+    assert.deepStrictEqual(next8.value, [2, 1, 3]);
+    assert.deepStrictEqual(next9.value, [2, 3]);
+    assert.deepStrictEqual(next10.value, [2, 3, 1]);
+    assert.deepStrictEqual(next11.value, [3]);
+    assert.deepStrictEqual(next12.value, [3, 1]);
+    assert.deepStrictEqual(next13.value, [3, 1, 2]);
+    assert.deepStrictEqual(next14.value, [3, 2]);
+    assert.deepStrictEqual(next15.value, [3, 2, 1]);
+    assert.deepStrictEqual(next16.done, true);
+});
+test("permutations with skip", () => {
+    const fn = permuteWithFeedback([1, 2, 3]);
+    const next1 = fn.next(PROCEED);
+    const next2 = fn.next(SKIP);
+    const next3 = fn.next(PROCEED);
+    const next4 = fn.next(SKIP);
+    const next5 = fn.next(SKIP);
+    const next6 = fn.next(SKIP);
+    assert.deepStrictEqual(next1.value, [1]);
+    assert.deepStrictEqual(next2.value, [2]);
+    assert.deepStrictEqual(next3.value, [2, 1]);
+    assert.deepStrictEqual(next4.value, [2, 3]);
+    assert.deepStrictEqual(next5.value, [3]);
+    assert.deepStrictEqual(next6.done, true);
+});

package/dist/sql/pg-identifier.d.ts

@@ -0,0 +1,9 @@
+export declare class PgIdentifier {
+    private readonly value;
+    private readonly quoted;
+    private constructor();
+    static fromString(identifier: string): PgIdentifier;
+    toString(): string;
+    private static readonly reservedKeywords;
+}
+//# sourceMappingURL=pg-identifier.d.ts.map

package/dist/sql/pg-identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-identifier.d.ts","sourceRoot":"","sources":["../../src/sql/pg-identifier.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFzB,OAAO;IAKP,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY;IAYnD,QAAQ,IAAI,MAAM;IAOlB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CA4GrC;CACJ"}

package/dist/sql/pg-identifier.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pg-identifier.test.d.ts.map

package/dist/sql/pg-identifier.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-identifier.test.d.ts","sourceRoot":"","sources":["../../src/sql/pg-identifier.test.ts"],"names":[],"mappings":""}

package/dist/sql/walker.d.ts

@@ -1,6 +1,6 @@
 import type { Node } from "@pgsql/types";
-import type { DiscoveredColumnReference } from "./analyzer.ts";
-import type { Nudge } from "./nudges.ts";
+import type { DiscoveredColumnReference } from "./analyzer.js";
+import type { Nudge } from "./nudges.js";
 /** Information about tables that appear in the query */
 export type TableMappings = Map<string, ColumnReferencePart>;
 /**

package/dist/sql/walker.js

@@ -0,0 +1,295 @@
+import { deparseSync } from "pgsql-deparser";
+import { parseNudges } from "./nudges.js";
+/**
+ * Walks the AST of a sql query and extracts query metadata.
+ * This pattern is used to segregate the mutable state that's more common for the
+ * AST walking process from the rest of the analyzer.
+ */
+export class Walker {
+    query;
+    tableMappings = new Map();
+    tempTables = new Set();
+    highlights = [];
+    indexRepresentations = new Set();
+    indexesToCheck = [];
+    highlightPositions = new Set();
+    // used for tallying the amount of times we see stuff so
+    // we have a better idea of what to start off the algorithm with
+    seenReferences = new Map();
+    shadowedAliases = [];
+    nudges = [];
+    constructor(query) {
+        this.query = query;
+    }
+    walk(root) {
+        // reset state in case the class instance is reused
+        // reassigning vars here instead of using `map.clear()` to prevent
+        // accidentally mutating existing references
+        this.tableMappings = new Map();
+        this.tempTables = new Set();
+        this.highlights = [];
+        this.indexRepresentations = new Set();
+        this.indexesToCheck = [];
+        this.highlightPositions = new Set();
+        this.seenReferences = new Map();
+        this.shadowedAliases = [];
+        this.nudges = [];
+        Walker.traverse(root, [], (node, stack) => {
+            const nodeNudges = parseNudges(node, stack);
+            this.nudges = [...this.nudges, ...nodeNudges];
+            // comments are not parsed here as they seem to be ignored.
+            //
+            // results cannot be indexed in any way because they alias a CTE
+            // with alias as (select ...)
+            //      ^^^^^
+            if (is(node, "CommonTableExpr")) {
+                if (node.CommonTableExpr.ctename) {
+                    this.tempTables.add(node.CommonTableExpr.ctename);
+                }
+            }
+            // results cannot be indexed in any way because they alias a subquery
+            // select ... from (...) as alias
+            //                          ^^^^^
+            if (is(node, "RangeSubselect")) {
+                if (node.RangeSubselect.alias?.aliasname) {
+                    this.tempTables.add(node.RangeSubselect.alias.aliasname);
+                }
+            }
+            // select ... from (...) where col is null
+            //                                 ^^^^^^^
+            if (is(node, "NullTest")) {
+                if (node.NullTest.arg &&
+                    node.NullTest.nulltesttype &&
+                    is(node.NullTest.arg, "ColumnRef")) {
+                    this.add(node.NullTest.arg, {
+                        where: { nulltest: node.NullTest.nulltesttype },
+                    });
+                }
+            }
+            // can be indexed as the alias refers to a regular table
+            // but the alias has to be mapped to the original table name
+            // select ... from table as alias
+            //                          ^^^^^
+            if (is(node, "RangeVar") && node.RangeVar.relname) {
+                this.tableMappings.set(node.RangeVar.relname, {
+                    text: node.RangeVar.relname,
+                    start: node.RangeVar.location,
+                    quoted: false,
+                });
+                // In theory we can't blindly map aliases to table names
+                // it's possible that two aliases point to different tables
+                // which postgres allows but is tricky to determine by just walking
+                // the AST like we're doing currently.
+                if (node.RangeVar.alias?.aliasname) {
+                    const aliasName = node.RangeVar.alias.aliasname;
+                    const existingMapping = this.tableMappings.get(aliasName);
+                    const part = {
+                        text: node.RangeVar.relname,
+                        start: node.RangeVar.location,
+                        // what goes here? the text here doesn't _really_ exist.
+                        // so it can't be quoted or not quoted.
+                        // Does it even matter?
+                        quoted: true,
+                        alias: aliasName,
+                    };
+                    // Postgres supports shadowing table aliases created in different levels of queries
+                    // for example:
+                    // ```
+                    // SELECT t.id, t.name
+                    // FROM users t
+                    // WHERE EXISTS (
+                    //     SELECT 1
+                    //     FROM orders t   -- shadows outer alias "t"
+                    //     WHERE t.user_id = users.id
+                    // );
+                    // ```
+                    // but we're very unlikely to see this in practice. Every ORM I've seen so far
+                    // has produced globally unique aliases. This is not worth the complexity currently.
+                    // but is almost certainly guaranteed to be a problem in the future.
+                    if (existingMapping) {
+                        console.warn(`Ignoring alias ${aliasName} as it shadows an existing mapping. We currently do not support alias shadowing.`);
+                        // Let the user know what happened but don't stop the show.
+                        this.shadowedAliases.push(part);
+                        return;
+                    }
+                    this.tableMappings.set(aliasName, part);
+                }
+            }
+            // select ... from table order by col asc
+            //                       ^^^^^^^^^^^^^^^^
+            if (is(node, "SortBy")) {
+                // we don't care about sorting by anything that's not a column reference
+                // because it couldn't be indexed anyway.
+                // TODO: mark that expression as unindexable? It's just better for debugging
+                if (node.SortBy.node && is(node.SortBy.node, "ColumnRef")) {
+                    this.add(node.SortBy.node, {
+                        sort: {
+                            dir: node.SortBy.sortby_dir ?? "SORTBY_DEFAULT",
+                            nulls: node.SortBy.sortby_nulls ?? "SORTBY_NULLS_DEFAULT",
+                        },
+                    });
+                }
+            }
+            // select ... from table1 join table2 t2 on table1.col = t2.col
+            //                                    ^^
+            if (is(node, "JoinExpr") && node.JoinExpr.quals) {
+                if (is(node.JoinExpr.quals, "A_Expr")) {
+                    if (node.JoinExpr.quals.A_Expr.lexpr &&
+                        is(node.JoinExpr.quals.A_Expr.lexpr, "ColumnRef")) {
+                        this.add(node.JoinExpr.quals.A_Expr.lexpr);
+                    }
+                    if (node.JoinExpr.quals.A_Expr.rexpr &&
+                        is(node.JoinExpr.quals.A_Expr.rexpr, "ColumnRef")) {
+                        this.add(node.JoinExpr.quals.A_Expr.rexpr);
+                    }
+                }
+            }
+            // any column reference anywhere
+            if (is(node, "ColumnRef")) {
+                // TODO: this approach needs refinement
+                for (let i = 0; i < stack.length; i++) {
+                    const inReturningList = stack[i] === "returningList" &&
+                        stack[i + 1] === "ResTarget" &&
+                        stack[i + 2] === "val" &&
+                        stack[i + 3] === "ColumnRef";
+                    if (inReturningList) {
+                        this.add(node, { ignored: true });
+                        return;
+                    }
+                    if (
+                    // stack[i] === "SelectStmt" &&
+                    stack[i + 1] === "targetList" &&
+                        stack[i + 2] === "ResTarget" &&
+                        stack[i + 3] === "val" &&
+                        stack[i + 4] === "ColumnRef") {
+                        // we don't want to index the columns that are being selected
+                        this.add(node, { ignored: true });
+                        return;
+                    }
+                    // TODO: add functional index support here
+                    if (stack[i] === "FuncCall" && stack[i + 1] === "args") {
+                        // args of a function call can't be indexed (without functional indexes)
+                        this.add(node, { ignored: true });
+                        return;
+                    }
+                }
+                this.add(node);
+            }
+        });
+        return {
+            highlights: this.highlights,
+            indexRepresentations: this.indexRepresentations,
+            indexesToCheck: this.indexesToCheck,
+            shadowedAliases: this.shadowedAliases,
+            tempTables: this.tempTables,
+            tableMappings: this.tableMappings,
+            nudges: this.nudges,
+        };
+    }
+    add(node, options) {
+        if (!node.ColumnRef.location) {
+            console.error(`Node did not have a location. Skipping`, node);
+            return;
+        }
+        if (!node.ColumnRef.fields) {
+            console.error(node);
+            throw new Error("Column reference must have fields");
+        }
+        let ignored = options?.ignored ?? false;
+        let runningLength = node.ColumnRef.location;
+        const parts = node.ColumnRef.fields.map((field, i, length) => {
+            if (!is(field, "String") || !field.String.sval) {
+                const out = deparseSync(field);
+                ignored = true;
+                return {
+                    quoted: out.startsWith('"'),
+                    text: out,
+                    start: runningLength,
+                };
+            }
+            const start = runningLength;
+            const size = field.String.sval?.length ?? 0;
+            let quoted = false;
+            if (node.ColumnRef.location !== undefined) {
+                const boundary = this.query[runningLength];
+                if (boundary === '"') {
+                    quoted = true;
+                }
+            }
+            // +1 for the dot that comes after
+            const isLastIteration = i === length.length - 1;
+            runningLength += size + (isLastIteration ? 0 : 1) + (quoted ? 2 : 0);
+            return {
+                text: field.String.sval,
+                start,
+                quoted,
+            };
+        });
+        const end = runningLength;
+        if (this.highlightPositions.has(node.ColumnRef.location)) {
+            return;
+        }
+        this.highlightPositions.add(node.ColumnRef.location);
+        const highlighted = `${this.query.slice(node.ColumnRef.location, end)}`;
+        const seen = this.seenReferences.get(highlighted);
+        if (!ignored) {
+            this.seenReferences.set(highlighted, (seen ?? 0) + 1);
+        }
+        const ref = {
+            frequency: seen ?? 1,
+            representation: highlighted,
+            parts,
+            ignored: ignored ?? false,
+            position: {
+                start: node.ColumnRef.location,
+                end,
+            },
+        };
+        if (options?.sort) {
+            ref.sort = options.sort;
+        }
+        if (options?.where) {
+            ref.where = options.where;
+        }
+        this.highlights.push(ref);
+    }
+    static traverse(node, stack, callback) {
+        if (isANode(node)) {
+            callback(node, [...stack, getNodeKind(node)]);
+        }
+        if (typeof node !== "object" || node === null) {
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                if (isANode(item)) {
+                    Walker.traverse(item, stack, callback);
+                }
+            }
+        }
+        else if (isANode(node)) {
+            const keys = Object.keys(node);
+            // @ts-expect-error | nodes don't allow dynamic access but it's the only way to do it
+            Walker.traverse(node[keys[0]], [...stack, getNodeKind(node)], callback);
+        }
+        else {
+            for (const [key, child] of Object.entries(node)) {
+                Walker.traverse(child, [...stack, key], callback);
+            }
+        }
+    }
+}
+function is(node, kind) {
+    return kind in node;
+}
+function getNodeKind(node) {
+    const keys = Object.keys(node);
+    return keys[0];
+}
+function isANode(node) {
+    if (typeof node !== "object" || node === null) {
+        return false;
+    }
+    const keys = Object.keys(node);
+    return keys.length === 1 && /^[A-Z]/.test(keys[0]);
+}