code-auditor-mcp 3.1.0 → 3.4.0

package/dist/analyzers/universal/UniversalDataAccessAnalyzer.js

@@ -4,7 +4,7 @@
  * Analyzes database access patterns and data layer interactions
  */
 import { UniversalAnalyzer } from '../../languages/UniversalAnalyzer.js';
-import { IS_DEV_MODE } from '../../constants.js';
+import { buildProvenanceContext, isDBProvenanced, DB_CALL_METHODS, } from '../provenance.js';
 export const DEFAULT_DATA_ACCESS_CONFIG = {
     checkOrgFilters: true,
     checkSQLInjection: true,
@@ -28,18 +28,22 @@ export const DEFAULT_DATA_ACCESS_CONFIG = {
         'companyId',
         'company_id'
     ],
+    // Spec 21 R6.2: three-tier org-filter detection
+    orgFilterTables: [], // Tier 1: empty — user must declare
+    orgFilterColumns: ['org_id', 'tenant_id', 'organization_id', 'workspace_id'], // Tier 2
+    schemas: [], // Tier 2: schema definitions for column-based inference
     tablePatterns: {
         orm: [
-            /from\s*\(\s*["'`]?(\w+)["'`]?\s*\)/gi,
-            /table\s*[:=]\s*["'`]?(\w+)["'`]?/gi,
-            /\.from\s*\(\s*(\w+)\s*\)/gi, // Handle .from(users) where users is a variable
-            /join\s*\(\s*(\w+)\s*,/gi, // Handle joins
-            /leftJoin\s*\(\s*(\w+)\s*,/gi,
-            /rightJoin\s*\(\s*(\w+)\s*,/gi,
-            /innerJoin\s*\(\s*(\w+)\s*,/gi
+            /from\s*\(\s*["'`]?([\p{L}\p{N}_]+)["'`]?\s*\)/giu,
+            /table\s*[:=]\s*["'`]?([\p{L}\p{N}_]+)["'`]?/giu,
+            /\.from\s*\(\s*([\p{L}\p{N}_]+)\s*\)/giu, // Handle .from(users) where users is a variable
+            /join\s*\(\s*([\p{L}\p{N}_]+)\s*,/giu, // Handle joins
+            /leftJoin\s*\(\s*([\p{L}\p{N}_]+)\s*,/giu,
+            /rightJoin\s*\(\s*([\p{L}\p{N}_]+)\s*,/giu,
+            /innerJoin\s*\(\s*([\p{L}\p{N}_]+)\s*,/giu
         ],
-        sql: [/FROM\s+["'`]?(\w+)["'`]?/gi, /JOIN\s+["'`]?(\w+)["'`]?/gi, /UPDATE\s+["'`]?(\w+)["'`]?/gi],
-        queryBuilder: [/\.from\s*\(\s*["'`]?(\w+)["'`]?\s*\)/gi]
+        sql: [/FROM\s+["'`]?([\p{L}\p{N}_]+)["'`]?/giu, /JOIN\s+["'`]?([\p{L}\p{N}_]+)["'`]?/giu, /UPDATE\s+["'`]?([\p{L}\p{N}_]+)["'`]?/giu],
+        queryBuilder: [/\.from\s*\(\s*["'`]?([\p{L}\p{N}_]+)["'`]?\s*\)/giu]
     },
     performanceThresholds: {
         complexQueryCount: 3,
@@ -58,26 +62,33 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
     async analyzeAST(ast, adapter, config, sourceCode) {
         const violations = [];
         const finalConfig = { ...DEFAULT_DATA_ACCESS_CONFIG, ...config };
-        if (IS_DEV_MODE) {
-            console.error('[DEBUG] Data access config merge:', {
-                defaultPatterns: DEFAULT_DATA_ACCESS_CONFIG.organizationPatterns,
-                inputConfig: config,
-                finalPatterns: finalConfig.organizationPatterns
-            });
-        }
+        // Spec 21: Build provenance context for this file (R1 — provenance-primary detection)
+        const detectionMode = config.detection?.mode ?? 'hybrid';
+        const schemaConfig = config;
+        const p0 = performance.now();
+        const provenanceContext = buildProvenanceContext(ast, adapter, sourceCode, {
+            mode: detectionMode,
+            dbReceiverNames: schemaConfig.dbReceiverNames ?? ['db', 'database', 'sql', 'stmt', 'connection', 'pool', 'client'],
+            dbBindingNames: schemaConfig.dbBindingNames ?? ['env.DB'],
+            dbCallMethods: schemaConfig.dbCallMethods ?? [...DB_CALL_METHODS],
+        });
+        const timingAcc = schemaConfig._provenanceTiming;
+        if (timingAcc)
+            timingAcc.totalMs += performance.now() - p0;
         // Check imports for database libraries
         const imports = adapter.extractImports(ast);
         const dbImports = this.mapDatabaseImports(imports, finalConfig);
-        // Find database calls
-        const calls = this.extractDatabaseCalls(ast, adapter, sourceCode, dbImports, finalConfig);
-        // Analyze each call
+        // Find database calls (Spec 21: uses provenance context)
+        const calls = this.extractDatabaseCalls(ast, adapter, sourceCode, dbImports, finalConfig, provenanceContext);
+        // Analyze each call — track symbol ordinals for fingerprint stability
+        const symbolOrdinals = new Map();
         for (const call of calls) {
             const analysis = this.analyzeQuery(call, sourceCode, finalConfig);
             // Check for violations
-            violations.push(...this.checkViolations(call, analysis, ast.filePath, finalConfig));
+            violations.push(...this.checkViolations(call, analysis, ast.filePath, finalConfig, symbolOrdinals));
         }
-        // R4.1: Check for database queries inside loops (N+1 detection)
-        violations.push(...this.checkLoopQueries(ast, adapter, sourceCode, finalConfig));
+        // R4.1: Check for database queries inside loops (N+1 detection, Spec 21: provenance-gated)
+        violations.push(...this.checkLoopQueries(ast, adapter, sourceCode, finalConfig, provenanceContext));
         // Check for general data access patterns
         violations.push(...this.checkGeneralPatterns(ast, adapter, sourceCode, finalConfig));
         return violations;
@@ -99,26 +110,28 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
     /**
      * Extract database calls from AST
      */
-    extractDatabaseCalls(ast, adapter, sourceCode, dbImports, config) {
+    extractDatabaseCalls(ast, adapter, sourceCode, dbImports, config, provenanceContext) {
         const calls = [];
         // Find all relevant nodes
         const allNodes = adapter.findNodes(ast, {
             custom: (node) => {
                 const nodeText = adapter.getNodeText(node, sourceCode);
-                // Check if it's a function call that might be database-related
+                // Check if it's a function call whose callee is DB-related
                 if (this.isFunctionCall(node, adapter)) {
-                    // Check for ORM patterns or database method calls
-                    const dbPatterns = ['select', 'insert', 'update', 'delete', 'from', 'where', 'execute', 'query', 'find', 'aggregate', 'count', 'distinct'];
-                    const hasDbPattern = dbPatterns.some(pattern => nodeText.toLowerCase().includes(pattern));
-                    if (hasDbPattern) {
-                        // Ensure we get the full method call including arguments
-                        // For method calls like db.users.find(...), we want the entire expression
+                    // Spec 21: Use provenance when available, fall back to name-based check
+                    if (provenanceContext) {
+                        if (isDBProvenanced(node, adapter, sourceCode, provenanceContext, DB_CALL_METHODS)) {
+                            return true;
+                        }
+                    }
+                    else if (this.isDBCallee(node, adapter, sourceCode)) {
                         return true;
                     }
                 }
-                // Check if it's a template literal with SQL
+                // Check if it's a template literal with SQL in a DB-call context
                 if (this.isTemplateLiteral(node, adapter)) {
-                    return this.containsSQLKeywords(nodeText);
+                    return this.containsSQLKeywords(nodeText) &&
+                        this.isTemplateInDBCallOrVariableContext(node, adapter, sourceCode, provenanceContext);
                 }
                 // Check if it's a variable declaration with SQL (but not if it contains a template literal)
                 if (this.isVariableAssignment(node, adapter)) {
@@ -171,24 +184,7 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
             if (isSqlQuery || isOrmCall) {
                 const tables = this.extractTables(nodeText, config);
                 const hasOrgFilter = this.hasOrganizationFilter(nodeText, config);
-                // Debug: Log the analysis
-                if (IS_DEV_MODE) {
-                    console.error('[DEBUG] Database call analysis:', {
-                        line: node.location.start.line,
-                        nodeText: nodeText.substring(0, 100),
-                        tables,
-                        hasOrgFilter,
-                        patterns: config.organizationPatterns || []
-                    });
-                }
                 const security = this.checkQuerySecurity(nodeText, config);
-                // Debug: Log extracted tables
-                if (tables.length === 0 && isOrmCall) {
-                    console.error('[DataAccess Debug] No tables extracted from ORM call:', {
-                        line: node.location.start.line,
-                        nodeText: nodeText.substring(0, 100)
-                    });
-                }
                 // Determine the type based on imports or patterns
                 let callType = 'unknown';
                 if (isSqlQuery) {
@@ -212,7 +208,8 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
                     tables,
                     hasOrganizationFilter: hasOrgFilter,
                     hasParameterizedQuery: security.parameterized,
-                    hasSqlInjectionRisk: security.injectionRisk
+                    hasSqlInjectionRisk: security.injectionRisk,
+                    enclosingFunction: this.findEnclosingFunctionName(node, adapter),
                 });
             }
         }
@@ -251,8 +248,15 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
     /**
      * Check for violations in a database call
      */
-    checkViolations(call, analysis, filePath, config) {
+    checkViolations(call, analysis, filePath, config, symbolOrdinals) {
         const violations = [];
+        // Build a stable base symbol key — enclosing function + callee method.
+        // Ordinal added for genuine repeats within the same function.
+        const fnName = call.enclosingFunction ?? 'top-level';
+        const baseSymbol = `${fnName}:${call.method}`;
+        const ordinal = (symbolOrdinals.get(baseSymbol) ?? 0) + 1;
+        symbolOrdinals.set(baseSymbol, ordinal);
+        const symbol = ordinal > 1 ? `${baseSymbol}:${ordinal}` : baseSymbol;
         // Security: SQL Injection Risk
         // Spec 11 (calibration): Detection uses AST-level heuristics (string
         // concatenation in query construction) without type information. Findings
@@ -261,19 +265,19 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
         // rate on ExcAlDraw and Gin corpora to decide whether heuristics should be
         // tightened or severity re-escalated.
         if (config.checkSQLInjection && call.hasSqlInjectionRisk) {
-            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Potential SQL injection risk in ${call.method}. Use parameterized queries.`, 'warning', 'sql-injection-risk'));
+            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Potential SQL injection risk in ${call.method}. Use parameterized queries.`, 'suggestion', 'sql-injection-risk', undefined, symbol));
         }
         // Security: Missing Organization Filter
-        if (config.checkOrgFilters && !call.hasOrganizationFilter && call.tables.length > 0 && this.requiresOrgFilter(call.tables)) {
-            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Query on ${call.tables.join(', ')} missing organization/tenant filter`, 'warning', 'missing-org-filter'));
+        if (config.checkOrgFilters && !call.hasOrganizationFilter && call.tables.length > 0 && this.requiresOrgFilter(call.tables, config)) {
+            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Query on ${call.tables.join(', ')} missing organization/tenant filter`, 'warning', 'missing-org-filter', undefined, symbol));
         }
         // Performance: Complex Query
         if (analysis.performanceRisk === 'high') {
-            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Complex query with ${call.tables.length} tables may have performance issues`, 'warning', 'complex-query'));
+            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Complex query with ${call.tables.length} tables may have performance issues`, 'warning', 'complex-query', undefined, symbol));
         }
         // Performance: Unfiltered Query
         if (!call.hasOrganizationFilter && analysis.performanceRisk === 'medium') {
-            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Unfiltered query on ${call.tables.join(', ')} may cause performance issues`, 'suggestion', 'unfiltered-query'));
+            violations.push(this.createViolation(filePath, { line: call.line, column: call.column }, `Unfiltered query on ${call.tables.join(', ')} may cause performance issues`, 'suggestion', 'unfiltered-query', undefined, symbol));
         }
         return violations;
     }
@@ -290,11 +294,17 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
         const stringNodes = adapter.findNodes(ast, {
             custom: (node) => this.isStringLiteral(node, adapter)
         });
+        const hardcodedOrdinals = new Map();
         for (const node of stringNodes) {
             const text = adapter.getNodeText(node, sourceCode);
             if (this.isConnectionString(text)) {
+                const fnName = this.findEnclosingFunctionName(node, adapter);
+                const baseSym = `${fnName}:hardcoded-connection`;
+                const count = (hardcodedOrdinals.get(baseSym) ?? 0) + 1;
+                hardcodedOrdinals.set(baseSym, count);
+                const sym = count > 1 ? `${baseSym}:${count}` : baseSym;
                 violations.push(this.createViolation(ast.filePath, node.location.start, 'Hardcoded database connection string detected. Use environment variables. (On Cloudflare Workers/D1, connection strings are injected via bindings.)', 'suggestion', // R7: direct-access → suggestion
-                'hardcoded-connection'));
+                'hardcoded-connection', undefined, sym));
             }
         }
         // Check for direct SQL execution without ORM
@@ -302,7 +312,7 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
         for (const pattern of sqlPatterns) {
             if (pattern.test(sourceCode)) {
                 violations.push(this.createViolation(ast.filePath, { line: 1, column: 1 }, 'Direct SQL execution detected. Consider using an ORM or query builder.', 'suggestion', // R7: direct-access → suggestion
-                'direct-sql'));
+                'direct-sql', undefined, 'direct-sql'));
                 break;
             }
         }
@@ -328,6 +338,59 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
         const upperText = text.toUpperCase();
         return sqlKeywords.some(keyword => upperText.includes(keyword));
     }
+    /**
+     * R3.1: Check if a call expression's callee (excluding arguments)
+     * matches database-related patterns. Prevents false positives from
+     * non-DB calls like page.evaluate() whose arguments happen to contain
+     * SQL-like substrings.
+     */
+    isDBCallee(node, adapter, sourceCode) {
+        const children = adapter.getChildren(node);
+        const calleeParts = [];
+        for (const child of children) {
+            if (adapter.getNodeType(child) === 'arguments')
+                break;
+            calleeParts.push(adapter.getNodeText(child, sourceCode));
+        }
+        const calleeText = calleeParts.join('');
+        const dbPatterns = ['select', 'insert', 'update', 'delete', 'from', 'where', 'execute', 'query', 'find', 'aggregate', 'count', 'distinct'];
+        return dbPatterns.some(pattern => calleeText.toLowerCase().includes(pattern));
+    }
+    /**
+     * R3.1: Gate template literal SQL detection by parent context.
+     * Template literals in non-DB sinks (console.log, page.evaluate) must not
+     * trigger sql-injection-risk. Conservative: variable assignments and bare
+     * statements pass the gate (they may flow to a DB call).
+     *
+     * Spec 21: When provenance context is available, uses provenance-based callee
+     * check (conjunctive guard). Falls back to isDBCallee() when no context.
+     */
+    isTemplateInDBCallOrVariableContext(node, adapter, sourceCode, provenanceContext) {
+        const parent = adapter.getParent(node);
+        if (!parent)
+            return false;
+        const parentType = adapter.getNodeType(parent);
+        // Inside arguments of a call expression → check callee is DB-related
+        if (parentType === 'arguments') {
+            const callExpr = adapter.getParent(parent);
+            if (!callExpr || adapter.getNodeType(callExpr) !== 'call_expression')
+                return false;
+            // Spec 21: Use provenance when available
+            if (provenanceContext) {
+                return isDBProvenanced(callExpr, adapter, sourceCode, provenanceContext, DB_CALL_METHODS);
+            }
+            return this.isDBCallee(callExpr, adapter, sourceCode);
+        }
+        // Variable assignment → conservative (may eventually reach a DB call)
+        if (parentType === 'binary_expression' || parentType === 'variable_declarator' || parentType === 'variable_declaration') {
+            return true;
+        }
+        // Statement-level or program-level → conservative
+        if (parentType === 'expression_statement' || parentType === 'program') {
+            return true;
+        }
+        return false;
+    }
     isOrmPattern(text) {
         // Common ORM method patterns
         const ormPatterns = [
@@ -381,7 +444,7 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
         });
         // Additional check for common ORM patterns that might be missed
         // Handle patterns like db.select().from(users) where 'users' is a variable
-        const ormVariablePattern = /\.from\s*\(\s*([a-zA-Z_]\w*)\s*\)/g;
+        const ormVariablePattern = /\.from\s*\(\s*([\p{L}_][\p{L}\p{N}_]*)\s*\)/gu;
         const ormMatches = text.matchAll(ormVariablePattern);
         for (const match of ormMatches) {
             if (match[1] && !match[1].includes('"') && !match[1].includes("'")) {
@@ -389,7 +452,7 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
             }
         }
         // Handle patterns like db.users.find() or db.orders.findOne()
-        const dbTablePattern = /db\.([a-zA-Z_]\w*)\.\w+\s*\(/g;
+        const dbTablePattern = /db\.([\p{L}_][\p{L}\p{N}_]*)\.\p{L}[\p{L}\p{N}_]*\s*\(/gu;
         const dbMatches = text.matchAll(dbTablePattern);
         for (const match of dbMatches) {
             if (match[1]) {
@@ -401,33 +464,17 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
     hasOrganizationFilter(text, config) {
         const patterns = config.organizationPatterns || [];
         const lowerText = text.toLowerCase();
-        if (IS_DEV_MODE) {
-            console.error('[DEBUG] hasOrganizationFilter called with:', {
-                text: text.substring(0, 100),
-                patternsFromConfig: patterns,
-                patternsLength: patterns.length
-            });
-        }
         // If no patterns provided, check for hardcoded common patterns as fallback
         const fallbackPatterns = patterns.length === 0 ? [
             'organizationid', 'organization_id', 'orgid', 'org_id',
             'tenantid', 'tenant_id', 'companyid', 'company_id'
         ] : patterns;
-        if (IS_DEV_MODE) {
-            console.error('[DEBUG] Using fallback patterns:', fallbackPatterns);
-        }
         // Check for simple pattern matches first
         const hasSimpleMatch = fallbackPatterns.some(pattern => {
             const match = lowerText.includes(pattern.toLowerCase());
-            if (IS_DEV_MODE) {
-                console.error(`[DEBUG] Pattern "${pattern}" -> "${pattern.toLowerCase()}" in "${lowerText}": ${match}`);
-            }
             return match;
         });
         if (hasSimpleMatch) {
-            if (IS_DEV_MODE) {
-                console.error('[DEBUG] Found simple match, returning true');
-            }
             return true;
         }
         // Enhanced pattern matching for object properties and SQL WHERE clauses
@@ -456,15 +503,6 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
                 return true;
             }
         }
-        // Debug logging
-        if (IS_DEV_MODE) {
-            console.error('[DEBUG] hasOrganizationFilter check:', {
-                text: text.substring(0, 150),
-                patterns,
-                fallbackPatterns,
-                hasFilter: false
-            });
-        }
         return false;
     }
     checkQuerySecurity(text, config) {
@@ -482,23 +520,60 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
         ];
         const configPatterns = config.securityPatterns?.sqlInjectionRisks || [];
         const allPatterns = [...sqlInjectionPatterns, ...configPatterns];
-        const injectionRisk = allPatterns.some(pattern => text.includes(pattern)) &&
+        const injectionRisk = !parameterized &&
+            allPatterns.some(pattern => text.includes(pattern)) &&
             this.containsSQLKeywords(text);
         return { parameterized, injectionRisk };
     }
     extractMethodName(node, adapter, sourceCode) {
         const text = adapter.getNodeText(node, sourceCode);
-        const match = text.match(/(\w+)\s*\(/);
+        const match = text.match(/([\p{L}\p{N}_]+)\s*\(/u);
         return match ? match[1] : 'unknown';
     }
-    requiresOrgFilter(tables) {
-        // Tables that typically need organization filtering
-        const orgTables = ['users', 'projects', 'orders', 'customers', 'accounts', 'teams'];
+    /**
+     * Spec 21 R6.2: Three-tier org-filter detection.
+     *
+     * Tier 1 (config-primary): `orgFilterTables` — the user's explicit declaration
+     *   of which tables are multi-tenant. Tenancy is policy; this is the
+     *   declaration of record.
+     *
+     * Tier 2 (usage-inference secondary): A table requires the filter if the
+     *   project's own corpus shows it scoped — i.e., a column matching
+     *   `orgFilterColumns` (default: org_id/tenant_id/organization_id/workspace_id)
+     *   exists on it in the schema definitions in config.
+     *   This is what makes non-English table names (e.g., 注文) detectable
+     *   with zero explicit orgFilterTables declaration.
+     *
+     * Tier 3 (fallback): English table list retained as defaults, evidence-tagged
+     *   `fallback` like every other name list in Spec 21.
+     */
+    requiresOrgFilter(tables, config) {
+        const orgFilterTables = config.orgFilterTables ?? [];
+        const orgFilterColumns = config.orgFilterColumns ?? ['org_id', 'tenant_id', 'organization_id', 'workspace_id'];
+        const schemas = config.schemas ?? [];
+        const fallbackOrgTables = ['users', 'projects', 'orders', 'customers', 'accounts', 'teams'];
+        // Build a lookup set of tables from schema definitions that have an
+        // org-filter column — this is the usage-inference tier.
+        const schemaOrgTables = new Set();
+        for (const schema of schemas) {
+            for (const table of schema.tables) {
+                if (table.columns.some(c => orgFilterColumns.includes(c.name.toLowerCase()))) {
+                    schemaOrgTables.add(table.name.toLowerCase());
+                }
+            }
+        }
         return tables.some(table => {
-            // Handle both actual table names and variable names that likely represent tables
-            const tableName = table.toLowerCase();
-            // Check exact match or if the table variable name matches (e.g., 'users' variable for 'users' table)
-            return orgTables.includes(tableName) || orgTables.some(orgTable => tableName === orgTable);
+            const tableLower = table.toLowerCase();
+            // Tier 1: config-primary — explicit user declaration
+            if (orgFilterTables.some(t => t.toLowerCase() === tableLower)) {
+                return true;
+            }
+            // Tier 2: schema-based inference — table has an org-filter column
+            if (schemaOrgTables.has(tableLower)) {
+                return true;
+            }
+            // Tier 3: English fallback
+            return fallbackOrgTables.includes(tableLower);
         });
     }
     isStringLiteral(node, adapter) {
@@ -519,14 +594,16 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
      * R4.1: Find database queries inside loops and flag them as N+1 risks.
      * Each finding carries the query call location (never line 1).
      */
-    checkLoopQueries(ast, adapter, sourceCode, config) {
+    checkLoopQueries(ast, adapter, sourceCode, config, provenanceContext) {
         const violations = [];
-        // Find all nodes that look like database calls
+        // Find all nodes that look like database calls (Spec 21: provenance-gated)
         const dbNodes = adapter.findNodes(ast, {
-            custom: (node) => this.isDbCallNode(node, adapter, sourceCode),
+            custom: (node) => this.isDbCallNode(node, adapter, sourceCode, provenanceContext),
         });
-        // Track reported line+loop combos to avoid duplicates
+        // Track reported line+loop combos to avoid duplicates (runtime dedup only)
         const reported = new Set();
+        // Track symbol ordinals per enclosing function for fingerprint stability
+        const loopOrdinals = new Map();
         for (const node of dbNodes) {
             const nodeText = adapter.getNodeText(node, sourceCode);
             if (!nodeText || nodeText.trim().length < 10)
@@ -541,6 +618,12 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
             if (reported.has(dedupKey))
                 continue;
             reported.add(dedupKey);
+            // Stable fingerprint symbol: enclosing function + ordinal
+            const enclosingFn = this.findEnclosingFunctionName(node, adapter);
+            const baseSym = `${enclosingFn}:loop-query`;
+            const count = (loopOrdinals.get(baseSym) ?? 0) + 1;
+            loopOrdinals.set(baseSym, count);
+            const sym = count > 1 ? `${baseSym}:${count}` : baseSym;
             // R4.2: Nested-loop attribution
             const depthMsg = loopInfo.depth > 1
                 ? ` (nested ${loopInfo.depth} levels deep)`
@@ -549,7 +632,7 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
             `Database query inside loop${depthMsg} ` +
                 `(loop at line ${loopInfo.loopNode.location.start.line}). ` +
                 `This may cause N+1 performance issues. Consider batching queries or using a join.`, 'warning', // R7: loop-query → warning
-            'loop-query'));
+            'loop-query', undefined, sym));
         }
         return violations;
     }
@@ -557,16 +640,35 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
      * R4.1: Determine if a node is a database call expression.
      * Lightweight check — reused from extractDatabaseCalls logic.
      */
-    isDbCallNode(node, adapter, sourceCode) {
+    /**
+     * R4.1: Determine if a node is a database call expression.
+     * Spec 21: When provenance context is available, uses provenance-based detection
+     * (conjunctive guard — never name alone). In names mode or without context,
+     * falls back to the legacy dbPatterns text match.
+     */
+    isDbCallNode(node, adapter, sourceCode, provenanceContext) {
+        // Spec 21: Provenance-first detection when context is available
+        if (provenanceContext && provenanceContext.mode !== 'names') {
+            // In provenance or hybrid mode, use provenance check
+            if (this.isFunctionCall(node, adapter)) {
+                if (isDBProvenanced(node, adapter, sourceCode, provenanceContext, DB_CALL_METHODS)) {
+                    return true;
+                }
+            }
+            // Template literal with SQL keywords — syntax check, no name involved
+            if (this.isTemplateLiteral(node, adapter)) {
+                return this.containsSQLKeywords(adapter.getNodeText(node, sourceCode));
+            }
+            return false;
+        }
+        // Legacy fallback: name-based matching for names mode / no context
         const nodeText = adapter.getNodeText(node, sourceCode);
-        // Call-expression with DB patterns
         if (this.isFunctionCall(node, adapter)) {
             const dbPatterns = ['select', 'insert', 'update', 'delete', 'from', 'where', 'execute', 'query', 'find', 'aggregate', 'count', 'distinct'];
             if (dbPatterns.some(pattern => nodeText.toLowerCase().includes(pattern))) {
                 return true;
             }
         }
-        // Template literal with SQL keywords
         if (this.isTemplateLiteral(node, adapter)) {
             return this.containsSQLKeywords(nodeText);
         }
@@ -653,5 +755,59 @@ export class UniversalDataAccessAnalyzer extends UniversalAnalyzer {
         }
         return '';
     }
+    /**
+     * Walk the parent chain to find the enclosing function/method/arrow name.
+     * Returns 'top-level' if no enclosing function is found.
+     *
+     * Used for stable fingerprint symbols — the enclosing function name is
+     * immune to line drift (Spec 18 Gap 2).
+     */
+    findEnclosingFunctionName(node, adapter) {
+        let current = adapter.getParent(node);
+        while (current) {
+            const type = adapter.getNodeType(current);
+            // Arrow functions, function declarations, function expressions
+            if (type === 'arrow_function' ||
+                type === 'function_declaration' ||
+                type === 'function_expression' ||
+                type === 'generator_function_declaration' ||
+                type === 'generator_function_expression') {
+                const name = this.getNodeName(current, adapter);
+                if (name)
+                    return name;
+            }
+            // Method definitions on classes/objects
+            if (type === 'method_definition' || adapter.isMethod(current)) {
+                const name = this.getNodeName(current, adapter);
+                if (name)
+                    return name;
+            }
+            current = adapter.getParent(current);
+        }
+        return 'top-level';
+    }
+    /**
+     * Extract the name/identifier from a function or method AST node.
+     */
+    getNodeName(node, adapter) {
+        // Try named children first
+        if (node.name && typeof node.name === 'string')
+            return node.name;
+        if (node.text && typeof node.text === 'string')
+            return node.text;
+        // Walk children for identifier / property_identifier
+        if (node.children) {
+            for (const child of node.children) {
+                const childType = adapter.getNodeType(child);
+                if (childType === 'identifier' ||
+                    childType === 'property_identifier') {
+                    const name = this.getNodeName(child, adapter);
+                    if (name)
+                        return name;
+                }
+            }
+        }
+        return '';
+    }
 }
 //# sourceMappingURL=UniversalDataAccessAnalyzer.js.map