code-auditor-mcp 4.1.0 → 5.0.1

package/dist/mcp-tools-shared.js

@@ -5,15 +5,15 @@
  * between stdio and HTTP/UI MCP server implementations.
  */
 import { createAuditRunner } from './auditRunner.js';
-import { runAuditDispatch } from './auditRouter.js';
 import { searchFunctions, findDefinition, syncFileIndex } from './codeIndexService.js';
 import { CodeMapGenerator } from './services/CodeMapGenerator.js';
 import { analyzeDocumentation } from './analyzers/documentationAnalyzer.js';
 import { CodeIndexDB } from './codeIndexDB.js';
+import { errorMessage } from './utils/errorMessage.js';
+import { buildDiscoveryQueries, normalizeDialect } from './mcp-tools/discoveryQueries.js';
 import path from 'node:path';
 import chalk from 'chalk';
 import { assertAuditPathExists } from './mcpToolErrors.js';
-import { MCP_DEFAULT_ANALYZERS } from './analyzers/ruleRegistry.js';
 export const tools = [
     // Core Audit Tools
     {
@@ -27,13 +27,6 @@ export const tools = [
                 description: 'The file or directory path to audit (defaults to current directory)',
                 default: process.cwd(),
             },
-            {
-                name: 'analyzers',
-                type: 'array',
-                required: false,
-                description: 'List of analyzers to run (solid, dry, documentation, react, data-access)',
-                default: ['solid', 'dry', 'documentation', 'react', 'data-access'],
-            },
             {
                 name: 'minSeverity',
                 type: 'string',
@@ -119,7 +112,7 @@ export const tools = [
                 name: 'filters',
                 type: 'object',
                 required: false,
-                description: 'Optional filters (language, filePath, dependencies, componentType, entityType, searchMode). Set searchMode to "content" to search within function bodies, "metadata" for names/signatures only, or "both" for combined search',
+                description: 'Optional filters (language, filePath, dependencies, componentType, entityType, searchMode). Set searchMode to "content" to search within function bodies, "metadata" for names/jsDoc/purpose only, or "both" for combined search',
             },
             {
                 name: 'limit',
@@ -208,67 +201,10 @@ export const tools = [
             },
         ],
     },
-    // Analyzer Configuration Tools
-    {
-        name: 'set_analyzer_config',
-        description: 'Set or update analyzer configuration that persists across audit runs',
-        parameters: [
-            {
-                name: 'analyzerName',
-                type: 'string',
-                required: true,
-                description: 'The analyzer to configure (solid, dry, security, etc.)',
-            },
-            {
-                name: 'config',
-                type: 'object',
-                required: true,
-                description: 'Configuration object for the analyzer (e.g., thresholds, rules)',
-            },
-            {
-                name: 'projectPath',
-                type: 'string',
-                required: false,
-                description: 'Optional project path for project-specific config (defaults to global)',
-            },
-        ],
-    },
-    {
-        name: 'get_analyzer_config',
-        description: 'Get current configuration for an analyzer',
-        parameters: [
-            {
-                name: 'analyzerName',
-                type: 'string',
-                required: false,
-                description: 'Specific analyzer name, or omit to get all configs',
-            },
-            {
-                name: 'projectPath',
-                type: 'string',
-                required: false,
-                description: 'Optional project path to get project-specific config',
-            },
-        ],
-    },
-    {
-        name: 'reset_analyzer_config',
-        description: 'Reset analyzer configuration to defaults',
-        parameters: [
-            {
-                name: 'analyzerName',
-                type: 'string',
-                required: false,
-                description: 'Specific analyzer to reset, or omit to reset all',
-            },
-            {
-                name: 'projectPath',
-                type: 'string',
-                required: false,
-                description: 'Optional project path to reset only project-specific config',
-            },
-        ],
-    },
+    // Analyzer-config tooling is removed in 5.0.0 (Spec 68 §14). The three flat
+    // `set_analyzer_config` / `get_analyzer_config` / `reset_analyzer_config`
+    // tools are gone; their get/set/reset shape survives as the `config` tool's
+    // actions in mcp.ts, the single registered config surface.
     {
         name: 'get_code_map_section',
         description: 'Retrieve a specific section of a previously generated code map',
@@ -308,7 +244,7 @@ export const tools = [
                 name: 'databaseType',
                 type: 'string',
                 required: true,
-                enum: ['postgresql', 'mysql', 'sqlite', 'sqlserver', 'oracle'],
+                enum: ['postgresql', 'mysql', 'sqlite'],
                 description: 'Type of database to generate queries for',
             },
             {
@@ -450,13 +386,6 @@ export const uiTools = [
                 description: 'Path to audit',
                 default: '.',
             },
-            {
-                name: 'analyzers',
-                type: 'array',
-                required: false,
-                description: 'Analyzers to run',
-                default: ['solid', 'dry', 'documentation', 'react', 'data-access'],
-            },
             {
                 name: 'minSeverity',
                 type: 'string',
@@ -481,10 +410,106 @@ export const uiTools = [
         ],
     },
 ];
+/**
+ * After a full audit, optionally sync the discovered functions into the code
+ * index and generate a paginated code map. Shared verbatim by `handleAudit` and
+ * `handleAuditHealth` — the two callers differ only in the code-map `maxDepth`
+ * (the full audit uses 10, the health check a smaller 8) and in how they format
+ * the returned `indexingResult`/`codeMapResult` into their response bodies.
+ *
+ * @param auditResult - The completed audit whose metadata holds the file→function map.
+ * @param auditPath - The audited path, passed through to the code-map generator.
+ * @param indexFunctions - Whether function indexing was requested.
+ * @param generateCodeMap - Whether code-map generation was requested.
+ * @param maxDepth - Maximum code-map depth (differs between the two callers).
+ * @returns The indexing and code-map results (null for any skipped step).
+ */
+async function runIndexingAndCodeMap(auditResult, auditPath, indexFunctions, generateCodeMap, maxDepth) {
+    // Handle function indexing if enabled and functions were collected
+    let indexingResult = null;
+    if (indexFunctions && auditResult.metadata.fileToFunctionsMap) {
+        try {
+            const syncStats = { added: 0, updated: 0, removed: 0 };
+            // Sync each file's functions to handle additions, updates, and removals
+            for (const [filePath, functions] of Object.entries(auditResult.metadata.fileToFunctionsMap)) {
+                const fileStats = await syncFileIndex(filePath, functions);
+                syncStats.added += fileStats.added;
+                syncStats.updated += fileStats.updated;
+                syncStats.removed += fileStats.removed;
+            }
+            indexingResult = {
+                success: true,
+                registered: syncStats.added + syncStats.updated,
+                failed: 0,
+                syncStats
+            };
+            console.error(chalk.blue('[INFO]'), `Synced functions: ${syncStats.added} added, ${syncStats.updated} updated, ${syncStats.removed} removed`);
+        }
+        catch (error) {
+            console.error(chalk.yellow('[WARN]'), 'Failed to sync functions:', error);
+        }
+    }
+    // Generate code map if requested and functions were indexed
+    let codeMapResult = null;
+    if (generateCodeMap && indexingResult && indexingResult.success) {
+        try {
+            const mapGenerator = new CodeMapGenerator();
+            const mapOptions = {
+                includeComplexity: true,
+                includeDocumentation: true,
+                includeDependencies: true,
+                includeUsage: false,
+                groupByDirectory: true,
+                maxDepth,
+                showUnusedImports: true,
+                minComplexity: 7,
+            };
+            // Generate documentation metrics
+            let documentation = undefined;
+            try {
+                const files = Object.keys(auditResult.metadata.fileToFunctionsMap || {});
+                if (files.length > 0) {
+                    const docResult = await analyzeDocumentation(files);
+                    documentation = docResult.metrics;
+                }
+            }
+            catch (docError) {
+                console.error(chalk.yellow('[WARN]'), 'Failed to analyze documentation:', docError);
+            }
+            // Use paginated code map generation
+            const paginatedResult = await mapGenerator.generatePaginatedCodeMap(auditPath, {
+                ...mapOptions,
+                includeDocumentation: !!documentation
+            });
+            codeMapResult = {
+                success: true,
+                mapId: paginatedResult.mapId,
+                summary: paginatedResult.summary,
+                quickPreview: paginatedResult.quickPreview,
+                sections: paginatedResult.summary.sectionsAvailable,
+                documentationCoverage: documentation?.coverageScore
+            };
+            console.error(chalk.blue('[INFO]'), `Generated paginated code map: ${paginatedResult.summary.stats.totalFiles} files, ${paginatedResult.summary.totalSections} sections`);
+        }
+        catch (error) {
+            console.error(chalk.yellow('[WARN]'), 'Failed to generate code map:', error);
+            codeMapResult = {
+                success: false,
+                error: error instanceof Error ? error.message : 'Failed to generate code map'
+            };
+        }
+    }
+    return { indexingResult, codeMapResult };
+}
 /**
  * Shared tool handler implementations
  */
 export class ToolHandlers {
+    /**
+     * Run a full audit on a path and return the formatted MCP result.
+     * @param args - The tool arguments (path, minSeverity, indexFunctions, etc.).
+     * @returns The audit summary, violations, and optional indexing/code-map results.
+     */
     static async handleAudit(args) {
         const auditPath = path.resolve(args.path || process.cwd());
         const indexFunctions = args.indexFunctions !== false; // Default true
@@ -493,7 +518,7 @@ export class ToolHandlers {
         // Get stored analyzer configs from database
         const db = CodeIndexDB.getInstance();
         await db.initialize();
-        const storedConfigs = await db.getAllAnalyzerConfigs(auditPath);
+        const storedConfigs = await db.analyzerConfig.getAllAnalyzerConfigs(auditPath);
         // Merge stored configs with any provided configs
         const analyzerConfigs = {
             ...storedConfigs,
@@ -501,92 +526,16 @@ export class ToolHandlers {
         };
         const options = {
             projectRoot: isFile ? path.dirname(auditPath) : auditPath,
-            enabledAnalyzers: args.analyzers || ['solid', 'dry', 'documentation', 'react', 'data-access'],
             minSeverity: (args.minSeverity || 'high'),
             verbose: false,
             indexFunctions,
             ...(isFile && { includePaths: [auditPath] }),
             ...(Object.keys(analyzerConfigs).length > 0 && { analyzerConfigs }),
         };
-        // Route through the single audit entry point. Whether `.go` files route to
-        // the Go subprocess or fall through to the TypeScript pipeline is decided
-        // in one place (`runAuditDispatch`), shared with the CLI — not re-detected
-        // here as a second copy that can drift from the CLI.
-        const auditResult = await runAuditDispatch(options);
-        // Handle function indexing if enabled and functions were collected
-        let indexingResult = null;
-        if (indexFunctions && auditResult.metadata.fileToFunctionsMap) {
-            try {
-                const syncStats = { added: 0, updated: 0, removed: 0 };
-                // Sync each file's functions to handle additions, updates, and removals
-                for (const [filePath, functions] of Object.entries(auditResult.metadata.fileToFunctionsMap)) {
-                    const fileStats = await syncFileIndex(filePath, functions);
-                    syncStats.added += fileStats.added;
-                    syncStats.updated += fileStats.updated;
-                    syncStats.removed += fileStats.removed;
-                }
-                indexingResult = {
-                    success: true,
-                    registered: syncStats.added + syncStats.updated,
-                    failed: 0,
-                    syncStats
-                };
-                console.error(chalk.blue('[INFO]'), `Synced functions: ${syncStats.added} added, ${syncStats.updated} updated, ${syncStats.removed} removed`);
-            }
-            catch (error) {
-                console.error(chalk.yellow('[WARN]'), 'Failed to sync functions:', error);
-            }
-        }
-        // Generate code map if requested and functions were indexed
-        let codeMapResult = null;
-        if (generateCodeMap && indexingResult && indexingResult.success) {
-            try {
-                const mapGenerator = new CodeMapGenerator();
-                const mapOptions = {
-                    includeComplexity: true,
-                    includeDocumentation: true,
-                    includeDependencies: true,
-                    includeUsage: false,
-                    groupByDirectory: true,
-                    maxDepth: 10,
-                    showUnusedImports: true,
-                    minComplexity: 7,
-                };
-                // Generate documentation metrics
-                let documentation = undefined;
-                try {
-                    const files = Object.keys(auditResult.metadata.fileToFunctionsMap || {});
-                    if (files.length > 0) {
-                        const docResult = await analyzeDocumentation(files);
-                        documentation = docResult.metrics;
-                    }
-                }
-                catch (docError) {
-                    console.error(chalk.yellow('[WARN]'), 'Failed to analyze documentation:', docError);
-                }
-                // Use paginated code map generation
-                const paginatedResult = await mapGenerator.generatePaginatedCodeMap(auditPath, {
-                    ...mapOptions,
-                    includeDocumentation: !!documentation
-                });
-                codeMapResult = {
-                    success: true,
-                    mapId: paginatedResult.mapId,
-                    summary: paginatedResult.summary,
-                    quickPreview: paginatedResult.quickPreview,
-                    sections: paginatedResult.summary.sectionsAvailable,
-                    documentationCoverage: documentation?.coverageScore
-                };
-                console.error(chalk.blue('[INFO]'), `Generated paginated code map: ${paginatedResult.summary.stats.totalFiles} files, ${paginatedResult.summary.totalSections} sections`);
-            }
-            catch (error) {
-                console.error(chalk.yellow('[WARN]'), 'Failed to generate code map:', error);
-                codeMapResult = {
-                    success: false,
-                    error: error instanceof Error ? error.message : 'Failed to generate code map'
-                };
-            }
-        }
+        // Route through the single audit entry point shared with the CLI.
+        const auditResult = await createAuditRunner(options).run();
+        // Handle function indexing + code-map generation (shared with the health check)
+        const { indexingResult, codeMapResult } = await runIndexingAndCodeMap(auditResult, auditPath, indexFunctions, generateCodeMap, 10);
         // Format for MCP
         return {
             summary: {
@@ -605,6 +554,11 @@ export class ToolHandlers {
             ...(codeMapResult && { codeMap: codeMapResult }),
         };
     }
+    /**
+     * Run a quick health check and return key metrics with a pass/fail status.
+     * @param args - The tool arguments (path, threshold, indexFunctions, etc.).
+     * @returns The health score, threshold, and pass/fail status.
+     */
     static async handleAuditHealth(args) {
         const auditPath = path.resolve(args.path || process.cwd());
         await assertAuditPathExists(auditPath);
@@ -614,7 +568,7 @@ export class ToolHandlers {
         // Get stored analyzer configs from database
         const db = CodeIndexDB.getInstance();
         await db.initialize();
-        const storedConfigs = await db.getAllAnalyzerConfigs(auditPath);
+        const storedConfigs = await db.analyzerConfig.getAllAnalyzerConfigs(auditPath);
         // Merge stored configs with any provided configs
         const analyzerConfigs = {
             ...storedConfigs,
@@ -622,7 +576,6 @@ export class ToolHandlers {
         };
         const runner = createAuditRunner({
             projectRoot: auditPath,
-            enabledAnalyzers: [...MCP_DEFAULT_ANALYZERS],
             minSeverity: 'high',
             verbose: false,
             indexFunctions,
@@ -630,80 +583,8 @@ export class ToolHandlers {
         });
         const auditResult = await runner.run();
         const healthScore = ToolHandlers.calculateHealthScore(auditResult);
-        // Handle function indexing if enabled and functions were collected
-        let indexingResult = null;
-        if (indexFunctions && auditResult.metadata.fileToFunctionsMap) {
-            try {
-                const syncStats = { added: 0, updated: 0, removed: 0 };
-                // Sync each file's functions to handle additions, updates, and removals
-                for (const [filePath, functions] of Object.entries(auditResult.metadata.fileToFunctionsMap)) {
-                    const fileStats = await syncFileIndex(filePath, functions);
-                    syncStats.added += fileStats.added;
-                    syncStats.updated += fileStats.updated;
-                    syncStats.removed += fileStats.removed;
-                }
-                indexingResult = {
-                    success: true,
-                    registered: syncStats.added + syncStats.updated,
-                    failed: 0,
-                    syncStats
-                };
-                console.error(chalk.blue('[INFO]'), `Synced functions: ${syncStats.added} added, ${syncStats.updated} updated, ${syncStats.removed} removed`);
-            }
-            catch (error) {
-                console.error(chalk.yellow('[WARN]'), 'Failed to sync functions:', error);
-            }
-        }
-        // Generate code map if requested and functions were indexed
-        let codeMapResult = null;
-        if (generateCodeMap && indexingResult && indexingResult.success) {
-            try {
-                const mapGenerator = new CodeMapGenerator();
-                const mapOptions = {
-                    includeComplexity: true,
-                    includeDocumentation: true,
-                    includeDependencies: true,
-                    includeUsage: false,
-                    groupByDirectory: true,
-                    maxDepth: 8, // Slightly smaller for health check
-                    showUnusedImports: true,
-                    minComplexity: 7,
-                };
-                // Generate documentation metrics
-                let documentation = undefined;
-                try {
-                    const files = Object.keys(auditResult.metadata.fileToFunctionsMap || {});
-                    if (files.length > 0) {
-                        const docResult = await analyzeDocumentation(files);
-                        documentation = docResult.metrics;
-                    }
-                }
-                catch (docError) {
-                    console.error(chalk.yellow('[WARN]'), 'Failed to analyze documentation:', docError);
-                }
-                // Use paginated code map generation for health check too
-                const paginatedResult = await mapGenerator.generatePaginatedCodeMap(auditPath, {
-                    ...mapOptions,
-                    includeDocumentation: !!documentation
-                });
-                codeMapResult = {
-                    success: true,
-                    mapId: paginatedResult.mapId,
-                    summary: paginatedResult.summary,
-                    quickPreview: paginatedResult.quickPreview,
-                    sections: paginatedResult.summary.sectionsAvailable,
-                    documentationCoverage: documentation?.coverageScore
-                };
-                console.error(chalk.blue('[INFO]'), `Generated paginated code map: ${paginatedResult.summary.stats.totalFiles} files, ${paginatedResult.summary.totalSections} sections`);
-            }
-            catch (error) {
-                console.error(chalk.yellow('[WARN]'), 'Failed to generate code map:', error);
-                codeMapResult = {
-                    success: false,
-                    error: error instanceof Error ? error.message : 'Failed to generate code map'
-                };
-            }
-        }
+        // Handle function indexing + code-map generation (shared with the full audit)
+        const { indexingResult, codeMapResult } = await runIndexingAndCodeMap(auditResult, auditPath, indexFunctions, generateCodeMap, 8);
         return {
             healthScore,
             threshold,
@@ -723,6 +604,11 @@ export class ToolHandlers {
     }
     // Add all other tool handlers here following the same pattern...
     // (I'll include key ones for brevity)
+    /**
+     * Search indexed functions and components with natural language and operators.
+     * @param args - The tool arguments (query, filters, limit, offset).
+     * @returns The matching indexed functions.
+     */
     static async handleSearchCode(args) {
         const query = args.query;
         const filters = args.filters;
@@ -738,6 +624,11 @@ export class ToolHandlers {
             offset
         });
     }
+    /**
+     * Find the exact definition of a named function or component.
+     * @param args - The tool arguments (name, filePath).
+     * @returns The definition, or an error object when not found.
+     */
     static async handleFindDefinition(args) {
         const name = args.name;
         const filePath = args.filePath;
@@ -748,6 +639,11 @@ export class ToolHandlers {
         return definition || { error: 'Function not found' };
     }
     // Schema Management Tool Handlers
+    /**
+     * Generate SQL discovery queries for a database type.
+     * @param args - The tool arguments (databaseType, includeIndexes, etc.).
+     * @returns The generated queries plus instructions for using them.
+     */
     static async handleGenerateSchemaDiscoverySQL(args) {
         const databaseType = args.databaseType;
         const includeIndexes = args.includeIndexes !== false;
@@ -769,6 +665,11 @@ export class ToolHandlers {
             nextStep: "Use create_schema_from_sql_result with the query results"
         };
     }
+    /**
+     * Build and store a schema from SQL discovery result rows.
+     * @param args - The tool arguments (schemaName, databaseType, and result rows).
+     * @returns The stored schema id and stats, or an error object.
+     */
     static async handleCreateSchemaFromSqlResult(args) {
         const schemaName = args.schemaName;
         const databaseType = args.databaseType;
@@ -782,7 +683,7 @@ export class ToolHandlers {
             const schema = ToolHandlers.buildSchemaFromSqlData(schemaName, databaseType, tablesData, columnsData, constraintsData);
             const db = CodeIndexDB.getInstance();
             await db.initialize();
-            const schemaId = await db.storeSchema(schema);
+            const schemaId = await db.schema.storeSchema(schema);
             return {
                 success: true,
                 schemaId,
@@ -798,10 +699,15 @@ export class ToolHandlers {
         catch (error) {
             return {
                 success: false,
-                error: `Failed to create schema from SQL results: ${error instanceof Error ? error.message : 'Unknown error'}`
+                error: `Failed to create schema from SQL results: ${errorMessage(error)}`
             };
         }
     }
+    /**
+     * Add a table to an existing or newly-created schema.
+     * @param args - The tool arguments (schemaName, tableName, columns, databaseType).
+     * @returns The stored schema id and table details, or an error object.
+     */
     static async handleAddTableManually(args) {
         const schemaName = args.schemaName;
         const tableName = args.tableName;
@@ -814,7 +720,7 @@ export class ToolHandlers {
             const db = CodeIndexDB.getInstance();
             await db.initialize();
             // Get existing schema or create new one
-            const existingSchemas = await db.getAllSchemas();
+            const existingSchemas = await db.schema.getAllSchemas();
             let schema = existingSchemas.find(s => s.schema.name === schemaName)?.schema;
             if (!schema) {
                 // Create new schema
@@ -847,7 +753,7 @@ export class ToolHandlers {
             };
             schema.databases[0].tables.push(newTable);
             // Store updated schema
-            const schemaId = await db.storeSchema(schema);
+            const schemaId = await db.schema.storeSchema(schema);
             return {
                 success: true,
                 schemaId,
@@ -859,16 +765,21 @@ export class ToolHandlers {
         catch (error) {
             return {
                 success: false,
-                error: `Failed to add table: ${error instanceof Error ? error.message : 'Unknown error'}`
+                error: `Failed to add table: ${errorMessage(error)}`
             };
         }
     }
+    /**
+     * List all loaded schemas with their metadata.
+     * @param args - The tool arguments (currently unused).
+     * @returns The schemas and aggregate stats, or an error object.
+     */
     static async handleListSchemas(args) {
         try {
             const db = CodeIndexDB.getInstance();
             await db.initialize();
-            const schemas = await db.getAllSchemas();
-            const stats = await db.getSchemaStats();
+            const schemas = await db.schema.getAllSchemas();
+            const stats = await db.schema.getSchemaStats();
             return {
                 schemas: schemas.map(s => ({
                     schemaId: s.schemaId,
@@ -885,10 +796,15 @@ export class ToolHandlers {
         catch (error) {
             return {
                 success: false,
-                error: `Failed to list schemas: ${error instanceof Error ? error.message : 'Unknown error'}`
+                error: `Failed to list schemas: ${errorMessage(error)}`
             };
         }
     }
+    /**
+     * Search tables, columns, and relationships in loaded schemas.
+     * @param args - The tool arguments (query, elementType).
+     * @returns The matching schema elements, or an error object.
+     */
     static async handleSearchSchemaElements(args) {
         const query = args.query;
         const elementType = args.elementType || 'all';
@@ -898,7 +814,7 @@ export class ToolHandlers {
         try {
             const db = CodeIndexDB.getInstance();
             await db.initialize();
-            const schemas = (await db.getAllSchemas()).map(s => s.schema);
+            const schemas = (await db.schema.getAllSchemas()).map(s => s.schema);
             const results = [];
             const queryLower = query.toLowerCase();
             for (const schema of schemas) {
@@ -951,13 +867,27 @@ export class ToolHandlers {
         catch (error) {
             return {
                 success: false,
-                error: `Failed to search schema elements: ${error instanceof Error ? error.message : 'Unknown error'}`
+                error: `Failed to search schema elements: ${errorMessage(error)}`
             };
         }
     }
     // Schema Helper Functions
+    /**
+     * Build the ordered list of SQL discovery queries for a database type.
+     * @param databaseType - The database engine to generate queries for.
+     * @param includeIndexes - Whether to include index-discovery queries.
+     * @param includeConstraints - Whether to include foreign-key queries.
+     * @param specificTables - Optional table names to limit discovery to.
+     * @returns The generated discovery queries.
+     */
     static generateSchemaDiscoveryQueries(databaseType, includeIndexes, includeConstraints, specificTables) {
-        const queries = [];
+        // The dialect seam lives in `mcp-tools/discoveryQueries.ts`: a free-form
+        // string becomes a `Dialect` (or `null`) at exactly one point. An
+        // unrecognised engine is a loud error here, never a silent empty result.
+        const dialect = normalizeDialect(databaseType);
+        if (!dialect) {
+            throw new Error(`unsupported databaseType '${databaseType}' — expected one of postgresql, mysql, sqlite`);
+        }
         // Identifiers are interpolated into generated SQL text (run by the agent,
         // never this tool), so a name that is not a plain identifier is dropped —
         // a quoted name could otherwise escape the string literal and inject SQL.
@@ -966,100 +896,17 @@ export class ToolHandlers {
         const tableFilter = validTables.length > 0
             ? `WHERE table_name IN (${validTables.map(t => `'${t}'`).join(', ')})`
             : '';
-        switch (databaseType.toLowerCase()) {
-            case 'postgresql':
-                queries.push({
-                    name: 'tables',
-                    sql: `SELECT table_name, table_type, table_schema 
-                FROM information_schema.tables 
-                WHERE table_schema NOT IN ('information_schema', 'pg_catalog') ${tableFilter}
-                ORDER BY table_schema, table_name;`,
-                    description: 'Get all tables and views'
-                });
-                queries.push({
-                    name: 'columns',
-                    sql: `SELECT table_name, column_name, data_type, is_nullable, column_default, 
-                       character_maximum_length, numeric_precision, numeric_scale
-                FROM information_schema.columns 
-                WHERE table_schema NOT IN ('information_schema', 'pg_catalog') ${tableFilter}
-                ORDER BY table_name, ordinal_position;`,
-                    description: 'Get all columns with types and constraints'
-                });
-                if (includeConstraints) {
-                    queries.push({
-                        name: 'foreign_keys',
-                        sql: `SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table_name,
-                         ccu.column_name AS foreign_column_name, rc.delete_rule, rc.update_rule
-                  FROM information_schema.table_constraints AS tc 
-                  JOIN information_schema.key_column_usage AS kcu ON tc.constraint_name = kcu.constraint_name
-                  JOIN information_schema.constraint_column_usage AS ccu ON ccu.constraint_name = tc.constraint_name
-                  JOIN information_schema.referential_constraints AS rc ON tc.constraint_name = rc.constraint_name
-                  WHERE tc.constraint_type = 'FOREIGN KEY' ${tableFilter.replace('table_name', 'tc.table_name')}
-                  ORDER BY tc.table_name, kcu.column_name;`,
-                        description: 'Get foreign key relationships'
-                    });
-                }
-                if (includeIndexes) {
-                    queries.push({
-                        name: 'indexes',
-                        sql: `SELECT tablename, indexname, indexdef 
-                  FROM pg_indexes 
-                  WHERE schemaname NOT IN ('information_schema', 'pg_catalog') ${tableFilter.replace('table_name', 'tablename')}
-                  ORDER BY tablename, indexname;`,
-                        description: 'Get all indexes'
-                    });
-                }
-                break;
-            case 'mysql':
-                queries.push({
-                    name: 'tables',
-                    sql: `SELECT table_name, table_type, table_schema 
-                FROM information_schema.tables 
-                WHERE table_schema = DATABASE() ${tableFilter}
-                ORDER BY table_name;`,
-                    description: 'Get all tables and views'
-                });
-                queries.push({
-                    name: 'columns',
-                    sql: `SELECT table_name, column_name, data_type, is_nullable, column_default,
-                       character_maximum_length, numeric_precision, numeric_scale,
-                       column_key, extra
-                FROM information_schema.columns 
-                WHERE table_schema = DATABASE() ${tableFilter}
-                ORDER BY table_name, ordinal_position;`,
-                    description: 'Get all columns with types and constraints'
-                });
-                if (includeConstraints) {
-                    queries.push({
-                        name: 'foreign_keys',
-                        sql: `SELECT table_name, column_name, referenced_table_name, referenced_column_name,
-                         delete_rule, update_rule
-                  FROM information_schema.key_column_usage 
-                  WHERE table_schema = DATABASE() AND referenced_table_name IS NOT NULL ${tableFilter}
-                  ORDER BY table_name, column_name;`,
-                        description: 'Get foreign key relationships'
-                    });
-                }
-                break;
-            case 'sqlite':
-                queries.push({
-                    name: 'tables',
-                    sql: `SELECT name as table_name, type as table_type 
-                FROM sqlite_master 
-                WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'
-                ORDER BY name;`,
-                    description: 'Get all tables and views'
-                });
-                queries.push({
-                    name: 'table_info',
-                    sql: `-- Run this for each table: PRAGMA table_info(table_name);
-                -- This will give you column information for each table`,
-                    description: 'Get column information (run PRAGMA table_info for each table)'
-                });
-                break;
-        }
-        return queries;
+        return buildDiscoveryQueries(dialect, { tableFilter, includeIndexes, includeConstraints });
     }
+    /**
+     * Build a schema object from SQL discovery result rows.
+     * @param schemaName - The name to give the schema.
+     * @param databaseType - The database engine the data came from.
+     * @param tablesData - The table rows from discovery.
+     * @param columnsData - The column rows from discovery.
+     * @param constraintsData - Optional foreign-key rows from discovery.
+     * @returns The assembled schema object.
+     */
     static buildSchemaFromSqlData(schemaName, databaseType, tablesData, columnsData, constraintsData) {
         // Build schema from SQL results
         const tables = [];
@@ -1129,6 +976,11 @@ export class ToolHandlers {
         };
     }
     // Helper functions
+    /**
+     * Flatten all violations across analyzers, tagging each with its analyzer name.
+     * @param result - The audit result to extract violations from.
+     * @returns The flat list of violations.
+     */
     static getAllViolations(result) {
         const violations = [];
         for (const [analyzerName, analyzerResult] of Object.entries(result.analyzerResults)) {
@@ -1141,6 +993,11 @@ export class ToolHandlers {
         }
         return violations;
     }
+    /**
+     * Compute a 0-100 health score from weighted violation counts.
+     * @param result - The audit result to score.
+     * @returns The computed health score.
+     */
     static calculateHealthScore(result) {
         const filesAnalyzed = result.metadata?.filesAnalyzed || 1;
         const critical = result.summary.criticalIssues || 0;
@@ -1158,6 +1015,12 @@ export class ToolHandlers {
         let score = 100 - (violationsPerFile * 2);
         return Math.max(0, Math.round(Math.min(100, score)));
     }
+    /**
+     * Produce a human-readable recommendation from the health score.
+     * @param score - The computed health score.
+     * @param result - The audit result used to tailor the recommendation.
+     * @returns The recommendation string.
+     */
     static getHealthRecommendation(score, result) {
         const criticals = result.summary.criticalIssues || 0;
         const severe = result.summary.severe || 0;