code-sentinel-mcp 0.2.4 → 0.2.6

package/README.md

@@ -12,6 +12,75 @@ AI coding assistants can inadvertently introduce subtle issues: hardcoded secret
 - **Balanced analysis**: Detects both issues AND strengths for fair code assessment
 - **Multi-language support**: Works with TypeScript, JavaScript, Python, Go, Rust, Java, and more
 
+## Why Not Tree-sitter or AST-Based Tools?
+
+CodeSentinel intentionally uses a **pattern-based approach** rather than AST parsing. Here's why:
+
+### The Problem We Solve Is Different
+
+Traditional linters (ESLint, tree-sitter) detect **syntax errors** and **style violations**. CodeSentinel detects **semantically deceptive patterns** - code that is:
+
+- Syntactically valid (passes all linters)
+- Structurally correct (valid AST)
+- **But hides serious issues** that AI agents commonly produce
+
+### Examples AST Tools Miss
+
+```javascript
+// AST sees: valid try-catch block
+// CodeSentinel sees: error swallowing that masks failures
+try { riskyOperation(); } catch(e) { }
+
+// AST sees: valid function returning boolean
+// CodeSentinel sees: fake implementation that always succeeds
+function validateUser() { return true; } // TODO: implement
+
+// AST sees: valid fallback expression
+// CodeSentinel sees: failure masking - "no data" vs "fetch failed" indistinguishable
+const users = response.data || [];
+
+// AST sees: valid return statement
+// CodeSentinel sees: silent failure hiding
+if (error) { return null; } // error case
+```
+
+### What Each Approach Detects
+
+| Issue Type | AST/Tree-sitter | CodeSentinel |
+|:-----------|:----------------|:-------------|
+| Syntax errors | Yes | No (not our goal) |
+| Missing semicolons | Yes | No |
+| Unused variables | Yes | No |
+| **Empty catch blocks** | Partially | Yes |
+| **Silent error returns** | No | Yes |
+| **Fake success responses** | No | Yes |
+| **TODO/placeholder code** | No | Yes |
+| **Error-masking fallbacks** | No | Yes |
+| **Hardcoded secrets** | Limited | Yes |
+| **Deceptive comments** | No | Yes |
+
+### The Real Issue: Agent Behavior
+
+AI coding agents produce code that **looks correct** but contains subtle deceptions:
+
+1. **"Making the error go away"** - Empty catches, silent returns, swallowed exceptions
+2. **Placeholder implementations** - `return true`, `return []`, TODO comments
+3. **False confidence patterns** - `|| []` fallbacks that mask fetch failures
+4. **Suppression abuse** - `@ts-ignore`, `eslint-disable` to hide type errors
+
+These patterns pass every linter and compile successfully. AST tools see valid structure. Only pattern-based detection catches the **semantic intent** behind the code.
+
+### When to Use What
+
+| Tool | Use For |
+|:-----|:--------|
+| ESLint/TSLint | Style consistency, syntax rules, unused code |
+| Tree-sitter | Syntax highlighting, code navigation, refactoring |
+| TypeScript | Type safety, compile-time errors |
+| **CodeSentinel** | Agent-generated deceptions, error hiding, incomplete implementations |
+
+CodeSentinel complements these tools - it catches what they structurally cannot.
+
 ## Features
 
 - **Security Analysis** (16 patterns): Hardcoded secrets, SQL injection, XSS, command injection, insecure crypto, disabled SSL, and more
@@ -286,32 +355,105 @@ CodeSentinel detects language from file extensions:
 
 ## Extending CodeSentinel
 
-Add custom patterns by editing files in `src/analyzers/`:
+CodeSentinel uses a **data-driven pattern system** that separates pattern definitions from regex generation. This makes adding new patterns easier and more maintainable.
 
+### Project Structure
+
+```
+src/
+├── patterns/
+│   ├── types.ts           # Type definitions for pattern configs
+│   ├── builders.ts        # Functions that generate regex from configs
+│   ├── compiler.ts        # Compiles definitions to executable patterns
+│   └── definitions/
+│       ├── security.ts    # Security vulnerability patterns
+│       ├── deceptive.ts   # Error-hiding patterns
+│       ├── placeholders.ts # Incomplete code patterns
+│       ├── errors.ts      # Code smell patterns
+│       └── index.ts       # Exports all definitions
+├── analyzers/
+│   ├── core.ts            # Unified analyzer using compiled patterns
+│   ├── security.ts        # Security analyzer (delegates to core)
+│   ├── deceptive.ts       # Deceptive analyzer (delegates to core)
+│   ├── placeholders.ts    # Placeholder analyzer (delegates to core)
+│   ├── errors.ts          # Error analyzer (delegates to core)
+│   └── strengths.ts       # Strength analyzer
+└── index.ts               # MCP server entry point
 ```
