code-sentinel-mcp 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# CodeSentinel MCP Server
+
+A code quality analysis MCP server that detects security issues, deceptive patterns, placeholders, and highlights code strengths.
+
+## Features
+
+- 🔒 **Security Analysis**: Hardcoded secrets, SQL injection, XSS, insecure crypto, and more
+- 🎭 **Deceptive Pattern Detection**: Empty catch blocks, silent failures, error-hiding returns
+- 📝 **Placeholder Detection**: TODO/FIXME, lorem ipsum, test data, incomplete implementations
+- ⚠️ **Error & Code Smell Detection**: Type coercion, null references, async issues
+- 💪 **Strength Recognition**: Highlights good practices like typing, error handling, tests
+- 📊 **HTML Reports**: Beautiful visual reports with scores and suggestions
+
+## Installation
+
+```bash
+# Clone or copy the project
+cd code-sentinel
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+```
+
+## Usage with Claude Code
+
+Add to your Claude Code MCP configuration:
+
+```bash
+claude mcp add code-sentinel -- node /path/to/code-sentinel/build/index.js
+```
+
+Or manually add to your config:
+
+```json
+{
+  "mcpServers": {
+    "code-sentinel": {
+      "command": "node",
+      "args": ["/path/to/code-sentinel/build/index.js"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `analyze_code`
+Full analysis returning structured JSON with all issues and strengths.
+
+### `generate_report`
+Full analysis with HTML report output.
+
+### `check_security`
+Security-focused analysis only.
+
+### `check_deceptive_patterns`
+Check for error-hiding and deceptive code patterns.
+
+### `check_placeholders`
+Find TODOs, dummy data, and incomplete code.
+
+## Example Usage in Claude Code
+
+```
+Analyze this code for quality issues:
+
+const API_KEY = "sk-abc123456789";
+
+async function fetchData() {
+  try {
+    const response = await fetch(url);
+    return response.json();
+  } catch (e) {
+    // TODO: handle error
+  }
+}
+```
+
+Claude will automatically use CodeSentinel to analyze and report:
+- Critical: Hardcoded API key detected
+- High: Empty catch block (deceptive pattern)
+- Low: TODO comment found
+
+## Detection Categories
+
+### Security Issues (SEC)
+- Hardcoded secrets (API keys, tokens, passwords)
+- SQL injection patterns
+- XSS vulnerabilities
+- Insecure random, weak crypto
+- Disabled SSL validation
+- Eval and dynamic code execution
+
+### Deceptive Patterns (DEC)
+- Empty catch blocks
+- Silent promise rejections
+- Error-hiding fallbacks (|| [], || {})
+- Fake success responses
+- Excessive optional chaining
+- Linter suppression comments
+
+### Placeholders (PH)
+- TODO/FIXME/HACK/XXX comments
+- Lorem ipsum text
+- Test emails and passwords
+- Debug console.log
+- Debugger statements
+- Not implemented errors
+
+### Errors & Smells (ERR)
+- Loose equality (==)
+- Assignment in conditions
+- parseInt without radix
+- Array mutation during iteration
+- Floating point comparison
+- Await in constructor
+
+## Scoring
+
+The quality score (0-100) is calculated based on:
+- Critical issues: -25 points each
+- High issues: -15 points each
+- Medium issues: -5 points each
+- Low issues: -1 point each
+- Strengths: +2 points each
+
+## Extending
+
+Add new patterns by editing the analyzer files in `src/analyzers/`:
+- `security.ts` - Security vulnerability patterns
+- `deceptive.ts` - Error-hiding patterns
+- `placeholders.ts` - Incomplete code patterns
+- `errors.ts` - Code smell patterns
+- `strengths.ts` - Good practice patterns
+
+Each pattern includes:
+- `id`: Unique identifier (e.g., SEC001)
+- `pattern`: RegExp to match
+- `title`: Short description
+- `description`: Detailed explanation
+- `severity`: critical | high | medium | low
+- `suggestion`: How to fix (optional)
+
+## License
+
+MIT

package/build/analyzers/deceptive.d.ts

@@ -0,0 +1,2 @@
+import { Issue } from '../types.js';
+export declare function analyzeDeceptivePatterns(code: string, filename: string): Issue[];

package/build/analyzers/deceptive.js

@@ -0,0 +1,200 @@
+// These patterns detect code that hides errors or creates false confidence
+const deceptivePatterns = [
+    // Empty catch blocks
+    {
+        id: 'CS-DEC001',
+        pattern: /catch\s*\([^)]*\)\s*\{\s*\}/g,
+        title: 'Empty Catch Block',
+        description: 'Silently swallowing errors makes debugging impossible.',
+        severity: 'high',
+        category: 'deceptive',
+        suggestion: 'At minimum, log the error. Better: handle it appropriately or rethrow.'
+    },
+    {
+        id: 'CS-DEC002',
+        pattern: /catch\s*\([^)]*\)\s*\{\s*\/\/.*?\s*\}/gs,
+        title: 'Catch Block with Only Comments',
+        description: 'A catch block with only comments still swallows errors.',
+        severity: 'high',
+        category: 'deceptive',
+        suggestion: 'Add actual error handling, not just comments.'
+    },
+    {
+        id: 'CS-DEC003',
+        pattern: /catch\s*\([^)]*\)\s*\{\s*(?:console\.log|print)\s*\([^)]*\)\s*;?\s*\}/g,
+        title: 'Catch with Only Console.log',
+        description: 'Logging alone does not handle the error - execution continues as if nothing happened.',
+        severity: 'medium',
+        category: 'deceptive',
+        suggestion: 'Decide: should execution continue? Add recovery logic or rethrow.'
+    },
+    // Silent promise rejections
+    {
+        id: 'CS-DEC010',
+        pattern: /\.catch\s*\(\s*\(\s*\)\s*=>\s*\{\s*\}\s*\)/g,
+        title: 'Empty Promise Catch',
+        description: 'Silently ignoring promise rejections hides async errors.',
+        severity: 'high',
+        category: 'deceptive',
+        suggestion: 'Handle the rejection or let it propagate for proper error handling.'
+    },
+    {
+        id: 'CS-DEC011',
+        pattern: /\.catch\s*\(\s*\(\s*\)\s*=>\s*(?:null|undefined|false|true|''|"")\s*\)/g,
+        title: 'Promise Catch Returns Silent Value',
+        description: 'Returning a value from catch masks the error - callers won\'t know something failed.',
+        severity: 'high',
+        category: 'deceptive',
+        suggestion: 'Return a distinguishable error state or rethrow.'
+    },
+    {
+        id: 'CS-DEC012',
+        pattern: /\.catch\s*\(\s*_\s*=>\s*\{?\s*\}?\s*\)/g,
+        title: 'Catch with Ignored Error Parameter',
+        description: 'Using _ for error parameter signals intentional ignore - but is it really safe to ignore?',
+        severity: 'medium',
+        category: 'deceptive',
+        suggestion: 'Document why ignoring this error is safe, or handle it.'
+    },
+    // Fallback values that mask failures
+    {
+        id: 'CS-DEC020',
+        pattern: /\|\|\s*\[\s*\]/g,
+        title: 'Empty Array Fallback',
+        description: 'Falling back to [] can mask failed data fetching - code continues as if data was empty.',
+        severity: 'medium',
+        category: 'deceptive',
+        suggestion: 'Distinguish between "no data" and "failed to fetch". Consider throwing or returning null.'
+    },
+    {
+        id: 'CS-DEC021',
+        pattern: /\|\|\s*\{\s*\}/g,
+        title: 'Empty Object Fallback',
+        description: 'Falling back to {} can hide parsing or fetching failures.',
+        severity: 'medium',
+        category: 'deceptive',
+        suggestion: 'Handle the undefined/null case explicitly rather than masking it.'
+    },
+    {
+        id: 'CS-DEC022',
+        pattern: /\?\?\s*(?:\[\s*\]|\{\s*\}|''|"")/g,
+        title: 'Nullish Coalescing to Empty Value',
+        description: 'Defaulting to empty values with ?? can mask null responses that indicate errors.',
+        severity: 'low',
+        category: 'deceptive',
+        suggestion: 'Verify that null/undefined truly means "use default" vs "something went wrong".'
+    },
+    // Optional chaining abuse
+    {
+        id: 'CS-DEC030',
+        pattern: /\?\.\w+\?\.\w+\?\.\w+\?\.\w+/g,
+        title: 'Excessive Optional Chaining',
+        description: 'Deep optional chaining (4+ levels) often masks structural problems or missing validation.',
+        severity: 'medium',
+        category: 'deceptive',
+        suggestion: 'Validate data shape upfront rather than optional-chaining through uncertain structures.'
+    },
+    // Error-hiding returns
+    {
+        id: 'CS-DEC040',
+        pattern: /return\s+(?:null|undefined|false)\s*;?\s*\/\/\s*(?:error|fail|todo|fixme)/gi,
+        title: 'Silent Error Return',
+        description: 'Returning null/false on error with a comment - callers may not check for this.',
+        severity: 'high',
+        category: 'deceptive',
+        suggestion: 'Throw an error or return a Result/Either type that forces handling.'
+    },
+    {
+        id: 'CS-DEC041',
+        pattern: /if\s*\([^)]*error[^)]*\)\s*\{\s*return\s*;?\s*\}/gi,
+        title: 'Silent Return on Error',
+        description: 'Returning silently when an error is detected - no logging, no propagation.',
+        severity: 'high',
+        category: 'deceptive',
+        suggestion: 'Log the error or throw it. Silent returns make debugging a nightmare.'
+    },
+    // Timeout-based "fixes"
+    {
+        id: 'CS-DEC050',
+        pattern: /setTimeout\s*\([^,]+,\s*\d+\s*\)\s*;?\s*\/\/.*?(?:fix|hack|workaround|retry)/gi,
+        title: 'Timeout as Error Workaround',
+        description: 'Using setTimeout to "fix" timing issues often masks race conditions.',
+        severity: 'medium',
+        category: 'deceptive',
+        suggestion: 'Fix the underlying race condition. Use proper async coordination.'
+    },
+    // Suppressed warnings/errors
+    {
+        id: 'CS-DEC060',
+        pattern: /\/\/\s*(?:@ts-ignore|@ts-expect-error|eslint-disable|noqa)/g,
+        title: 'Linter/Type Check Suppression',
+        description: 'Suppressing type errors or linter warnings may hide real issues.',
+        severity: 'low',
+        category: 'deceptive',
+        suggestion: 'Fix the underlying issue. If suppression is needed, document why.'
+    },
+    {
+        id: 'CS-DEC061',
+        pattern: /as\s+any(?!\w)/g,
+        title: 'TypeScript "as any" Cast',
+        description: 'Casting to any defeats TypeScript\'s type safety.',
+        severity: 'medium',
+        category: 'deceptive',
+        suggestion: 'Use proper type definitions or unknown with type guards.'
+    },
+    // Fake success responses
+    {
+        id: 'CS-DEC070',
+        pattern: /return\s*\{\s*(?:success|ok|status)\s*:\s*true[^}]*\}\s*;?\s*\/\/.*?(?:todo|fixme|hack)/gi,
+        title: 'Fake Success Response',
+        description: 'Returning success without actually doing the work.',
+        severity: 'critical',
+        category: 'deceptive',
+        suggestion: 'Implement the actual functionality or return an honest error.'
+    },
+    // Console.error without throwing
+    {
+        id: 'CS-DEC080',
+        pattern: /console\.error\s*\([^)]+\)\s*;?\s*(?!\s*throw)/g,
+        title: 'console.error Without Throw',
+        description: 'Logging an error but continuing execution - the error may not be handled.',
+        severity: 'low',
+        category: 'deceptive',
+        suggestion: 'Consider if execution should continue. If not, throw after logging.'
+    }
+];
+export function analyzeDeceptivePatterns(code, filename) {
+    const issues = [];
+    const lines = code.split('\n');
+    for (const patternDef of deceptivePatterns) {
+        patternDef.pattern.lastIndex = 0;
+        let match;
+        while ((match = patternDef.pattern.exec(code)) !== null) {
+            const beforeMatch = code.substring(0, match.index);
+            const lineNumber = beforeMatch.split('\n').length;
+            const lineContent = lines[lineNumber - 1] || '';
+            // Build verification with actual values substituted
+            let verification = patternDef.verification;
+            if (verification) {
+                verification = {
+                    ...verification,
+                    commands: verification.commands?.map(cmd => cmd.replace(/<filename>/g, filename))
+                };
+            }
+            issues.push({
+                id: patternDef.id,
+                category: patternDef.category,
+                severity: patternDef.severity,
+                title: patternDef.title,
+                description: patternDef.description,
+                line: lineNumber,
+                code: lineContent.trim(),
+                suggestion: patternDef.suggestion,
+                verification
+            });
+            if (!patternDef.pattern.global)
+                break;
+        }
+    }
+    return issues;
+}

package/build/analyzers/errors.d.ts

@@ -0,0 +1,2 @@
+import { Issue } from '../types.js';
+export declare function analyzeErrors(code: string, filename: string): Issue[];

package/build/analyzers/errors.js

@@ -0,0 +1,214 @@
+const errorPatterns = [
+    // Unhandled promises
+    {
+        id: 'CS-ERR001',
+        pattern: /(?:^|\s)(?:await\s+)?(?:\w+\.)+\w+\s*\([^)]*\)\s*;?\s*$/gm,
+        title: 'Potentially Unhandled Promise',
+        description: 'Async call without await or .then()/.catch() may silently fail.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Use await with try/catch or add .catch() handler.'
+    },
+    // Missing error handling
+    {
+        id: 'CS-ERR010',
+        pattern: /async\s+(?:function\s+\w+|\w+\s*=\s*async)\s*\([^)]*\)\s*(?::\s*\w+\s*)?\{(?:(?!try\s*\{).)*\}/gs,
+        title: 'Async Function Without Try/Catch',
+        description: 'Async function has no error handling.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Wrap async operations in try/catch or handle at call site.'
+    },
+    // Variable shadowing and redeclaration
+    {
+        id: 'CS-ERR020',
+        pattern: /var\s+(\w+)[\s\S]*?var\s+\1\s*=/g,
+        title: 'Variable Redeclaration with var',
+        description: 'Same variable declared twice with var - potential bug.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Use let/const and avoid redeclaring variables.'
+    },
+    // Comparison issues
+    {
+        id: 'CS-ERR030',
+        pattern: /[^!=]==[^=]/g,
+        title: 'Loose Equality (==)',
+        description: 'Loose equality can cause unexpected type coercion.',
+        severity: 'low',
+        category: 'error',
+        suggestion: 'Use strict equality (===) instead.'
+    },
+    {
+        id: 'CS-ERR031',
+        pattern: /!=[^=]/g,
+        title: 'Loose Inequality (!=)',
+        description: 'Loose inequality can cause unexpected type coercion.',
+        severity: 'low',
+        category: 'error',
+        suggestion: 'Use strict inequality (!==) instead.'
+    },
+    {
+        id: 'CS-ERR032',
+        pattern: /if\s*\(\s*\w+\s*=\s*[^=]/g,
+        title: 'Assignment in Condition',
+        description: 'Assignment inside if condition - likely meant to use ==.',
+        severity: 'high',
+        category: 'error',
+        suggestion: 'Use === for comparison. If assignment is intentional, wrap in extra parens.'
+    },
+    // Null/undefined issues
+    {
+        id: 'CS-ERR040',
+        pattern: /(\w+)\.(\w+)\s*(?:\(|\.)/g,
+        title: 'Potential Null Reference',
+        description: 'Accessing property without null check - may throw.',
+        severity: 'low',
+        category: 'error',
+        suggestion: 'Use optional chaining (?.) or add null checks.'
+    },
+    // Loop issues
+    {
+        id: 'CS-ERR050',
+        pattern: /for\s*\(\s*(?:var|let)\s+\w+\s+in\s+/g,
+        title: 'for...in on Array',
+        description: 'for...in iterates over keys, not values - often wrong for arrays.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Use for...of, forEach(), or traditional for loop for arrays.'
+    },
+    {
+        id: 'CS-ERR051',
+        pattern: /while\s*\(\s*true\s*\)/g,
+        title: 'Infinite Loop Pattern',
+        description: 'while(true) requires explicit break - easy to create infinite loop.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Ensure there is always a reachable break condition.'
+    },
+    // Floating point comparison
+    {
+        id: 'CS-ERR060',
+        pattern: /(?:\d+\.\d+|\w+)\s*===?\s*(?:\d+\.\d+|\w+).*?(?:price|amount|total|sum|money|currency|rate)/gi,
+        title: 'Floating Point Comparison',
+        description: 'Direct comparison of floats (especially money) can fail due to precision.',
+        severity: 'high',
+        category: 'error',
+        suggestion: 'Use epsilon comparison or integer cents for money.'
+    },
+    // Array mutation issues
+    {
+        id: 'CS-ERR070',
+        pattern: /\.forEach\s*\([^)]*\)\s*\{[^}]*(?:\.push|\.pop|\.shift|\.splice)/g,
+        title: 'Array Mutation During Iteration',
+        description: 'Modifying array while iterating can cause skipped elements.',
+        severity: 'high',
+        category: 'error',
+        suggestion: 'Create a new array or iterate backwards when mutating.'
+    },
+    // parseInt without radix
+    {
+        id: 'CS-ERR080',
+        pattern: /parseInt\s*\(\s*[^,)]+\s*\)(?!\s*,)/g,
+        title: 'parseInt Without Radix',
+        description: 'parseInt without radix can give unexpected results.',
+        severity: 'low',
+        category: 'error',
+        suggestion: 'Always specify radix: parseInt(x, 10).'
+    },
+    // Unreachable code
+    {
+        id: 'CS-ERR090',
+        pattern: /return\s+[^;]+;\s*\n\s*(?![\s}]|case\s|default:)/g,
+        title: 'Potentially Unreachable Code',
+        description: 'Code after return statement will never execute.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Remove unreachable code or fix control flow.'
+    },
+    // Dangerous delete
+    {
+        id: 'CS-ERR100',
+        pattern: /delete\s+\w+\[\w+\]/g,
+        title: 'delete Operator on Array',
+        description: 'delete leaves holes in arrays - length unchanged.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Use splice() to remove array elements.'
+    },
+    // This binding issues
+    {
+        id: 'CS-ERR110',
+        pattern: /setTimeout\s*\(\s*(?:this\.\w+|function\s*\([^)]*\)\s*\{[^}]*this\.)/g,
+        title: 'Potential "this" Binding Issue',
+        description: 'Using "this" in setTimeout callback may not refer to expected context.',
+        severity: 'medium',
+        category: 'error',
+        suggestion: 'Use arrow function or .bind(this).'
+    },
+    // Constructor without new
+    {
+        id: 'CS-ERR120',
+        pattern: /(?:^|[^.])\b(?:Date|Array|Object|Map|Set|Promise)\s*\(\s*\)/g,
+        title: 'Constructor Without "new"',
+        description: 'Calling constructor without new may not work as expected.',
+        severity: 'low',
+        category: 'error',
+        suggestion: 'Use "new" keyword with constructors.'
+    },
+    // Magic numbers
+    {
+        id: 'CS-ERR130',
+        pattern: /(?:if|while|for|===?|!==?|[<>]=?)\s*\(?\s*(?:\d{3,}|\d+\.\d+)\s*(?!\s*(?:px|em|rem|%|vh|vw|s|ms))/g,
+        title: 'Magic Number',
+        description: 'Hardcoded number without context makes code hard to maintain.',
+        severity: 'low',
+        category: 'error',
+        suggestion: 'Extract magic numbers into named constants.'
+    },
+    // Async in constructor
+    {
+        id: 'CS-ERR140',
+        pattern: /constructor\s*\([^)]*\)\s*\{[^}]*await\s+/g,
+        title: 'Await in Constructor',
+        description: 'Constructors cannot be async - await will not work as expected.',
+        severity: 'high',
+        category: 'error',
+        suggestion: 'Use a static factory method for async initialization.'
+    }
+];
+export function analyzeErrors(code, filename) {
+    const issues = [];
+    const lines = code.split('\n');
+    for (const patternDef of errorPatterns) {
+        patternDef.pattern.lastIndex = 0;
+        let match;
+        while ((match = patternDef.pattern.exec(code)) !== null) {
+            const beforeMatch = code.substring(0, match.index);
+            const lineNumber = beforeMatch.split('\n').length;
+            const lineContent = lines[lineNumber - 1] || '';
+            // Build verification with actual values substituted
+            let verification = patternDef.verification;
+            if (verification) {
+                verification = {
+                    ...verification,
+                    commands: verification.commands?.map(cmd => cmd.replace(/<filename>/g, filename))
+                };
+            }
+            issues.push({
+                id: patternDef.id,
+                category: patternDef.category,
+                severity: patternDef.severity,
+                title: patternDef.title,
+                description: patternDef.description,
+                line: lineNumber,
+                code: lineContent.trim(),
+                suggestion: patternDef.suggestion,
+                verification
+            });
+            if (!patternDef.pattern.global)
+                break;
+        }
+    }
+    return issues;
+}