@homenshum/convex-mcp-nodebench 0.9.8 → 0.10.0

package/dist/index.js

@@ -79,7 +79,7 @@ for (const tool of ALL_TOOLS) {
 // ── Server setup ────────────────────────────────────────────────────
 const server = new Server({
     name: "convex-mcp-nodebench",
-    version: "0.9.8",
+    version: "0.9.4",
 }, {
     capabilities: {
         tools: {},
@@ -349,7 +349,9 @@ After running all audits, summarize:
 - Total issues by severity (critical/warning/info)
 - Top 5 most impactful issues to fix first
 - Quality gate score and grade
-- Trend direction if previous audits exist (use convex_audit_diff)`,
+- Trend direction if previous audits exist (use convex_audit_diff)
+
+IMPORTANT — Analyst diagnostic: For every issue found, trace the ROOT CAUSE — don't just list what's wrong, explain WHY it happened. Ask "why" 5 times. Record root causes with convex_record_gotcha so they don't recur.`,
                     },
                 },
             ],
@@ -373,6 +375,8 @@ After running all audits, summarize:
 6. convex_schema_migration_plan — Compare against previous snapshot for breaking changes
 7. convex_quality_gate — Final quality check with thresholds
 
+For each blocker: diagnose the ROOT CAUSE, not just the symptom. Explain WHY the issue exists and how to prevent it from recurring.
+
 Report: DEPLOY or DO NOT DEPLOY with specific blockers to fix.`,
                     },
                 },
@@ -396,7 +400,9 @@ Report: DEPLOY or DO NOT DEPLOY with specific blockers to fix.`,
 5. convex_audit_pagination — Unbounded numItems (DoS risk)
 6. convex_audit_transaction_safety — Race condition risks
 
-Focus on: unauthorized data access, unvalidated inputs, missing error boundaries, and potential data corruption vectors.`,
+Focus on: unauthorized data access, unvalidated inputs, missing error boundaries, and potential data corruption vectors.
+
+Analyst diagnostic: For each security finding, trace upstream to the ROOT CAUSE. Don't just flag the symptom — explain what system condition allowed the vulnerability to exist. Record findings with convex_record_gotcha.`,
                     },
                 },
             ],

package/dist/tools/actionAuditTools.js

@@ -71,16 +71,11 @@ function auditActions(convexDir) {
                 }
             }
             const body = lines.slice(startLine, endLine).join("\n");