-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
+
+### Adding a New Pattern
+
+Instead of writing regex manually, you define **what** to detect and the system generates the regex:
+
+```typescript
+// Old approach (manual regex)
+{
+  id: 'CS-DEC001',
+  pattern: /catch\s*\([^)]*\)\s*\{\s*\}/g,  // Error-prone
+  title: 'Empty Catch Block',
+  // ...
+}
+
+// New approach (data-driven)
+{
+  id: 'CS-DEC001',
+  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.',
+  match: {
+    type: 'catch_handler',
+    behavior: 'empty'
+  }
+}
 ```
 
-Each pattern follows this structure:
+### Available Match Types
+
+| Match Type | Description | Example Config |
+|:-----------|:------------|:---------------|
+| `empty_block` | Empty catch/finally/promise blocks | `{ type: 'empty_block', constructs: ['catch', '.catch'] }` |
+| `function_call` | Function/method calls | `{ type: 'function_call', names: ['eval', 'exec'] }` |
+| `returns_only` | Return statements with specific values | `{ type: 'returns_only', values: ['null', '[]', '{}'] }` |
+| `contains_text` | Text in comments/strings | `{ type: 'contains_text', terms: ['TODO', 'FIXME'], context: 'comment' }` |
+| `fallback_value` | Fallback patterns | `{ type: 'fallback_value', operators: ['\|\|'], values: ['[]'] }` |
+| `catch_handler` | Catch block behaviors | `{ type: 'catch_handler', behavior: 'empty' }` |
+| `promise_catch` | Promise .catch() behaviors | `{ type: 'promise_catch', behavior: 'returns_silent' }` |
+| `comment_marker` | TODO/FIXME/HACK markers | `{ type: 'comment_marker', markers: ['TODO', 'FIXME'] }` |
+| `string_literal` | Patterns inside strings | `{ type: 'string_literal', patterns: ['password', 'secret'] }` |
+| `secret_pattern` | API keys and tokens | `{ type: 'secret_pattern', kind: 'github' }` |
+| `url_pattern` | URL patterns | `{ type: 'url_pattern', protocol: 'http', excludeLocalhost: true }` |
+| `suppression_comment` | Linter suppressions | `{ type: 'suppression_comment', tools: ['ts-ignore', 'eslint-disable'] }` |
+| `type_cast` | Type casts | `{ type: 'type_cast', targets: ['any'] }` |
+| `comparison` | Comparison operators | `{ type: 'comparison', operators: ['==', '!='] }` |
+| `loop_pattern` | Loop patterns | `{ type: 'loop_pattern', kind: 'while_true' }` |
+| `raw_regex` | Escape hatch for complex patterns | `{ type: 'raw_regex', pattern: 'your-regex', flags: 'gi' }` |
+
+### Step-by-Step: Adding a Pattern
+
+1. **Choose the category** - security, deceptive, placeholder, or error
+2. **Open the definition file** - `src/patterns/definitions/<category>.ts`
+3. **Add a new pattern definition** using the appropriate match type
+4. **Build** - `npm run build`
+5. **Test** - Use the MCP inspector to verify detection
+
+### Pattern Definition Structure
 
 ```typescript
 {
-  id: 'CS-SEC001',           // Unique ID with category prefix
-  pattern: /regex/g,          // RegExp to match
-  title: 'Short description',
-  description: 'Detailed explanation',
-  severity: 'critical',       // critical | high | medium | low | info
-  category: 'security',
-  suggestion: 'How to fix',
-  verification: {             // Optional: reduce false positives
-    assumption: 'What we assume is true',
-    confirmIf: 'When to confirm as real issue',
-    falsePositiveIf: 'When to dismiss'
+  id: string;              // Unique ID: CS-<CAT><NUM> (e.g., CS-SEC001)
+  title: string;           // Short description (displayed in results)
+  description: string;     // Detailed explanation of the issue
+  severity: Severity;      // 'critical' | 'high' | 'medium' | 'low' | 'info'
+  category: Category;      // 'security' | 'deceptive' | 'placeholder' | 'error'
+  suggestion?: string;     // How to fix the issue
+  match: MatchConfig;      // What to detect (see match types above)
+  verification?: {         // Optional: reduce false positives
+    status: 'needs_verification' | 'confirmed';
+    assumption?: string;
+    confirmIf?: string;
+    falsePositiveIf?: string;
   }
 }
 ```

