@askdb/core 1.0.0-beta.42 → 1.0.0-beta.43

package/dist/sql/sensitive-guardrail.js

@@ -1,4 +1,5 @@
 import { SensitiveReferenceError, } from "../errors.js";
+import { ENGINE_LEXER_PROFILES, GENERIC_LEXER, hasUnterminatedToken, lexSql, lexerProfileFor, } from "./lexer.js";
 /**
  * Check whether a SQL statement references tables/columns marked `sensitive`
  * in the schema artifact.
@@ -14,16 +15,23 @@ import { SensitiveReferenceError, } from "../errors.js";
  * are resolved first. When scope cannot be resolved (no resolvable table source, or a
  * qualifier that binds to nothing known), the check fails conservatively — it widens
  * matching and reports why in {@link SensitiveGuardrailResult.unresolvedScope} — rather
- * than passing silently.
+ * than passing silently. A string, quoted identifier, or comment that never closes is
+ * reported the same way (`UNTERMINATED_TOKEN`).
  *
- * Heuristic, not a SQL parser. It is a review/enforcement aid, not a substitute for
- * database-side column privileges.
+ * `SELECT *`, `alias.*`, and whole-row references such as `row_to_json(alias)` count as
+ * referencing every sensitive column of the table they reach. They expand per query
+ * block: a bare `*` covers its own `SELECT`'s FROM/JOIN tables, and an alias resolves in
+ * its own block first, then in enclosing blocks. When the block structure cannot be
+ * read with confidence, they expand against every table in the statement.
+ *
+ * Heuristic, not a SQL parser, and not a security boundary. It is defense in depth for
+ * review and enforcement; database-side column privileges are the real control.
  */
 export function validateSensitiveReferences(sql, schema, options) {
     const mode = options?.mode ?? "warn";
     const index = indexSchema(schema);
     const result = index.hasSensitive
-        ? scan(sql, index)
+        ? scanSql(sql, index, options?.dialect)
         : { passed: true, references: [] };
     if (mode === "strict" && !result.passed) {
         throw new SensitiveReferenceError(buildStrictMessage(result), ruleFor(result), result.references, result.unresolvedScope);
@@ -103,134 +111,48 @@ function indexSchema(schema) {
     indexCache.set(schema, index);
     return index;
 }
-const WORD_START = /[A-Za-z_\u0080-\uFFFF]/;
-const WORD_CHAR = /[A-Za-z0-9_$\u0080-\uFFFF]/;
-function tokenize(sql) {
+/**
+ * Map lexer tokens onto the scanner's simpler vocabulary. Comments are dropped (MySQL
+ * `/*! … *\/` bodies are already lexed as code).
+ */
+function toToks(tokens) {
     const out = [];
-    const push = (kind, value, quoted = false) => {
-        out.push({ kind, value, lower: value.toLowerCase(), quoted });
-    };
-    let i = 0;
-    while (i < sql.length) {
-        const ch = sql[i];
-        if (/\s/.test(ch)) {
-            i++;
-            continue;
-        }
-        if (ch === "-" && sql[i + 1] === "-") {
-            while (i < sql.length && sql[i] !== "\n")
-                i++;
-            continue;
-        }
-        if (ch === "/" && sql[i + 1] === "*") {
-            i += 2;
-            while (i < sql.length && !(sql[i] === "*" && sql[i + 1] === "/"))
-                i++;
-            i = Math.min(i + 2, sql.length);
-            continue;
-        }
-        if (ch === "'") {
-            i++;
-            while (i < sql.length) {
-                if (sql[i] === "'" && sql[i + 1] === "'") {
-                    i += 2;
-                    continue;
-                }
-                if (sql[i] === "'") {
-                    i++;
-                    break;
-                }
-                i++;
-            }
-            push("literal", "'");
-            continue;
-        }
-        if (ch === "$") {
-            const dollarQuote = /^\$(\w*)\$/.exec(sql.slice(i));
-            if (dollarQuote) {
-                const opener = dollarQuote[0];
-                const close = sql.indexOf(opener, i + opener.length);
-                i = close === -1 ? sql.length : close + opener.length;
-                push("literal", "$$");
-                continue;
-            }
-            if (/[0-9]/.test(sql[i + 1] ?? "")) {
-                let j = i + 1;
-                while (j < sql.length && /[0-9]/.test(sql[j]))
-                    j++;
-                push("placeholder", sql.slice(i, j));
-                i = j;
-                continue;
-            }
-        }
-        if (ch === '"' || ch === "`") {
-            const close = ch;
-            i++;
-            let buf = "";
-            while (i < sql.length) {
-                if (sql[i] === close && sql[i + 1] === close) {
-                    buf += close;
-                    i += 2;
-                    continue;
+    for (const t of tokens) {
+        switch (t.kind) {
+            case "comment":
+                break;
+            case "word":
+                out.push({ kind: "word", value: t.value, lower: t.lower, quoted: false });
+                break;
+            case "quoted_identifier":
+                out.push({ kind: "word", value: t.value, lower: t.lower, quoted: true });
+                break;
+            case "string":
+                // MySQL/MariaDB `"…"` is a string under the default sql_mode but an identifier
+                // under ANSI_QUOTES, and the lexer cannot know which the server runs. Reading it
+                // as an identifier means `SELECT "ssn"` is flagged: over-reporting is the safe
+                // failure for this check, while reading it as a string would be a bypass on
+                // ANSI_QUOTES servers. The tenant guardrail makes the mirror-image choice (a
+                // `"tenant_id"` predicate reads as a string, so it never counts as scoping),
+                // because there treating it as a string is what fails closed.
+                if (t.quote === '"') {
+                    const inner = t.text.slice(1, t.unterminated ? undefined : -1);
+                    out.push({ kind: "word", value: inner, lower: inner.toLowerCase(), quoted: true });
                 }
-                if (sql[i] === close) {
-                    i++;
-                    break;
+                else {
+                    out.push({ kind: "literal", value: "'", lower: "'", quoted: false });
                 }
-                buf += sql[i];
-                i++;
-            }
-            push("word", buf, true);
-            continue;
-        }
-        if (ch === "[") {
-            i++;
-            let buf = "";
-            while (i < sql.length && sql[i] !== "]") {
-                buf += sql[i];
-                i++;
-            }
-            if (i < sql.length)
-                i++;
-            push("word", buf, true);
-            continue;
-        }
-        if (ch === ":" && sql[i + 1] === ":") {
-            push("punct", "::");
-            i += 2;
-            continue;
-        }
-        if ((ch === ":" || ch === "@") && WORD_START.test(sql[i + 1] ?? "")) {
-            let j = i + 1;
-            while (j < sql.length && WORD_CHAR.test(sql[j]))
-                j++;
-            push("placeholder", sql.slice(i, j));
-            i = j;
-            continue;
-        }
-        if (/[0-9]/.test(ch)) {
-            let j = i;
-            while (j < sql.length && /[0-9]/.test(sql[j]))
-                j++;
-            if (sql[j] === "." && /[0-9]/.test(sql[j + 1] ?? "")) {
-                j++;
-                while (j < sql.length && /[0-9]/.test(sql[j]))
-                    j++;
-            }
-            push("number", sql.slice(i, j));
-            i = j;
-            continue;
-        }
-        if (WORD_START.test(ch)) {
-            let j = i;
-            while (j < sql.length && WORD_CHAR.test(sql[j]))
-                j++;
-            push("word", sql.slice(i, j));
-            i = j;
-            continue;
+                break;
+            case "number":
+                out.push({ kind: "number", value: t.text, lower: t.lower, quoted: false });
+                break;
+            case "parameter":
+                out.push({ kind: "placeholder", value: t.text, lower: t.lower, quoted: false });
+                break;
+            case "punct":
+                out.push({ kind: "punct", value: t.text, lower: t.text, quoted: false });
+                break;
         }
-        push("punct", ch);
-        i++;
     }
     return out;
 }
@@ -267,17 +189,116 @@ const BARE_STOP = new Set([
 const JOIN_MODIFIER = new Set([
     "inner", "left", "right", "full", "outer", "cross", "natural", "straight_join",
 ]);
-function scan(sql, index) {
-    const tokens = tokenize(sql);
+/**
+ * Words that continue an expression rather than end one, on top of {@link ALIAS_STOP} and
+ * {@link BARE_STOP}. A word after one of these is an operand, never an implicit alias —
+ * `a DIV u`, `ts AT TIME ZONE u`, `json_object('k' VALUE u)`. Broad on purpose: a word
+ * wrongly listed here only costs an over-report.
+ */
+const EXPR_KEYWORDS = new Set([
+    "array", "asymmetric", "binary", "content", "default", "div", "document", "false",
+    "glob", "interval", "isnull", "match", "mod", "notnull", "operator", "overlaps",
+    "placing", "regexp", "rlike", "row", "sounds", "symmetric", "to", "true", "unique",
+    "value", "variadic", "xor", "zone",
+]);
+const isKeyword = (lower) => ALIAS_STOP.has(lower) || BARE_STOP.has(lower) || EXPR_KEYWORDS.has(lower);
+/** Unquoted words that end a select list at its own nesting depth. */
+const SELECT_LIST_END = new Set([
+    "except", "fetch", "for", "from", "group", "having", "intersect", "into", "limit",
+    "offset", "order", "union", "where", "window",
+]);
+const STANDARD_SELECT_WORDS = ["all", "distinct"];
+const MYSQL_SELECT_WORDS = [
+    ...STANDARD_SELECT_WORDS,
+    "distinctrow", "high_priority", "straight_join", "sql_small_result", "sql_big_result",
+    "sql_buffer_result", "sql_no_cache", "sql_cache", "sql_calc_found_rows",
+];
+const SELECT_MODIFIERS = {
+    postgres: { words: new Set(STANDARD_SELECT_WORDS), distinctOn: true, top: false },
+    mysql: { words: new Set(MYSQL_SELECT_WORDS), distinctOn: false, top: false },
+    sqlserver: { words: new Set(STANDARD_SELECT_WORDS), distinctOn: false, top: true },
+    sqlite: { words: new Set(STANDARD_SELECT_WORDS), distinctOn: false, top: false },
+    /** Unknown or no dialect: accept every engine's modifiers, so no wildcard slips past. */
+    any: { words: new Set(MYSQL_SELECT_WORDS), distinctOn: true, top: true },
+};
+function selectModifiersFor(dialect) {
+    switch (dialect?.id) {
+        case "postgres":
+        case "cockroachdb":
+            return SELECT_MODIFIERS.postgres;
+        case "mysql":
+        case "mariadb":
+            return SELECT_MODIFIERS.mysql;
+        case "sqlserver":
+            return SELECT_MODIFIERS.sqlserver;
+        case "sqlite":
+            return SELECT_MODIFIERS.sqlite;
+        default:
+            return SELECT_MODIFIERS.any;
+    }
+}
+/**
+ * Lex and scan. With a known dialect the statement is lexed once, the way that engine
+ * reads it. Without one (or for an unrecognized id) the generic reading decides scope
+ * issues, and references are unioned across every engine's reading that lexes cleanly —
+ * so a column hidden from one reading by an engine-specific quote or comment rule (for
+ * example MySQL `'\''` or Postgres `E'\''`) is still reported. Readings with an
+ * unterminated token are skipped: the engine would reject that SQL outright.
+ */
+function scanSql(sql, index, dialect) {
+    const profile = dialect ? lexerProfileFor(dialect) : undefined;
+    if (profile) {
+        return finalize(scanTokens(lexSql(sql, profile), index, selectModifiersFor(dialect)));
+    }
+    const modifiers = SELECT_MODIFIERS.any;
+    const primary = scanTokens(lexSql(sql, GENERIC_LEXER), index, modifiers);
+    for (const p of ENGINE_LEXER_PROFILES) {
+        const tokens = lexSql(sql, p);
+        if (hasUnterminatedToken(tokens))
+            continue;
+        for (const [key, ref] of scanTokens(tokens, index, modifiers).found) {
+            const existing = primary.found.get(key);
+            if (!existing)
+                primary.found.set(key, ref);
+            else if (ref.matchKind === "qualified")
+                existing.matchKind = "qualified";
+        }
+    }
+    return finalize(primary);
+}
+function finalize(outcome) {
+    const references = [...outcome.found.values()]
+        .sort((a, b) => a.tableOrder - b.tableOrder || a.columnOrder - b.columnOrder)
+        .map(({ tableOrder: _tableOrder, columnOrder: _columnOrder, ...ref }) => ref);
+    const unresolvedScope = outcome.issues.size > 0 ? buildScopeReport([...outcome.issues], outcome.widened) : undefined;
+    return {
+        passed: references.length === 0 && unresolvedScope === undefined,
+        references,
+        ...(unresolvedScope ? { unresolvedScope } : {}),
+    };
+}
+function scanTokens(lexed, index, modifiers) {
+    const tokens = toToks(lexed);
     const isWord = (t) => t?.kind === "word";
     const isPunct = (t, v) => t?.kind === "punct" && t.value === v;
+    const isKeywordTok = (t, v) => t?.kind === "word" && !t.quoted && t.lower === v;
     const canAlias = (t) => t?.kind === "word" && (t.quoted || !ALIAS_STOP.has(t.lower));
     /** Token indices already accounted for as relation names or aliases. */
     const consumed = new Set();
     /** Relation names that exist but are not schema tables (CTEs, derived tables). */
     const derived = new Set();
+    // FROM/JOIN bindings. `at` is the index of the FROM/JOIN keyword that introduced them,
+    // which places the binding in that clause's query block.
     const sourcePaths = [];
     const aliasDecls = [];
+    /** Aliases of derived tables and table functions — bound, but to no schema table. */
+    const derivedDecls = [];
+    /** The FROM/JOIN keyword whose items `parseTableRef` is reading. */
+    let bindingAt = -1;
+    const addDerived = (alias) => {
+        derived.add(alias);
+        derivedDecls.push({ alias, at: bindingAt });
+    };
     let opaqueSource = false;
     let sawTableSource = false;
     const closeParenAfter = (open) => {
@@ -306,6 +327,113 @@ function scan(sql, index) {
         }
         return -1;
     };
+    /**
+     * Index of the first select-list item after the `SELECT` at `select`, skipping the
+     * engine's modifiers: `DISTINCT`, `DISTINCT ON (x)`, MySQL `SQL_NO_CACHE`, SQL Server
+     * `TOP (5) PERCENT WITH TIES`, …. `PERCENT` / `TIES` only count inside a `TOP` clause,
+     * so `SELECT percent * rate` stays a multiplication.
+     */
+    const selectListStart = (select) => {
+        let k = select + 1;
+        for (;;) {
+            const t = tokens[k];
+            if (t?.kind !== "word" || t.quoted)
+                return k;
+            if (modifiers.distinctOn &&
+                t.lower === "distinct" &&
+                isKeywordTok(tokens[k + 1], "on") &&
+                isPunct(tokens[k + 2], "(")) {
+                const close = closeParenAfter(k + 2);
+                if (close === -1)
+                    return k;
+                k = close + 1;
+                continue;
+            }
+            if (modifiers.words.has(t.lower)) {
+                k++;
+                continue;
+            }
+            if (modifiers.top && t.lower === "top") {
+                let j = k + 1;
+                if (isPunct(tokens[j], "(")) {
+                    const close = closeParenAfter(j);
+                    if (close === -1)
+                        return k;
+                    j = close + 1;
+                }
+                else if (tokens[j]?.kind === "number" || tokens[j]?.kind === "placeholder") {
+                    j++;
+                }
+                else {
+                    return k; // `top` is an ordinary column name here
+                }
+                if (isKeywordTok(tokens[j], "percent"))
+                    j++;
+                if (isKeywordTok(tokens[j], "with") && isKeywordTok(tokens[j + 1], "ties"))
+                    j += 2;
+                k = j;
+                continue;
+            }
+            return k;
+        }
+    };
+    /** A token that can end a select-list expression, so a word right after it is an alias. */
+    const endsExpression = (k) => {
+        const t = tokens[k];
+        if (!t)
+            return false;
+        if (t.kind === "word")
+            return t.quoted || !isKeyword(t.lower);
+        if (t.kind === "number" || t.kind === "literal")
+            return true;
+        if (!isPunct(t, ")"))
+            return false;
+        // `a OPERATOR(pg_catalog.||) u` — the parenthesized operator takes a right operand.
+        return !isKeywordTok(tokens[openParenBefore(k) - 1], "operator");
+    };
+    const endsSelectList = (t) => t === undefined ||
+        isPunct(t, ")") ||
+        isPunct(t, ";") ||
+        (t.kind === "word" && !t.quoted && SELECT_LIST_END.has(t.lower));
+    /**
+     * Bare `*` projections, and select-list words that are implicit output aliases. `SELECT
+     * id u` names an output column `u`, while `SELECT u` and `SELECT id, u` read the row, so
+     * only a word between an expression-ending token and the end of its item (`,` or the end
+     * of the list) is an alias. Anything less certain stays a reference.
+     */
+    const wildcards = new Set();
+    const implicitAliases = new Set();
+    for (let s = 0; s < tokens.length; s++) {
+        if (!isKeywordTok(tokens[s], "select"))
+            continue;
+        const start = selectListStart(s);
+        // `EXISTS (SELECT * …)` returns no columns.
+        const inExists = isPunct(tokens[s - 1], "(") && isKeywordTok(tokens[s - 2], "exists");
+        if (isPunct(tokens[start], "*") && !inExists)
+            wildcards.add(start);
+        let depth = 0;
+        for (let k = start; k < tokens.length; k++) {
+            const t = tokens[k];
+            if (isPunct(t, "("))
+                depth++;
+            else if (isPunct(t, ")")) {
+                if (depth === 0)
+                    break;
+                depth--;
+            }
+            else if (depth > 0)
+                continue;
+            else if (endsSelectList(t))
+                break;
+            else if (k > start &&
+                t.kind === "word" &&
+                (t.quoted || !isKeyword(t.lower)) &&
+                endsExpression(k - 1) &&
+                (isPunct(tokens[k + 1], ",") || endsSelectList(tokens[k + 1]))) {
+                implicitAliases.add(k);
+            }
+        }
+    }
     /** Consume an optional `AS alias` / bare `alias`; returns the index after it. */
     const takeAlias = (start, register) => {
         let k = start;
@@ -343,7 +471,7 @@ function scan(sql, index) {
             if (close === -1)
                 return j + 1;
             sawTableSource = true;
-            return takeAlias(close + 1, (alias) => derived.add(alias));
+            return takeAlias(close + 1, addDerived);
         }
         if (!canAlias(tokens[j])) {
             // e.g. the operand in `EXTRACT(YEAR FROM 1)` — not a relation name.
@@ -370,11 +498,11 @@ function scan(sql, index) {
             // Table function / table-valued expression — its columns are not schema columns.
             opaqueSource = true;
             const close = closeParenAfter(k);
-            return takeAlias(close === -1 ? k + 1 : close + 1, (alias) => derived.add(alias));
+            return takeAlias(close === -1 ? k + 1 : close + 1, addDerived);
         }
         sawTableSource = true;
-        sourcePaths.push(path);
-        return takeAlias(k, (alias) => aliasDecls.push({ alias, path }));
+        sourcePaths.push({ path, at: bindingAt });
+        return takeAlias(k, (alias) => aliasDecls.push({ alias, path, at: bindingAt }));
     };
     // Pass A — resolve relation names, aliases, and CTE names.
     for (let i = 0; i < tokens.length; i++) {
@@ -400,6 +528,7 @@ function scan(sql, index) {
                 consumed.add(k);
             }
         }
+        bindingAt = i;
         let j = i + 1;
         for (;;) {
             const next = parseTableRef(j);
@@ -413,9 +542,19 @@ function scan(sql, index) {
     }
     // Pass B — collect the column references the statement actually makes.
     const qualifiedRefs = [];
+    const starRefs = [];
     const bare = new Set();
+    /** Each bare word where it occurs: a table name or alias used as a value is the whole row. */
+    const wholeRowRefs = [];
+    const bareStars = [];
     for (let i = 0; i < tokens.length; i++) {
         const t = tokens[i];
+        // `SELECT *`, `SELECT DISTINCT *`, `SELECT TOP 5 *`, `SELECT a, *` — not `count(*)`
+        // or multiplication.
+        if (isPunct(t, "*") && (wildcards.has(i) || isPunct(tokens[i - 1], ","))) {
+            bareStars.push(i);
+            continue;
+        }
         if (t.kind !== "word")
             continue;
         if (isPunct(tokens[i - 1], "."))
@@ -424,6 +563,8 @@ function scan(sql, index) {
             continue; // cast target type
         if (isWord(tokens[i - 1]) && tokens[i - 1].lower === "as")
             continue; // output alias
+        if (implicitAliases.has(i))
+            continue; // output alias without AS
         if (isPunct(tokens[i + 1], ".")) {
             const path = [t.lower];
             let k = i + 1;
@@ -440,7 +581,15 @@ function scan(sql, index) {
                 path.push(tokens[k].lower);
                 k++;
             }
-            if (!star && path.length >= 2 && !consumed.has(i)) {
+            if (star && !consumed.has(i)) {
+                // `alias.*` / `schema.table.*` — every column of the qualifier's table.
+                starRefs.push({
+                    qualifier: path[path.length - 1],
+                    ...(path.length >= 2 ? { qualifierSchema: path[path.length - 2] } : {}),
+                    at: i,
+                });
+            }
+            else if (!star && path.length >= 2 && !consumed.has(i)) {
                 qualifiedRefs.push({
                     column: path[path.length - 1],
                     qualifier: path[path.length - 2],
@@ -457,6 +606,7 @@ function scan(sql, index) {
         if (!t.quoted && BARE_STOP.has(t.lower))
             continue;
         bare.add(t.lower);
+        wholeRowRefs.push({ word: t.lower, at: i });
     }
     // Bind relation names and aliases to schema tables.
     const resolve = (path) => {
@@ -471,23 +621,69 @@ function scan(sql, index) {
         // v1 schemas carry no namespace — a qualified reference still matches by name.
         return candidates.filter((e) => e.schemaLower === undefined);
     };
+    // Query blocks, for wildcard and whole-row expansion. When the block tree cannot be
+    // trusted — an unterminated token, unbalanced parentheses, a SELECT that neither nests
+    // nor follows a set operator, or a FROM/JOIN outside every block — every binding and
+    // reference goes into one block, which is the statement-global reading.
+    let tree = hasUnterminatedToken(lexed) ? undefined : buildQueryBlocks(tokens);
+    if (tree && [...sourcePaths, ...derivedDecls].some((b) => tree.blockOf[b.at] === -1)) {
+        tree = undefined;
+    }
+    const blockAt = (k) => (tree ? tree.blockOf[k] : 0);
+    const parentOf = (block) => (tree ? tree.parent[block] : -1);
+    /** Every table the statement reaches, and every qualifier it binds, in any block. */
     const inScope = new Set();
     const qualifiers = new Map();
-    const bindQualifier = (name, entries) => {
-        const bucket = qualifiers.get(name);
+    const blockScopes = new Map();
+    const blockScope = (block) => {
+        let scope = blockScopes.get(block);
+        if (!scope) {
+            scope = { tables: new Set(), qualifiers: new Map() };
+            blockScopes.set(block, scope);
+        }
+        return scope;
+    };
+    const bindQualifier = (into, name, entries) => {
+        const bucket = into.get(name);
         if (bucket)
             bucket.push(...entries.filter((e) => !bucket.includes(e)));
         else
-            qualifiers.set(name, [...entries]);
+            into.set(name, [...entries]);
     };
-    for (const path of sourcePaths) {
+    for (const { path, at } of sourcePaths) {
         const entries = resolve(path);
-        for (const e of entries)
+        const scope = blockScope(blockAt(at));
+        for (const e of entries) {
             inScope.add(e);
-        bindQualifier(path[path.length - 1], entries);
+            scope.tables.add(e);
+        }
+        bindQualifier(qualifiers, path[path.length - 1], entries);
+        bindQualifier(scope.qualifiers, path[path.length - 1], entries);
+    }
+    for (const { alias, path, at } of aliasDecls) {
+        const entries = resolve(path);
+        bindQualifier(qualifiers, alias, entries);
+        bindQualifier(blockScope(blockAt(at)).qualifiers, alias, entries);
+    }
+    // A derived-table alias binds no schema table, but it still shadows outer bindings.
+    for (const { alias, at } of derivedDecls) {
+        bindQualifier(blockScope(blockAt(at)).qualifiers, alias, []);
     }
-    for (const decl of aliasDecls)
-        bindQualifier(decl.alias, resolve(decl.path));
+    /**
+     * The tables `name` denotes where it is written: its own block's bindings first, then
+     * each enclosing block's (correlated references). A name no enclosing block binds falls
+     * back to every binding in the statement, so a reference that cannot be placed is
+     * over-reported rather than dropped.
+     */
+    const lookupQualifier = (name, block) => {
+        for (let b = block; b !== -1; b = parentOf(b)) {
+            const bound = blockScopes.get(b)?.qualifiers.get(name);
+            if (bound)
+                return bound;
+        }
+        return qualifiers.get(name);
+    };
+    // Collect findings.
     const found = new Map();
     const record = (table, column, columnOrder, matchKind) => {
         const key = `${table.schemaLower ?? ""}.${table.lower}.${column.toLowerCase()}`;
@@ -558,22 +754,113 @@ function scan(sql, index) {
             }
         }
     }
-    const references = [...found.values()]
-        .sort((a, b) => a.tableOrder - b.tableOrder || a.columnOrder - b.columnOrder)
-        .map(({ tableOrder: _tableOrder, columnOrder: _columnOrder, ...ref }) => ref);
-    const unresolvedScope = issues.size > 0
-        ? buildScopeReport([...issues], noTableSource || unknownQualifierColumns.size > 0)
-        : undefined;
-    return {
-        passed: references.length === 0 && unresolvedScope === undefined,
-        references,
-        ...(unresolvedScope ? { unresolvedScope } : {}),
+    // Wildcards and whole-row references reach every column of the table, so they reach
+    // its sensitive columns. (Table-level-sensitive tables are already reported as "*".)
+    const recordAllSensitive = (table, matchKind) => {
+        if (table.sensitive)
+            return;
+        for (const column of table.columns) {
+            if (column.sensitive)
+                record(table, column.name, column.order, matchKind);
+        }
+    };
+    // Bare `SELECT *` — every table its own block's FROM/JOIN reaches.
+    for (const at of bareStars) {
+        const block = blockAt(at);
+        const tables = block === -1 ? inScope : (blockScopes.get(block)?.tables ?? []);
+        for (const table of tables)
+            recordAllSensitive(table, "unqualified");
+    }
+    // `alias.*`
+    for (const ref of starRefs) {
+        const bound = lookupQualifier(ref.qualifier, blockAt(ref.at));
+        if (!bound) {
+            if (!derived.has(ref.qualifier))
+                issues.add("UNKNOWN_QUALIFIER");
+            continue;
+        }
+        const scoped = ref.qualifierSchema
+            ? bound.filter((e) => e.schemaLower === undefined || e.schemaLower === ref.qualifierSchema)
+            : bound;
+        for (const table of scoped)
+            recordAllSensitive(table, "qualified");
+    }
+    // A table name or alias used as a value — `row_to_json(u)`, `to_jsonb(u)`,
+    // `json_agg(u)`, Postgres `SELECT u FROM users u` — is the whole row.
+    for (const { word, at } of wholeRowRefs) {
+        for (const table of lookupQualifier(word, blockAt(at)) ?? []) {
+            recordAllSensitive(table, "qualified");
+        }
+    }
+    if (hasUnterminatedToken(lexed))
+        issues.add("UNTERMINATED_TOKEN");
+    return { found, issues, widened: noTableSource || unknownQualifierColumns.size > 0 };
+}
+/**
+ * The statement's query blocks, read from parenthesis depth. Every `SELECT` opens a block
+ * that runs to the `)` closing its depth, a set operator (`UNION` / `INTERSECT` /
+ * `EXCEPT`) at its depth, or a `;`. A block's parent is the innermost block still open
+ * where it starts, so subqueries, derived tables, CTE bodies, and `EXISTS` / `IN`
+ * operands nest, and set-operation branches are siblings. Parentheses that do not start
+ * a `SELECT` (function calls, parenthesized joins) stay in the enclosing block.
+ *
+ * `blockOf[k]` is the block token `k` belongs to, or -1 outside every block (e.g. the
+ * tokens of a top-level `WITH` clause). Returns `undefined` when the tree cannot be
+ * trusted: unbalanced parentheses, a `;` inside parentheses, or a `SELECT` at a depth
+ * whose block is still open (two statements with no separator, or a construct this
+ * reader does not know).
+ */
+function buildQueryBlocks(tokens) {
+    const blockOf = [];
+    const parent = [];
+    /** `open[d]` is the block open at parenthesis depth `d`, or -1. */
+    const open = [-1];
+    const innermost = () => {
+        for (let d = open.length - 1; d >= 0; d--)
+            if (open[d] !== -1)
+                return open[d];
+        return -1;
     };
+    for (const t of tokens) {
+        const depth = open.length - 1;
+        const punct = t.kind === "punct" ? t.value : undefined;
+        if (punct === "(") {
+            blockOf.push(innermost());
+            open.push(-1);
+            continue;
+        }
+        if (punct === ")") {
+            if (depth === 0)
+                return undefined;
+            open.pop();
+            blockOf.push(innermost());
+            continue;
+        }
+        if (punct === ";") {
+            if (depth !== 0)
+                return undefined;
+            open[0] = -1;
+            blockOf.push(-1);
+            continue;
+        }
+        const keyword = t.kind === "word" && !t.quoted ? t.lower : undefined;
+        if (keyword === "select") {
+            if (open[depth] !== -1)
+                return undefined;
+            parent.push(innermost());
+            open[depth] = parent.length - 1;
+        }
+        blockOf.push(innermost());
+        if (keyword === "union" || keyword === "intersect" || keyword === "except")
+            open[depth] = -1;
+    }
+    return open.length === 1 ? { blockOf, parent } : undefined;
 }
 const SCOPE_ISSUE_TEXT = {
     NO_TABLE_SOURCE: "no FROM/JOIN target could be resolved, so unqualified column names cannot be bound to a table",
     UNKNOWN_QUALIFIER: "a qualified reference used a qualifier that is not a known table, alias, or CTE",
     OPAQUE_TABLE_SOURCE: "a table source is not a relation name (table function or table-valued expression)",
+    UNTERMINATED_TOKEN: "a string, quoted identifier, or comment never closes, so the rest of the statement could not be scanned",
 };
 function buildScopeReport(issues, widened) {
     const detail = issues.map((i) => SCOPE_ISSUE_TEXT[i]).join("; ");