-            // Check 1: ctx.db access in action (not allowed — will throw at runtime)
-            // BUT: skip if ctx.db is inside an inline ctx.runMutation/ctx.runQuery callback
-            // e.g. ctx.runMutation(async (ctx) => { ctx.db.patch(...) }) — the inner ctx is a mutation context
-            const hasInlineCallback = /ctx\.run(Mutation|Query)\s*\(\s*async\s*\(/.test(body);
-            if (/ctx\.db\.(get|query|insert|patch|replace|delete)\s*\(/.test(body) && !hasInlineCallback) {
+            // Check 1: ctx.db access in action (FATAL — not allowed)
+            if (/ctx\.db\.(get|query|insert|patch|replace|delete)\s*\(/.test(body)) {
                 actionsWithDbAccess++;
-                // internalAction ctx.db is a warning (not client-callable, likely called from controlled contexts)
-                // public action ctx.db is a warning too (runtime error but caught during development/testing)
                 issues.push({
-                    severity: "warning",
+                    severity: "critical",
                     location: `${relativePath}:${startLine + 1}`,
                     functionName: funcName,
                     message: `${funcType} "${funcName}" accesses ctx.db directly. Actions cannot access the database — use ctx.runQuery/ctx.runMutation instead.`,
@@ -90,9 +85,8 @@ function auditActions(convexDir) {
             // Check 2: Node API usage without "use node"
             if (!hasUseNode && (nodeApis.test(body) || nodeCryptoApis.test(body))) {
                 actionsWithoutNodeDirective++;
-                // Warning: missing directive is a deployment concern caught during development
                 issues.push({
-                    severity: "warning",
+                    severity: "critical",
                     location: `${relativePath}:${startLine + 1}`,
                     functionName: funcName,
                     message: `${funcType} "${funcName}" uses Node.js APIs but file lacks "use node" directive. Will fail in Convex runtime.`,

package/dist/tools/authorizationTools.js

@@ -41,27 +41,6 @@ function auditAuthorization(convexDir) {
         const content = readFileSync(filePath, "utf-8");
         const relativePath = filePath.replace(convexDir, "").replace(/^[\\/]/, "");
         const lines = content.split("\n");
-        // Pre-scan: detect local helper functions that wrap getAuthUserId/getUserIdentity
-        // Pattern: function getSafeUserId(ctx) { ... getAuthUserId(ctx) ... }
-        const authHelperNames = [];
-        const helperFuncPattern = /(?:async\s+)?function\s+(\w+)\s*\(/g;
-        let hm;
-        while ((hm = helperFuncPattern.exec(content)) !== null) {
-            const hStart = content.slice(0, hm.index).split("\n").length - 1;
-            const hBody = lines.slice(hStart, Math.min(hStart + 30, lines.length)).join("\n");
-            if (/getAuthUserId|getUserIdentity|getAuthSessionId/.test(hBody)) {
-                authHelperNames.push(hm[1]);
-            }
-        }
-        // Also check arrow function helpers: const getUserId = async (ctx) => { ... }
-        const arrowHelperPattern = /(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)\s*(?::\s*[^=]+)?\s*=>/g;
-        while ((hm = arrowHelperPattern.exec(content)) !== null) {
-            const hStart = content.slice(0, hm.index).split("\n").length - 1;
-            const hBody = lines.slice(hStart, Math.min(hStart + 20, lines.length)).join("\n");
-            if (/getAuthUserId|getUserIdentity|getAuthSessionId/.test(hBody)) {
-                authHelperNames.push(hm[1]);
-            }
-        }
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
             for (const ft of funcTypes) {
@@ -90,14 +69,10 @@ function auditAuthorization(convexDir) {
                     }
                 }
                 const body = lines.slice(i, endLine).join("\n");
-                // Check for direct auth calls OR calls to local auth helper wrappers
-                const hasDirectAuth = /ctx\.auth\.getUserIdentity\s*\(\s*\)/.test(body) ||
+                const hasAuthCheck = /ctx\.auth\.getUserIdentity\s*\(\s*\)/.test(body) ||
                     /getUserIdentity/.test(body) ||
                     /getAuthUserId/.test(body) ||
                     /getAuthSessionId/.test(body);
-                const callsAuthHelper = authHelperNames.length > 0 &&
-                    authHelperNames.some(h => new RegExp(`\\b${h}\\s*\\(`).test(body));
-                const hasAuthCheck = hasDirectAuth || callsAuthHelper;
                 const hasDbWrite = dbWriteOps.test(body);
                 const isSensitiveName = writeSensitive.test(funcName);
                 if (hasAuthCheck) {
@@ -106,13 +81,11 @@ function auditAuthorization(convexDir) {
                     const identityAssign = body.match(/(?:const|let)\s+(\w+)\s*=\s*await\s+ctx\.auth\.getUserIdentity\s*\(\s*\)/);
                     if (identityAssign) {
                         const varName = identityAssign[1];
-                        // Recognize: if (!var), if (var === null), if (var), var &&, var ?, throw on !var, comparisons
-                        const hasNullCheck = new RegExp(`if\\s*\\(\\s*!${varName}\\b|if\\s*\\(\\s*${varName}\\s*===?\\s*null|if\\s*\\(\\s*${varName}\\s*\\)|${varName}\\s*&&|${varName}\\s*\\?|throw.*!${varName}|${varName}\\s*!==?\\s*null|===\\s*${varName}|!==\\s*${varName}`).test(body);
+                        const hasNullCheck = new RegExp(`if\\s*\\(\\s*!${varName}\\b|if\\s*\\(\\s*${varName}\\s*===?\\s*null|if\\s*\\(\\s*!${varName}\\s*\\)`).test(body);
                         if (!hasNullCheck) {
                             uncheckedIdentity++;
-                            // Queries can intentionally return different data for auth/unauth — warning not critical
                             issues.push({
-                                severity: "warning",
+                                severity: "critical",
                                 location: `${relativePath}:${i + 1}`,
                                 functionName: funcName,
                                 message: `${ft} "${funcName}" calls getUserIdentity() but doesn't check for null. Unauthenticated users will get undefined identity.`,
@@ -124,13 +97,11 @@ function auditAuthorization(convexDir) {
                     const authUserAssign = body.match(/(?:const|let)\s+(\w+)\s*=\s*await\s+getAuthUserId\s*\(/);
                     if (authUserAssign) {
                         const varName = authUserAssign[1];
-                        // Recognize: if (!var), if (var === null), if (var), var &&, var ?, throw on !var, comparisons
-                        const hasNullCheck = new RegExp(`if\\s*\\(\\s*!${varName}\\b|if\\s*\\(\\s*${varName}\\s*===?\\s*null|if\\s*\\(\\s*${varName}\\s*\\)|${varName}\\s*&&|${varName}\\s*\\?|throw.*!${varName}|${varName}\\s*!==?\\s*null|===\\s*${varName}|!==\\s*${varName}`).test(body);
+                        const hasNullCheck = new RegExp(`if\\s*\\(\\s*!${varName}\\b|if\\s*\\(\\s*${varName}\\s*===?\\s*null|throw.*!${varName}`).test(body);
                         if (!hasNullCheck) {
                             uncheckedIdentity++;
-                            // Queries can intentionally return different data for auth/unauth — warning not critical
                             issues.push({
-                                severity: "warning",
+                                severity: "critical",
                                 location: `${relativePath}:${i + 1}`,
                                 functionName: funcName,
                                 message: `${ft} "${funcName}" calls getAuthUserId() but doesn't check for null. Unauthenticated users will get null userId.`,
@@ -141,13 +112,11 @@ function auditAuthorization(convexDir) {
                 }
                 else {
                     withoutAuth++;
-                    // Warning: public mutation/action with DB writes but no auth
-                    // Downgraded from critical — missing auth is a security posture issue, not a runtime failure.
-                    // Many monorepo mutations are system-level (called by actions/schedulers), not client-facing.
+                    // Critical: public mutation/action with DB writes but no auth
                     if ((ft === "mutation" || ft === "action") && hasDbWrite) {
                         const sensitiveHint = isSensitiveName ? ` Name "${funcName}" suggests a destructive operation.` : "";
                         issues.push({
-                            severity: "warning",
+                            severity: "critical",
                             location: `${relativePath}:${i + 1}`,
                             functionName: funcName,
                             message: `Public ${ft} "${funcName}" writes to DB without auth check. Any client can call this.${sensitiveHint}`,
@@ -155,8 +124,9 @@ function auditAuthorization(convexDir) {
                         });
                     }
                     else if (isSensitiveName) {
+                        // Only flag sensitive name separately if not already caught by DB-write check
                         issues.push({
-                            severity: "warning",
+                            severity: "critical",
                             location: `${relativePath}:${i + 1}`,
                             functionName: funcName,
                             message: `Public ${ft} "${funcName}" has a sensitive name but no auth check. Consider making it internal or adding auth.`,

package/dist/tools/critterTools.js

@@ -137,6 +137,20 @@ function scoreCritterCheck(input) {
         score += 10;
         feedback.push("Good: success criteria defined — this makes the deploy gate concrete.");
     }
+    // ── Check 10: Bandaid detection — symptom fixes without root-cause reasoning ──
+    const bandaidPatterns = [
+        "add try.?catch", "wrap in try", "catch the error", "suppress the error",
+        "add optional chaining", "add \\?\\.", "silence the warning",
+        "add as any", "cast to any", "ignore the type",
+        "add a timeout", "increase the timeout", "add a delay",
+        "delete the test", "skip the test", "disable the test",
+        "hide the error", "remove the warning",
+    ];
+    const bandaidRegex = new RegExp(bandaidPatterns.join("|"), "i");
+    if (bandaidRegex.test(taskLower) && !whyLower.includes("root cause") && !whyLower.includes("because") && whyLower.length < 50) {
+        score -= 20;
+        feedback.push("Bandaid alert: this looks like a symptom fix. What's the root cause? Diagnose like an analyst, not a junior dev.");
+    }
     score = Math.max(0, Math.min(100, score));
     let verdict;
     if (score >= 70) {

package/dist/tools/functionTools.js

@@ -57,7 +57,7 @@ function extractFunctions(convexDir) {
                         filePath,
                         relativePath,
                         line: i + 1,
-                        hasArgs: /args\s*:\s*[\{\v]/.test(chunk) || /args\s*:\s*v\./.test(chunk) || /args\s*:\s*\w/.test(chunk),
+                        hasArgs: /args\s*:\s*[\{\v]/.test(chunk) || /args\s*:\s*v\./.test(chunk),
                         hasReturns: /returns\s*:\s*v\./.test(chunk),
                         hasHandler: /handler\s*:/.test(chunk),
                     });
@@ -76,10 +76,8 @@ function auditFunctions(convexDir) {
         if (fn.type === "httpAction")
             continue; // httpActions don't have args/returns validators
         if (!fn.hasArgs) {
-            // Missing args validator is a best practice recommendation, not a runtime failure.
-            // Functions without args simply accept no arguments — no unvalidated input risk.
             issues.push({
-                severity: "warning",
+                severity: "critical",
                 location: `${fn.relativePath}:${fn.line}`,
                 functionName: fn.name,
                 message: `${fn.type} "${fn.name}" is missing args validator`,
@@ -96,9 +94,8 @@ function auditFunctions(convexDir) {
             });
         }
         if (!fn.hasHandler) {
-            // Old shorthand syntax (query(async (ctx) => {})) works fine — just a style recommendation
             issues.push({
-                severity: "warning",
+                severity: "critical",
                 location: `${fn.relativePath}:${fn.line}`,
                 functionName: fn.name,
                 message: `${fn.type} "${fn.name}" is missing handler property (may be using old syntax)`,
@@ -287,7 +284,7 @@ export const functionTools = [
             const functions = extractFunctions(convexDir);
             // Store audit result
             const db = getDb();
-            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "functions", JSON.stringify(issues), issues.length);
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "function_audit", JSON.stringify(issues), issues.length);
             const critical = issues.filter((i) => i.severity === "critical");
             const warnings = issues.filter((i) => i.severity === "warning");
             // Aggregate issues by category for cleaner output

package/dist/tools/methodologyTools.js

@@ -83,6 +83,19 @@ const METHODOLOGY_CONTENT = {
         ],
         tools: ["convex_suggest_indexes", "convex_audit_schema"],
     },
+    analyst_diagnostic: {
+        title: "Analyst Diagnostic — Root Cause Over Bandaids",
+        description: "Guide yourself like an analyst diagnosing the root cause, NOT a junior dev slapping on a bandaid. Mandatory for all bug work.",
+        steps: [
+            "1. REPRODUCE: Confirm the exact failure mode before touching any code",
+            "2. TRACE UPSTREAM: Walk from symptom → intermediate state → root cause. Don't stop at the first error you see",
+            "3. ASK 'WHY' 5 TIMES: Each answer should go one level deeper into the system",
+            "4. FIX THE CAUSE: The right fix makes the symptom impossible, not just invisible",
+            "5. VERIFY NO SIDEWAYS SHIFT: Bandaids move bugs, they don't fix them — check adjacent behavior",
+            "6. RECORD: Use convex_record_gotcha with the root cause so the next person doesn't re-discover it",
+        ],
+        tools: ["convex_search_gotchas", "convex_record_gotcha", "convex_critter_check"],
+    },
 };
 // ── Tool Definitions ────────────────────────────────────────────────
 export const methodologyTools = [
@@ -101,6 +114,7 @@ export const methodologyTools = [
                         "convex_deploy_verification",
                         "convex_knowledge_management",
                         "convex_index_optimization",
+                        "analyst_diagnostic",
                     ],
                     description: "Which methodology to explain",
                 },

package/dist/tools/qualityGateTools.js

@@ -77,18 +77,17 @@ function runQualityGate(projectDir, thresholds) {
         }
         catch { /* skip */ }
     }
-    // Check 4: Type safety (as any casts) — exclude test/eval files
+    // Check 4: Type safety (as any casts)
     const typeSafety = getLatest("type_safety");
     if (typeSafety) {
         try {
             const issues = JSON.parse(typeSafety.issues_json);
-            // Exclude test, eval, benchmark, and fixture files from production quality gate
-            const testEvalPattern = /test|__tests__|spec|\.test\.|\.spec\.|fixtures|mocks|evaluation|liveEval|liveApiSmoke|benchmark|calibration|harness|quickTest|comprehensiveTest|comprehensiveEval/i;
+            const asAnyIssues = Array.isArray(issues)
+                ? issues.filter((i) => i.message?.includes("as any")).length
+                : 0;
             // Each as-any issue represents a FILE, count from message for actual number
             const actualCasts = Array.isArray(issues)
                 ? issues.reduce((sum, i) => {
-                    if (testEvalPattern.test(i.location ?? ""))
-                        return sum; // skip test/eval files
                     const countMatch = i.message?.match(/(\d+)\s+`as any`/);
                     return sum + (countMatch ? parseInt(countMatch[1], 10) : 0);
                 }, 0)
@@ -103,13 +102,13 @@ function runQualityGate(projectDir, thresholds) {
         }
         catch { /* skip */ }
     }
-    // Check 5: Unbounded collects (only warning-level — indexed collects are downgraded to info)
+    // Check 5: Unbounded collects
     const queryEfficiency = getLatest("query_efficiency");
     if (queryEfficiency) {
         try {
             const issues = JSON.parse(queryEfficiency.issues_json);
             const unbounded = Array.isArray(issues)
-                ? issues.filter((i) => i.severity === "warning" && i.message?.includes(".collect()")).length
+                ? issues.filter((i) => i.message?.includes(".collect()")).length
                 : 0;
             checks.push({
                 metric: "unbounded_collects",

package/dist/tools/queryEfficiencyTools.js

@@ -63,16 +63,13 @@ function auditQueryEfficiency(convexDir) {
                 const chain = lines.slice(chainStart, i + 1).join("\n");
                 if (!/\.take\s*\(/.test(chain) && !/\.paginate\s*\(/.test(chain)) {
                     collectWithoutLimit++;
+                    // Check if it's a bounded table or could be large
                     const tableMatch = chain.match(/\.query\s*\(\s*["'](\w+)["']\s*\)/);
-                    // Indexed queries are bounded by the index range — lower severity
-                    const hasIndex = /\.withIndex\s*\(/.test(chain);
                     issues.push({
-                        severity: hasIndex ? "info" : "warning",
+                        severity: "warning",
                         location: `${relativePath}:${i + 1}`,
                         message: `.collect() without .take() limit${tableMatch ? ` on table "${tableMatch[1]}"` : ""}. Could return entire table.`,
-                        fix: hasIndex
-                            ? "Consider adding .take(N) for predictable result sizes, even with index filtering"
-                            : "Add .take(N) before .collect(), or use .paginate() for large result sets",
+                        fix: "Add .take(N) before .collect(), or use .paginate() for large result sets",
                     });
                 }
             }

package/dist/tools/reportingTools.js

@@ -75,7 +75,7 @@ function buildSarif(projectDir, auditTypes, limit) {
                 tool: {
                     driver: {
                         name: "convex-mcp-nodebench",
-                        version: "0.9.8",
+                        version: "0.9.4",
                         informationUri: "https://www.npmjs.com/package/@homenshum/convex-mcp-nodebench",
                         rules: [...rulesMap.values()],
                     },

package/dist/tools/storageAuditTools.js

@@ -133,7 +133,7 @@ export const storageAuditTools = [
             }
             const { issues, stats } = auditStorageUsage(convexDir);
             const db = getDb();
-            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "storage", JSON.stringify(issues), issues.length);
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "storage_usage", JSON.stringify(issues), issues.length);
             return {
                 summary: {
                     ...stats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homenshum/convex-mcp-nodebench",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "description": "Convex-specific MCP server applying NodeBench self-instruct diligence patterns to Convex development. Schema audit, function compliance, deployment gates, persistent gotcha DB, and methodology guidance. Complements Context7 (raw docs) and official Convex MCP (deployment introspection) with structured verification workflows.",
   "type": "module",
   "bin": {