code-auditor-mcp 3.4.11 → 3.4.13

package/dist/analyzers/provenance.js

@@ -65,7 +65,26 @@ export const DB_TYPES = new Set([
     'SqliteDatabase',
     'BetterSQLite3Database',
 ]);
-/** DB call methods — the fixed API surface (language-invariant) */
+/**
+ * DB call methods — the fixed API surface (language-invariant).
+ *
+ * Spec 33 Item 11 FP category 5: the bare-identifier hybrid fallback in
+ * `isDBProvenanced` treated any `get(...)` / `each(...)` / `values(...)` call
+ * as a DB query, flagging lodash-style object accessors (e.g.
+ * `@directus/utils`'s `get(item, ...)`) as sql-injection. Those three names
+ * are also common non-DB methods (lodash `get`, jQuery/iterator
+ * `each`, Map/WebSocket `.values()`), so they are removed from the fallback —
+ * mirroring the `get`/`each` trim in CHANGELOG 3.4.9 (DB_CALL_METHOD_NAMES).
+ *
+ * `query` is deliberately RETAINED: it is a genuine query-execution method on
+ * mysql2, pg, node-postgres, D1 and Planetscale (`.query(...)`), and the
+ * spec-19 data-access fixtures exercise it as a canonical DB entry point.
+ * Removing it would turn real SQL-injection positives into false negatives.
+ *
+ * `raw` is deliberately retained: it is a genuine raw-execution method on
+ * D1 prepared statements, Knex, and Kysely, and the Item-6 taint-tracking
+ * fixtures exercise it as the canonical raw-SQL entry point.
+ */
 export const DB_CALL_METHODS = new Set([
     'exec',
     'prepare',
@@ -74,10 +93,7 @@ export const DB_CALL_METHODS = new Set([
     'all',
     'first',
     'query',
-    'get',
-    'each',
     'raw',
-    'values',
 ]);
 /** ORM method patterns — fixed API surface for ORM recognition (Spec 21 R1) */
 export const ORM_METHODS = new Set([
@@ -128,6 +144,9 @@ function matchesValidatorPackage(specifier) {
  *
  * An import like `import Database from 'better-sqlite3'` produces
  * `Database` as DB-provenanced with reason "package".
+ * @param adapter
+ * @param ast
+ * @returns
  */
 export function extractDBProvenancedImports(ast, adapter) {
     const seedMap = new Map();
@@ -159,6 +178,9 @@ export function extractDBProvenancedImports(ast, adapter) {
 /**
  * Extract all validator-provenanced identifiers from a file's imports.
  * Same pattern as extractDBProvenancedImports but for validator packages.
+ * @param adapter
+ * @param ast
+ * @returns
  */
 export function extractValidatorProvenancedImports(ast, adapter) {
     const seedMap = new Map();
@@ -189,6 +211,133 @@ export function extractValidatorProvenancedImports(ast, adapter) {
 // ═══════════════════════════════════════════════════════════════════════════
 // Provenance propagation (R1 core)
 // ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Propagate provenance through a variable declaration (rules 1-3, 8).
+ * Returns true if any new identifier was added.
+ */
+function propagateVariableDeclaration(node, ctx) {
+    const { nameNode, valueNode, typeAnnotationNode } = splitVariableDeclarator(node, ctx.adapter);
+    if (!nameNode)
+        return false;
+    let mutated = false;
+    // Rule 8: type annotation — let x: D1Database
+    if (typeAnnotationNode) {
+        mutated = propagateFromTypeAnnotation(nameNode, typeAnnotationNode, ctx);
+    }
+    if (valueNode) {
+        mutated = propagateFromValue(nameNode, valueNode, ctx) || mutated;
+    }
+    return mutated;
+}
+/** Rule 8: type annotation — `let x: D1Database`. */
+function propagateFromTypeAnnotation(nameNode, typeAnnotationNode, ctx) {
+    if (nameNode.type !== 'identifier')
+        return false;
+    const typeText = ctx.adapter.getNodeText(typeAnnotationNode, ctx.sourceCode).trim();
+    if (!DB_TYPES.has(typeText))
+        return false;
+    const name = ctx.adapter.getNodeText(nameNode, ctx.sourceCode);
+    if (ctx.provenanceMap.has(name))
+        return false;
+    ctx.provenanceMap.set(name, {
+        identifier: name,
+        reason: 'type',
+        source: `type annotation ${typeText}`,
+        chain: [],
+    });
+    return true;
+}
+/** Propagate provenance from a declarator's value expression into its names. */
+function propagateFromValue(nameNode, valueNode, ctx) {
+    const propagated = tryPropagateFromExpression(valueNode, ctx.adapter, ctx.sourceCode, ctx.provenanceMap);
+    if (!propagated)
+        return false;
+    let mutated = false;
+    for (const varName of extractPatternNames(nameNode, ctx.adapter, ctx.sourceCode)) {
+        if (!ctx.provenanceMap.has(varName)) {
+            ctx.provenanceMap.set(varName, {
+                identifier: varName,
+                reason: 'propagation',
+                source: propagated.source,
+                chain: [...propagated.chain, propagated.identifier],
+            });
+            mutated = true;
+        }
+    }
+    return mutated;
+}
+/**
+ * Propagate provenance through a default parameter (rule 6).
+ * Returns true if a new identifier was added.
+ */
+function propagateDefaultParameter(node, adapter, sourceCode, provenanceMap) {
+    const children = adapter.getChildren(node);
+    // assignment_pattern has [left, right]
+    if (children.length < 2)
+        return false;
+    const leftNode = children[0];
+    const rightNode = children[1];
+    if (leftNode.type !== 'identifier')
+        return false;
+    const paramName = adapter.getNodeText(leftNode, sourceCode);
+    const propagated = tryPropagateFromExpression(rightNode, adapter, sourceCode, provenanceMap);
+    if (propagated && !provenanceMap.has(paramName)) {
+        provenanceMap.set(paramName, {
+            identifier: paramName,
+            reason: 'propagation',
+            source: `default parameter = ${propagated.source}`,
+            chain: [...propagated.chain, propagated.identifier],
+        });
+        return true;
+    }
+    return false;
+}
+/**
+ * Propagate provenance through a class field initialization (rule 7).
+ * Returns true if a new identifier was added.
+ */
+function propagateClassField(node, adapter, sourceCode, provenanceMap) {
+    const children = adapter.getChildren(node);
+    // Typically [name, value] or [decorators..., name, value]
+    const nameChild = children.find((c) => c.type === 'property_identifier');
+    const valueChild = children.find((c) => c.type !== 'property_identifier' &&
+        c.type !== 'decorator' &&
+        c.type !== 'private' &&
+        c.type !== 'public' &&
+        c.type !== 'protected' &&
+        c.type !== 'static' &&
+        c.type !== 'readonly' &&
+        c.type !== 'abstract');
+    if (nameChild && valueChild) {
+        const fieldName = adapter.getNodeText(nameChild, sourceCode);
+        const propagated = tryPropagateFromExpression(valueChild, adapter, sourceCode, provenanceMap);
+        if (propagated && !provenanceMap.has(fieldName)) {
+            provenanceMap.set(fieldName, {
+                identifier: fieldName,
+                reason: 'propagation',
+                source: `class field initialized from ${propagated.source}`,
+                chain: [...propagated.chain, propagated.identifier],
+            });
+            return true;
+        }
+    }
+    return false;
+}
+function applyPropagationRule(node, parent, ctx) {
+    const { adapter, sourceCode, provenanceMap } = ctx;
+    if (node.type === 'variable_declarator') {
+        return propagateVariableDeclaration(node, ctx);
+    }
+    if (node.type === 'assignment_pattern' &&
+        parent?.type === 'formal_parameters') {
+        return propagateDefaultParameter(node, adapter, sourceCode, provenanceMap);
+    }
+    if (node.type === 'public_field_definition' ||
+        node.type === 'field_definition') {
+        return propagateClassField(node, adapter, sourceCode, provenanceMap);
+    }
+    return false;
+}
 /**
  * Propagate provenance through assignments, destructuring, parameters,
  * class fields, and type annotations within a single file.
@@ -202,10 +351,16 @@ export function extractValidatorProvenancedImports(ast, adapter) {
  *   6. default parameter with DB value
  *   7. class field initialized with DB value
  *   8. type annotation with known DB type
+ * @param adapter
+ * @param ast
+ * @param seedMap
+ * @param sourceCode
+ * @returns
  */
 export function propagateProvenance(ast, adapter, sourceCode, seedMap) {
     // Work on a copy so we can add newly-provenanced identifiers during the walk
     const provenanceMap = new Map(seedMap);
+    const ctx = { adapter, sourceCode, provenanceMap };
     // Keep iterating until no new identifiers are discovered (handles chains)
     let changed = true;
     let iterations = 0;
@@ -214,100 +369,8 @@ export function propagateProvenance(ast, adapter, sourceCode, seedMap) {
         changed = false;
         iterations++;
         walkAST(ast.root, (node, parent) => {
-            // ── Rule 1 & 2 & 3 & 8: variable declarations ──
-            if (node.type === 'variable_declarator') {
-                const { nameNode, valueNode, typeAnnotationNode } = splitVariableDeclarator(node, adapter);
-                if (!nameNode)
-                    return;
-                // Rule 8: type annotation — let x: D1Database
-                if (typeAnnotationNode && nameNode.type === 'identifier') {
-                    const typeText = adapter.getNodeText(typeAnnotationNode, sourceCode).trim();
-                    if (DB_TYPES.has(typeText)) {
-                        const name = adapter.getNodeText(nameNode, sourceCode);
-                        if (!provenanceMap.has(name)) {
-                            provenanceMap.set(name, {
-                                identifier: name,
-                                reason: 'type',
-                                source: `type annotation ${typeText}`,
-                                chain: [],
-                            });
-                            changed = true;
-                        }
-                        // Type-provenanced names count as DB-provenanced for further propagation
-                    }
-                }
-                if (valueNode) {
-                    const propagated = tryPropagateFromExpression(valueNode, adapter, sourceCode, provenanceMap);
-                    if (propagated) {
-                        // Extract the variable name(s) from the name node
-                        const varNames = extractPatternNames(nameNode, adapter, sourceCode);
-                        for (const varName of varNames) {
-                            if (!provenanceMap.has(varName)) {
-                                provenanceMap.set(varName, {
-                                    identifier: varName,
-                                    reason: 'propagation',
-                                    source: propagated.source,
-                                    chain: [...propagated.chain, propagated.identifier],
-                                });
-                                changed = true;
-                            }
-                        }
-                    }
-                }
-                return;
-            }
-            // ── Rule 6: default parameters ──
-            if (node.type === 'assignment_pattern' &&
-                parent?.type === 'formal_parameters') {
-                const children = adapter.getChildren(node);
-                // assignment_pattern has [left, right]
-                if (children.length >= 2) {
-                    const leftNode = children[0];
-                    const rightNode = children[1];
-                    if (leftNode.type === 'identifier') {
-                        const paramName = adapter.getNodeText(leftNode, sourceCode);
-                        const propagated = tryPropagateFromExpression(rightNode, adapter, sourceCode, provenanceMap);
-                        if (propagated && !provenanceMap.has(paramName)) {
-                            provenanceMap.set(paramName, {
-                                identifier: paramName,
-                                reason: 'propagation',
-                                source: `default parameter = ${propagated.source}`,
-                                chain: [...propagated.chain, propagated.identifier],
-                            });
-                            changed = true;
-                        }
-                    }
-                }
-                return;
-            }
-            // ── Rule 7: class field initialization ──
-            if (node.type === 'public_field_definition' ||
-                node.type === 'field_definition') {
-                const children = adapter.getChildren(node);
-                // Typically [name, value] or [decorators..., name, value]
-                const nameChild = children.find((c) => c.type === 'property_identifier');
-                const valueChild = children.find((c) => c.type !== 'property_identifier' &&
-                    c.type !== 'decorator' &&
-                    c.type !== 'private' &&
-                    c.type !== 'public' &&
-                    c.type !== 'protected' &&
-                    c.type !== 'static' &&
-                    c.type !== 'readonly' &&
-                    c.type !== 'abstract');
-                if (nameChild && valueChild) {
-                    const fieldName = adapter.getNodeText(nameChild, sourceCode);
-                    const propagated = tryPropagateFromExpression(valueChild, adapter, sourceCode, provenanceMap);
-                    if (propagated && !provenanceMap.has(fieldName)) {
-                        provenanceMap.set(fieldName, {
-                            identifier: fieldName,
-                            reason: 'propagation',
-                            source: `class field initialized from ${propagated.source}`,
-                            chain: [...propagated.chain, propagated.identifier],
-                        });
-                        changed = true;
-                    }
-                }
-                return;
+            if (applyPropagationRule(node, parent, ctx)) {
+                changed = true;
             }
         });
     }
@@ -337,24 +400,9 @@ function tryPropagateFromExpression(node, adapter, sourceCode, provenanceMap) {
     // ── Rule 2: drizzle(env.DB) — call where callee is DB-provenanced ──
     // ── Rule 3: db.prepare(sql) — member expression call on DB receiver ──
     if (node.type === 'call_expression') {
-        // Walk children before arguments to get the callee
-        const calleeNode = getCallExpressionCallee(node, adapter);
-        if (calleeNode) {
-            // Case: simple identifier call — drizzle(...)
-            if (calleeNode.type === 'identifier') {
-                const name = adapter.getNodeText(calleeNode, sourceCode);
-                if (name && provenanceMap.has(name)) {
-                    return provenanceMap.get(name);
-                }
-            }
-            // Case: member expression — db.prepare(...)
-            if (calleeNode.type === 'member_expression') {
-                const receiver = getMemberExpressionReceiver(calleeNode, adapter, sourceCode);
-                if (receiver && provenanceMap.has(receiver)) {
-                    return provenanceMap.get(receiver);
-                }
-            }
-        }
+        const viaCall = tryCallProvenance(node, adapter, sourceCode, provenanceMap);
+        if (viaCall)
+            return viaCall;
     }
     // ── Simple identifier reference (for destructuring sources) ──
     if (node.type === 'identifier') {
@@ -372,6 +420,31 @@ function tryPropagateFromExpression(node, adapter, sourceCode, provenanceMap) {
     }
     return null;
 }
+/**
+ * Rule 2/3: check a call_expression whose callee is either a DB-provenanced
+ * identifier (e.g. `drizzle(...)`) or a member expression on a DB receiver
+ * (e.g. `db.prepare(sql)`).
+ */
+function tryCallProvenance(node, adapter, sourceCode, provenanceMap) {
+    const calleeNode = getCallExpressionCallee(node, adapter);
+    if (!calleeNode)
+        return null;
+    // Case: simple identifier call — drizzle(...)
+    if (calleeNode.type === 'identifier') {
+        const name = adapter.getNodeText(calleeNode, sourceCode);
+        if (name && provenanceMap.has(name)) {
+            return provenanceMap.get(name);
+        }
+    }
+    // Case: member expression — db.prepare(...)
+    if (calleeNode.type === 'member_expression') {
+        const receiver = getMemberExpressionReceiver(calleeNode, adapter, sourceCode);
+        if (receiver && provenanceMap.has(receiver)) {
+            return provenanceMap.get(receiver);
+        }
+    }
+    return null;
+}
 /**
  * Split a variable_declarator into its name, value, and type annotation
  * child nodes.
@@ -425,59 +498,57 @@ function splitVariableDeclarator(node, adapter) {
  */
 function extractPatternNames(node, adapter, sourceCode) {
     const names = [];
-    function collect(node) {
-        if (node.type === 'identifier') {
-            const name = adapter.getNodeText(node, sourceCode);
-            if (name)
-                names.push(name);
-        }
-        else if (node.type === 'object_pattern') {
-            // Each child is a shorthand_property_identifier, pair_pattern, or rest_pattern
-            for (const child of adapter.getChildren(node)) {
-                if (child.type === '{' ||
-                    child.type === '}' ||
-                    child.type === ',') {
-                    continue;
-                }
-                if (child.type === 'shorthand_property_identifier') {
-                    const name = adapter.getNodeText(child, sourceCode);
-                    if (name)
-                        names.push(name);
-                }
-                else if (child.type === 'pair_pattern') {
-                    // pair_pattern children: [property, value]
-                    // Extract from the value side (which might be an identifier or nested pattern)
-                    const pairChildren = adapter.getChildren(child);
-                    if (pairChildren.length >= 2) {
-                        collect(pairChildren[1]);
-                    }
-                }
-                else if (child.type === 'rest_pattern') {
-                    collectChildren(child, adapter, sourceCode, names);
-                }
-                else {
-                    collect(child);
-                }
+    collectPatternNames(node, adapter, sourceCode, names);
+    return names;
+}
+/** Recursively collect identifier names from a destructuring pattern node. */
+function collectPatternNames(node, adapter, sourceCode, names) {
+    if (node.type === 'identifier') {
+        const name = adapter.getNodeText(node, sourceCode);
+        if (name)
+            names.push(name);
+        return;
+    }
+    if (node.type === 'object_pattern') {
+        for (const child of adapter.getChildren(node)) {
+            if (child.type === '{' || child.type === '}' || child.type === ',')
+                continue;
+            if (child.type === 'shorthand_property_identifier') {
+                const name = adapter.getNodeText(child, sourceCode);
+                if (name)
+                    names.push(name);
             }
-        }
-        else if (node.type === 'array_pattern') {
-            for (const child of adapter.getChildren(node)) {
-                if (child.type === '[' || child.type === ']' || child.type === ',') {
-                    continue;
+            else if (child.type === 'pair_pattern') {
+                // pair_pattern children: [property, value] — collect from value side
+                const pairChildren = adapter.getChildren(child);
+                if (pairChildren.length >= 2) {
+                    collectPatternNames(pairChildren[1], adapter, sourceCode, names);
                 }
-                collect(child);
             }
-        }
-        else if (node.type === 'assignment_pattern') {
-            // Default value in destructuring — collect from the left side
-            const children = adapter.getChildren(node);
-            if (children.length >= 1) {
-                collect(children[0]);
+            else if (child.type === 'rest_pattern') {
+                collectChildren(child, adapter, sourceCode, names);
+            }
+            else {
+                collectPatternNames(child, adapter, sourceCode, names);
             }
         }
+        return;
+    }
+    if (node.type === 'array_pattern') {
+        for (const child of adapter.getChildren(node)) {
+            if (child.type === '[' || child.type === ']' || child.type === ',')
+                continue;
+            collectPatternNames(child, adapter, sourceCode, names);
+        }
+        return;
+    }
+    // assignment_pattern — default value in destructuring, collect from left side
+    if (node.type === 'assignment_pattern') {
+        const children = adapter.getChildren(node);
+        if (children.length >= 1) {
+            collectPatternNames(children[0], adapter, sourceCode, names);
+        }
     }
-    collect(node);
-    return names;
 }
 function collectChildren(node, adapter, sourceCode, names) {
     for (const child of adapter.getChildren(node)) {
@@ -510,8 +581,10 @@ function getMemberExpressionReceiver(node, adapter, sourceCode) {
             firstChild.type !== 'property_identifier' && firstChild.type !== 'field_identifier') {
             if (firstChild.type === 'member_expression' ||
                 firstChild.type === 'selector_expression') {
-                current = firstChild;
-                continue;
+                // Compound receiver: env.DB.prepare → receiver is "env.DB", not "env".
+                // Return the full text of the inner member expression so fallback
+                // entries like dbBindingNames: ['env.DB'] match the provenance check.
+                return adapter.getNodeText(firstChild, sourceCode);
             }
             if (firstChild.type === 'identifier') {
                 return adapter.getNodeText(firstChild, sourceCode);
@@ -592,6 +665,11 @@ function walkAST(root, visitor) {
  *
  * This is the main entry point — call once per file before analysis.
  * Combines import extraction, propagation, and mode-based fallback.
+ * @param adapter
+ * @param ast
+ * @param options
+ * @param sourceCode
+ * @returns
  */
 export function buildProvenanceContext(ast, adapter, sourceCode, options) {
     const mode = options.mode;
@@ -608,11 +686,15 @@ export function buildProvenanceContext(ast, adapter, sourceCode, options) {
     // 3. Fallback: in hybrid mode, add identifiers that match name lists
     //    but weren't caught by provenance (R3)
     if (mode === 'hybrid') {
-        dbProvenanced = addNameListFallbacks(dbProvenanced, sourceCode, options.dbReceiverNames ?? [], options.dbBindingNames ?? []);
+        dbProvenanced = addNameListFallbacks(dbProvenanced, sourceCode, {
+            dbReceiverNames: options.dbReceiverNames ?? [],
+            dbBindingNames: options.dbBindingNames ?? [],
+            dbWrapperNames: options.dbWrapperNames ?? [],
+        });
     }
     // 4. In names mode, use ONLY name lists
     if (mode === 'names') {
-        dbProvenanced = buildNamesOnlyProvenance(sourceCode, options.dbReceiverNames ?? [], options.dbBindingNames ?? []);
+        dbProvenanced = buildNamesOnlyProvenance(sourceCode, options.dbReceiverNames ?? [], options.dbBindingNames ?? [], options.dbWrapperNames ?? []);
     }
     return {
         dbProvenanced,
@@ -620,61 +702,63 @@ export function buildProvenanceContext(ast, adapter, sourceCode, options) {
         mode,
     };
 }
-/**
- * Add fallback provenance entries for identifiers that match name lists
- * but weren't caught by the provenance chain (R3 hybrid mode).
- *
- * These entries carry `reason: 'fallback'` — visible in config detection
- * so users can audit and tighten their chains.
- */
-function addNameListFallbacks(provenanceMap, sourceCode, dbReceiverNames, dbBindingNames) {
+function addNameListFallbacks(provenanceMap, sourceCode, nameLists) {
+    const { dbReceiverNames, dbBindingNames, dbWrapperNames } = nameLists;
     const result = new Map(provenanceMap);
-    // Scan for DB receiver names used as identifiers
-    for (const name of dbReceiverNames) {
+    addIdentifierFallbacks(result, sourceCode, dbReceiverNames, 'dbReceiverNames');
+    addBindingFallbacks(result, sourceCode, dbBindingNames);
+    addIdentifierFallbacks(result, sourceCode, dbWrapperNames, 'dbWrapperNames');
+    return result;
+}
+/** Add fallback entries for identifiers that appear in source but lack provenance. */
+function addIdentifierFallbacks(result, sourceCode, names, label) {
+    for (const name of names) {
         if (result.has(name))
             continue; // already provenanced — provenance wins
-        // Check if this name appears as an identifier in the source
         if (identifierAppearsInSource(sourceCode, name)) {
             result.set(name, {
                 identifier: name,
                 reason: 'fallback',
-                source: `name list match: dbReceiverNames contains "${name}"`,
+                source: `name list match: ${label} contains "${name}"`,
                 chain: [],
             });
         }
     }
-    // Scan for binding names like env.DB
-    for (const binding of dbBindingNames) {
-        if (sourceCode.includes(binding)) {
-            // Extract the property after the dot, e.g. "DB" from "env.DB"
-            const dotIdx = binding.lastIndexOf('.');
-            const shortName = dotIdx >= 0 ? binding.substring(dotIdx + 1) : binding;
-            // Also add the full binding path
-            if (!result.has(binding)) {
-                result.set(binding, {
-                    identifier: binding,
-                    reason: 'fallback',
-                    source: `name list match: dbBindingNames contains "${binding}"`,
-                    chain: [],
-                });
-            }
-            if (shortName !== binding && !result.has(shortName)) {
-                result.set(shortName, {
-                    identifier: shortName,
-                    reason: 'fallback',
-                    source: `from binding ${binding}`,
-                    chain: [],
-                });
-            }
+}
+/** Add fallback entries for binding names like `env.DB` (plus their short forms). */
+function addBindingFallbacks(result, sourceCode, bindings) {
+    for (const binding of bindings) {
+        if (!sourceCode.includes(binding))
+            continue;
+        const dotIdx = binding.lastIndexOf('.');
+        const shortName = dotIdx >= 0 ? binding.substring(dotIdx + 1) : binding;
+        if (!result.has(binding)) {
+            result.set(binding, {
+                identifier: binding,
+                reason: 'fallback',
+                source: `name list match: dbBindingNames contains "${binding}"`,
+                chain: [],
+            });
+        }
+        if (shortName !== binding && !result.has(shortName)) {
+            result.set(shortName, {
+                identifier: shortName,
+                reason: 'fallback',
+                source: `from binding ${binding}`,
+                chain: [],
+            });
         }
     }
-    return result;
 }
 /**
  * Build a provenance map using ONLY name lists (for names mode).
  */
-function buildNamesOnlyProvenance(sourceCode, dbReceiverNames, dbBindingNames) {
-    return addNameListFallbacks(new Map(), sourceCode, dbReceiverNames, dbBindingNames);
+function buildNamesOnlyProvenance(sourceCode, dbReceiverNames, dbBindingNames, dbWrapperNames) {
+    return addNameListFallbacks(new Map(), sourceCode, {
+        dbReceiverNames,
+        dbBindingNames,
+        dbWrapperNames,
+    });
 }
 /** Check if an identifier name appears as a standalone identifier in source. */
 function identifierAppearsInSource(sourceCode, name) {
@@ -685,9 +769,6 @@ function identifierAppearsInSource(sourceCode, name) {
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-// ═══════════════════════════════════════════════════════════════════════════
-// Core detection — is this call DB-provenanced?
-// ═══════════════════════════════════════════════════════════════════════════
 /**
  * Determine if a call-expression node's callee is DB-provenanced.
  *
@@ -699,11 +780,15 @@ function escapeRegex(s) {
  *   2. Member expression call → is the receiver DB-provenanced AND is the
  *      method in the DB call method set?
  *   3. ORM patterns → receiver is DB-provenanced and method matches ORM API
+ *
+ * @param node  the call-expression node whose callee is under test
+ * @param query  bundled adapter, source, provenance context, and DB methods
+ * @returns  true if the call's callee resolves to a DB-provenanced target
  */
-export function isDBProvenanced(node, adapter, sourceCode, context, dbCallMethods) {
+export function isDBProvenanced(node, query) {
     if (node.type !== 'call_expression')
         return false;
-    const methods = dbCallMethods ?? DB_CALL_METHODS;
+    const { adapter, sourceCode, context, methods } = query;
     const calleeNode = getCallExpressionCallee(node, adapter);
     if (!calleeNode)
         return false;
@@ -725,7 +810,7 @@ export function isDBProvenanced(node, adapter, sourceCode, context, dbCallMethod
     }
     // Case 2: Member expression — e.g. db.prepare(...)
     if (calleeNode.type === 'member_expression' || calleeNode.type === 'selector_expression') {
-        return isMemberExpressionDBProvenanced(calleeNode, adapter, sourceCode, context, methods);
+        return isMemberExpressionDBProvenanced(calleeNode, query);
     }
     return false;
 }
@@ -736,9 +821,42 @@ export function isDBProvenanced(node, adapter, sourceCode, context, dbCallMethod
  * checks if it's in the provenance context, and verifies
  * the method matches the DB call/ORM API.
  */
-function isMemberExpressionDBProvenanced(node, adapter, sourceCode, context, methods) {
-    // Walk the member expression chain to find the root
-    let rootReceiver = null;
+function isMemberExpressionDBProvenanced(node, query) {
+    const { adapter, sourceCode, context } = query;
+    const rootReceiver = findRootReceiver(node, adapter, sourceCode);
+    if (!rootReceiver)
+        return false;
+    // In names mode, check the method name directly
+    if (context.mode === 'names') {
+        return isDBMethodCall(node, query);
+    }
+    // Check if the root receiver is DB-provenanced.
+    // Compound receivers (e.g. "db.users" or "env.DB") need to match both
+    // the full text (for bindings like "env.DB") and each sub-identifier
+    // (for receivers like "db.users" where "db" is in dbReceiverNames).
+    const matchesProvenance = (r) => {
+        if (context.dbProvenanced.has(r))
+            return true;
+        for (const part of r.split('.')) {
+            if (context.dbProvenanced.has(part))
+                return true;
+        }
+        return false;
+    };
+    if (!matchesProvenance(rootReceiver)) {
+        if (rootReceiver !== 'this')
+            return false;
+        // For `this.xxx`, check if the method chain itself suggests DB usage
+        return isDBMethodOnThis(node, query);
+    }
+    // Check that the method is in the DB call/ORM API
+    return isDBMethodCall(node, query);
+}
+/**
+ * Walk a member/selector expression chain to its root receiver text.
+ * Returns `'this'` for `this.xxx` chains and `null` when no root is found.
+ */
+function findRootReceiver(node, adapter, sourceCode) {
     let current = node;
     while (current.type === 'member_expression' || current.type === 'selector_expression') {
         const children = adapter.getChildren(current);
@@ -746,41 +864,28 @@ function isMemberExpressionDBProvenanced(node, adapter, sourceCode, context, met
         if (!firstChild)
             break;
         if (firstChild.type === 'identifier') {
-            rootReceiver = adapter.getNodeText(firstChild, sourceCode);
-            break;
+            return adapter.getNodeText(firstChild, sourceCode);
         }
         if (firstChild.type === 'member_expression' || firstChild.type === 'selector_expression') {
-            current = firstChild;
-            continue;
+            // Compound receiver: env.DB.prepare → root is "env.DB", not "env".
+            // Returning the full text of the inner member expression ensures
+            // fallback entries match (e.g. dbBindingNames: ['env.DB']).
+            return adapter.getNodeText(firstChild, sourceCode);
         }
         // this.db.prepare → root is a chain on `this`, check `this.xxx`
         if (firstChild.type === 'this' || firstChild.type === 'super') {
-            rootReceiver = 'this';
-            break;
+            return 'this';
         }
         break;
     }
-    if (!rootReceiver)
-        return false;
-    // In names mode, check the method name directly
-    if (context.mode === 'names') {
-        return isDBMethodCall(node, adapter, sourceCode, context, methods);
-    }
-    // Check if the root receiver is DB-provenanced
-    if (!context.dbProvenanced.has(rootReceiver)) {
-        if (rootReceiver !== 'this')
-            return false;
-        // For `this.xxx`, check if the method chain itself suggests DB usage
-        return isDBMethodOnThis(node, adapter, sourceCode, context, methods);
-    }
-    // Check that the method is in the DB call/ORM API
-    return isDBMethodCall(node, adapter, sourceCode, context, methods);
+    return null;
 }
 /**
  * Check if a call through a member expression uses a DB method
  * (exec, prepare, all, etc.) or an ORM method (find, insert, etc.).
  */
-function isDBMethodCall(node, _adapter, _sourceCode, _context, methods) {
+function isDBMethodCall(node, query) {
+    const { adapter, sourceCode, methods } = query;
     // Walk the member expression chain and check each property
     let current = node;
     while (current.type === 'member_expression' ||
@@ -790,7 +895,7 @@ function isDBMethodCall(node, _adapter, _sourceCode, _context, methods) {
         for (const child of children) {
             if (child.type === 'property_identifier' ||
                 child.type === 'field_identifier') {
-                const propName = _adapter.getNodeText(child, _sourceCode);
+                const propName = adapter.getNodeText(child, sourceCode);
                 const lower = propName.toLowerCase();
                 if (methods.has(lower) || ORM_METHODS.has(lower)) {
                     return true;
@@ -813,7 +918,8 @@ function isDBMethodCall(node, _adapter, _sourceCode, _context, methods) {
  * For `this.xxx.method()` calls — check if the method chain suggests
  * DB access. Used when the receiver is `this` (not directly DB-provenanced).
  */
-function isDBMethodOnThis(node, adapter, sourceCode, _context, methods) {
+function isDBMethodOnThis(node, query) {
+    const { adapter, sourceCode, methods } = query;
     // Walk the chain: this.db.prepare → check if any property matches DB methods
     let current = node;
     while (current.type === 'member_expression' ||
@@ -844,6 +950,9 @@ function isDBMethodOnThis(node, adapter, sourceCode, _context, methods) {
  * Check if an identifier is validator-provenanced (R4 infrastructure).
  *
  * This will be consumed by Spec 15's validator-bypass detection.
+ * @param context
+ * @param identifier
+ * @returns
  */
 export function isValidatorProvenanced(identifier, context) {
     return context.validatorProvenanced.has(identifier);
@@ -860,108 +969,124 @@ export function isValidatorProvenanced(identifier, context) {
  * (b) can be traced back to a provenanced source through assignments.
  *
  * Deferred: full implementation in R2 step.
+ * @param adapter
+ * @param fileAst
+ * @param provenancedSet
+ * @param sourceCode
+ * @returns
  */
 export function inferReceivers(provenancedSet, fileAst, adapter, sourceCode) {
     const inferred = { identifiers: [], evidence: [] };
     const seen = new Set();
     // Step 1: Build an assignment graph — name → source text of initializer
     const assignmentGraph = buildAssignmentGraph(fileAst, adapter, sourceCode);
+    const ctx = {
+        adapter, sourceCode, provenancedSet, assignmentGraph, seen, inferred,
+    };
     // Step 2: Walk all call expressions whose callee is a member expression
-    walkAST(fileAst.root, (node) => {
-        if (node.type !== 'call_expression')
-            return;
-        const callee = getCallExpressionCallee(node, adapter);
-        if (!callee || (callee.type !== 'member_expression' && callee.type !== 'selector_expression'))
-            return;
-        // Extract method name (the property being called)
-        const methodName = extractMemberExpressionProperty(callee, adapter, sourceCode);
-        if (!methodName || !DB_CALL_METHODS.has(methodName.toLowerCase()))
-            return;
-        // Get the receiver identifier
-        const receiver = getMemberExpressionReceiver(callee, adapter, sourceCode);
-        if (!receiver)
-            return;
-        // Already in the provenanced set → skip (already first-class, not inferred)
-        if (provenancedSet.has(receiver))
-            return;
-        // Already added to inferred
-        if (seen.has(receiver))
-            return;
-        // Step 3: Trace receiver through assignment chain to see if it reaches
-        // a provenanced source
-        const traced = traceAssignmentChain(receiver, assignmentGraph, provenancedSet);
-        if (traced.found) {
-            seen.add(receiver);
-            inferred.identifiers.push(receiver);
-            inferred.evidence.push({
-                identifier: receiver,
-                reason: `calls .${methodName}() traced to ${traced.chains[0]} — ${traced.reason}`,
-            });
-        }
-    });
+    walkAST(fileAst.root, (node) => inferReceiverFromCall(node, ctx));
     return inferred;
 }
+/** Infer a receiver from a single call_expression node, if it qualifies. */
+function inferReceiverFromCall(node, ctx) {
+    const { adapter, sourceCode, provenancedSet, assignmentGraph, seen, inferred } = ctx;
+    if (node.type !== 'call_expression')
+        return;
+    const callee = getCallExpressionCallee(node, adapter);
+    if (!callee || (callee.type !== 'member_expression' && callee.type !== 'selector_expression'))
+        return;
+    const methodName = extractMemberExpressionProperty(callee, adapter, sourceCode);
+    if (!methodName || !DB_CALL_METHODS.has(methodName.toLowerCase()))
+        return;
+    const receiver = getMemberExpressionReceiver(callee, adapter, sourceCode);
+    if (!receiver)
+        return;
+    // Already provenanced → first-class, not inferred; already added → skip
+    if (provenancedSet.has(receiver) || seen.has(receiver))
+        return;
+    // Step 3: Trace receiver through assignment chain to a provenanced source
+    const traced = traceAssignmentChain(receiver, assignmentGraph, provenancedSet);
+    if (traced.found) {
+        seen.add(receiver);
+        inferred.identifiers.push(receiver);
+        inferred.evidence.push({
+            identifier: receiver,
+            reason: `calls .${methodName}() traced to ${traced.chains[0]} — ${traced.reason}`,
+        });
+    }
+}
 /**
  * Build a reverse assignment graph from the AST.
  * Maps variable name → the text of its initializer expression.
  * Handles: const/let/var declarations, parameter defaults, class fields.
  */
 function buildAssignmentGraph(ast, adapter, sourceCode) {
-    const graph = new Map();
+    const ctx = {
+        graph: new Map(),
+        adapter,
+        sourceCode,
+    };
     walkAST(ast.root, (node, parent) => {
-        // const/let/var x = <expr>
-        if (node.type === 'variable_declarator') {
-            const { nameNode, valueNode } = splitVariableDeclarator(node, adapter);
-            if (nameNode && valueNode) {
-                const names = extractPatternNames(nameNode, adapter, sourceCode);
-                const valueText = adapter.getNodeText(valueNode, sourceCode);
-                for (const name of names) {
-                    if (!graph.has(name))
-                        graph.set(name, valueText);
-                }
-            }
-            return;
-        }
-        // Parameter defaults: function foo(x = <expr>)
-        if (node.type === 'assignment_pattern' &&
-            parent?.type === 'formal_parameters') {
-            const children = adapter.getChildren(node);
-            if (children.length >= 2) {
-                const leftNode = children[0];
-                const rightNode = children[1];
-                if (leftNode.type === 'identifier') {
-                    const paramName = adapter.getNodeText(leftNode, sourceCode);
-                    const valueText = adapter.getNodeText(rightNode, sourceCode);
-                    if (!graph.has(paramName))
-                        graph.set(paramName, valueText);
-                }
-            }
-            return;
-        }
-        // Class field: fieldName = <expr>
-        if (node.type === 'public_field_definition' ||
-            node.type === 'field_definition') {
-            const children = adapter.getChildren(node);
-            const nameChild = children.find((c) => c.type === 'property_identifier');
-            const valueChild = children.find((c) => c.type !== 'property_identifier' &&
-                c.type !== 'decorator' &&
-                c.type !== 'private' &&
-                c.type !== 'public' &&
-                c.type !== 'protected' &&
-                c.type !== 'static' &&
-                c.type !== 'readonly' &&
-                c.type !== 'abstract' &&
-                c.type !== '=');
-            if (nameChild && valueChild) {
-                const fieldName = adapter.getNodeText(nameChild, sourceCode);
-                const valueText = adapter.getNodeText(valueChild, sourceCode);
-                if (!graph.has(fieldName))
-                    graph.set(fieldName, valueText);
-            }
-            return;
-        }
+        recordVariableDeclarator(node, ctx);
+        recordParameterDefault(node, parent, ctx);
+        recordClassField(node, ctx);
     });
-    return graph;
+    return ctx.graph;
+}
+/** Record `const/let/var x = <expr>` into the assignment graph. */
+function recordVariableDeclarator(node, ctx) {
+    if (node.type !== 'variable_declarator')
+        return;
+    const { nameNode, valueNode } = splitVariableDeclarator(node, ctx.adapter);
+    if (!nameNode || !valueNode)
+        return;
+    const names = extractPatternNames(nameNode, ctx.adapter, ctx.sourceCode);
+    const valueText = ctx.adapter.getNodeText(valueNode, ctx.sourceCode);
+    for (const name of names) {
+        if (!ctx.graph.has(name))
+            ctx.graph.set(name, valueText);
+    }
+}
+/** Record parameter defaults (`function foo(x = <expr>)`) into the graph. */
+function recordParameterDefault(node, parent, ctx) {
+    if (node.type !== 'assignment_pattern' || parent?.type !== 'formal_parameters') {
+        return;
+    }
+    const children = ctx.adapter.getChildren(node);
+    if (children.length < 2)
+        return;
+    const leftNode = children[0];
+    const rightNode = children[1];
+    if (leftNode.type !== 'identifier')
+        return;
+    const paramName = ctx.adapter.getNodeText(leftNode, ctx.sourceCode);
+    const valueText = ctx.adapter.getNodeText(rightNode, ctx.sourceCode);
+    if (!ctx.graph.has(paramName))
+        ctx.graph.set(paramName, valueText);
+}
+/** Record class-field initializers (`fieldName = <expr>`) into the graph. */
+function recordClassField(node, ctx) {
+    if (node.type !== 'public_field_definition' &&
+        node.type !== 'field_definition') {
+        return;
+    }
+    const children = ctx.adapter.getChildren(node);
+    const nameChild = children.find((c) => c.type === 'property_identifier');
+    const valueChild = children.find((c) => c.type !== 'property_identifier' &&
+        c.type !== 'decorator' &&
+        c.type !== 'private' &&
+        c.type !== 'public' &&
+        c.type !== 'protected' &&
+        c.type !== 'static' &&
+        c.type !== 'readonly' &&
+        c.type !== 'abstract' &&
+        c.type !== '=');
+    if (!nameChild || !valueChild)
+        return;
+    const fieldName = ctx.adapter.getNodeText(nameChild, ctx.sourceCode);
+    const valueText = ctx.adapter.getNodeText(valueChild, ctx.sourceCode);
+    if (!ctx.graph.has(fieldName))
+        ctx.graph.set(fieldName, valueText);
 }
 /**
  * Trace a receiver identifier through the assignment graph to see if it
@@ -982,10 +1107,8 @@ function traceAssignmentChain(receiver, assignmentGraph, provenancedSet) {
                 reason: provenancedSet.get(current).source,
             };
         }
-        // Also check if any identifier in the initializer text matches a provenanced source
         const initText = assignmentGraph.get(current);
         if (initText) {
-            // Extract identifiers from the initializer text and check against provenanced set
             const idents = extractTopLevelIdentifiers(initText);
             for (const ident of idents) {
                 if (provenancedSet.has(ident)) {
@@ -998,27 +1121,28 @@ function traceAssignmentChain(receiver, assignmentGraph, provenancedSet) {
                 }
             }
         }
-        // Move to the next link in the chain
         if (!initText || visited.has(initText))
             break;
         visited.add(initText);
-        // Try to find a next identifier to trace
-        const idents = extractTopLevelIdentifiers(initText);
-        let foundNext = false;
-        for (const ident of idents) {
-            if (assignmentGraph.has(ident) && !visited.has(ident)) {
-                chain.push(ident);
-                current = ident;
-                foundNext = true;
-                break;
-            }
-        }
-        if (!foundNext)
+        const next = findNextTraceIdentifier(initText, assignmentGraph, visited);
+        if (!next)
             break;
+        chain.push(next);
+        current = next;
         depth++;
     }
     return { found: false, chains: [], reason: '' };
 }
+/** Find the next assignment-graph identifier to trace, if any. */
+function findNextTraceIdentifier(initText, assignmentGraph, visited) {
+    const idents = extractTopLevelIdentifiers(initText);
+    for (const ident of idents) {
+        if (assignmentGraph.has(ident) && !visited.has(ident)) {
+            return ident;
+        }
+    }
+    return null;
+}
 /**
  * Extract top-level identifier names from an expression text.
  * E.g., "db.prepare(sql)" → ["db"], "getConnection()" → ["getConnection"]