package/build/analyzers/core.d.ts

@@ -0,0 +1,7 @@
+import { Issue, Category } from '../types.js';
+export declare function analyzeWithPatterns(code: string, filename: string, category: Category): Issue[];
+export declare function analyzeSecurityWithPatterns(code: string, filename: string): Issue[];
+export declare function analyzeDeceptiveWithPatterns(code: string, filename: string): Issue[];
+export declare function analyzePlaceholdersWithPatterns(code: string, filename: string): Issue[];
+export declare function analyzeErrorsWithPatterns(code: string, filename: string): Issue[];
+export declare function analyzeAllWithPatterns(code: string, filename: string): Issue[];

package/build/analyzers/core.js

@@ -0,0 +1,69 @@
+// Core analyzer - uses compiled patterns from the data-driven system
+import { getCompiledPatterns } from '../patterns/index.js';
+// Analyze code using compiled patterns
+export function analyzeWithPatterns(code, filename, category) {
+    const issues = [];
+    const lines = code.split('\n');
+    const compiledPatterns = getCompiledPatterns(category);
+    for (const pattern of compiledPatterns) {
+        for (const regex of pattern.patterns) {
+            // Reset regex state for global patterns
+            regex.lastIndex = 0;
+            let match;
+            while ((match = regex.exec(code)) !== null) {
+                // Calculate line number
+                const beforeMatch = code.substring(0, match.index);
+                const lineNumber = beforeMatch.split('\n').length;
+                const lineContent = lines[lineNumber - 1] || '';
+                const matchedValue = match[0];
+                // Build verification with actual values substituted
+                let verification = pattern.verification;
+                if (verification) {
+                    verification = {
+                        ...verification,
+                        commands: verification.commands?.map(cmd => cmd
+                            .replace(/<matched_value>/g, matchedValue.substring(0, 20) + '...')
+                            .replace(/<filename>/g, filename))
+                    };
+                }
+                issues.push({
+                    id: pattern.id,
+                    category: pattern.category,
+                    severity: pattern.severity,
+                    title: pattern.title,
+                    description: pattern.description,
+                    line: lineNumber,
+                    code: lineContent.trim(),
+                    suggestion: pattern.suggestion,
+                    verification
+                });
+                // Prevent infinite loops for patterns without global flag
+                if (!regex.global)
+                    break;
+            }
+        }
+    }
+    return issues;
+}
+// Convenience functions for each category
+export function analyzeSecurityWithPatterns(code, filename) {
+    return analyzeWithPatterns(code, filename, 'security');
+}
+export function analyzeDeceptiveWithPatterns(code, filename) {
+    return analyzeWithPatterns(code, filename, 'deceptive');
+}
+export function analyzePlaceholdersWithPatterns(code, filename) {
+    return analyzeWithPatterns(code, filename, 'placeholder');
+}
+export function analyzeErrorsWithPatterns(code, filename) {
+    return analyzeWithPatterns(code, filename, 'error');
+}
+// Analyze all categories at once
+export function analyzeAllWithPatterns(code, filename) {
+    return [
+        ...analyzeSecurityWithPatterns(code, filename),
+        ...analyzeDeceptiveWithPatterns(code, filename),
+        ...analyzePlaceholdersWithPatterns(code, filename),
+        ...analyzeErrorsWithPatterns(code, filename),
+    ];
+}

package/build/analyzers/deceptive.js

@@ -1,200 +1,7 @@
-// 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.'
-    }
-];
+// Deceptive pattern analyzer - uses data-driven pattern system
+// This file now delegates to the core analyzer with compiled patterns
+import { analyzeDeceptiveWithPatterns } from './core.js';
+// Main export - uses the data-driven pattern system
 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;
+    return analyzeDeceptiveWithPatterns(code, filename);
 }