code-auditor-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Code Auditor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# Code Auditor
+
+A comprehensive TypeScript/JavaScript code quality audit tool that analyzes your codebase for SOLID principles compliance, DRY violations, security patterns, and more.
+
+## Features
+
+- **SOLID Principles Analysis** - Detect violations of Single Responsibility, Open/Closed, and other SOLID principles
+- **DRY (Don't Repeat Yourself)** - Find code duplication and suggest refactoring opportunities
+- **Security Pattern Analysis** - Verify authentication, authorization, and rate limiting implementations
+- **Component Architecture Review** - Analyze component structure, complexity, and best practices
+- **Data Access Patterns** - Check for SQL injection risks, performance issues, and security patterns
+- **Multiple Output Formats** - Generate HTML, JSON, or CSV reports
+- **Highly Configurable** - Customize thresholds, patterns, and analysis rules
+- **Framework Support** - Built-in support for React, Vue, Angular, Svelte, and Node.js
+- **MCP Server Integration** - Use with AI assistants like Claude for interactive code analysis
+
+## Installation
+
+### Global Installation
+```bash
+npm install -g code-auditor
+```
+
+### Local Installation
+```bash
+npm install --save-dev code-auditor
+```
+
+### From Source
+```bash
+git clone https://github.com/code-auditor/code-auditor.git
+cd code-auditor
+npm install
+npm run build
+npm link
+```
+
+## Quick Start
+
+### Basic Usage
+```bash
+# Run with default settings
+code-audit
+
+# Generate a sample configuration
+code-audit --init
+
+# Use a specific configuration
+code-audit -c .auditrc.json
+
+# Analyze a specific directory
+code-audit -p ./src
+```
+
+### Common Options
+```bash
+# Generate multiple report formats
+code-audit -f html -f json -f csv
+
+# Run specific analyzers only
+code-audit -a solid -a dry
+
+# Set minimum severity level
+code-audit -s warning
+
+# Show detailed progress
+code-audit -v
+```
+
+## Configuration
+
+The auditor looks for configuration in these locations (in order):
+1. Command line arguments
+2. `.auditrc.json` in the current directory
+3. `audit.config.json` in the current directory
+4. `audit.config.js` in the current directory
+5. Environment variables (with `AUDIT_` prefix)
+
+### Basic Configuration Example
+
+```json
+{
+  "includePaths": [
+    "src/**/*.{ts,tsx,js,jsx}"
+  ],
+  "excludePaths": [
+    "**/node_modules/**",
+    "**/*.test.ts"
+  ],
+  "enabledAnalyzers": [
+    "solid",
+    "dry",
+    "security",
+    "component",
+    "data-access"
+  ],
+  "outputFormats": ["html", "json"],
+  "outputDirectory": "./audit-reports",
+  "thresholds": {
+    "maxCritical": 0,
+    "maxWarnings": 50,
+    "minHealthScore": 80
+  }
+}
+```
+
+### Project-Specific Configurations
+
+See the `examples/` directory for pre-configured setups:
+- `nextjs.auditrc.json` - Next.js projects
+- `react.auditrc.json` - React applications
+- `node-api.auditrc.json` - Node.js APIs
+
+## Available Analyzers
+
+### SOLID Analyzer
+Checks for violations of SOLID principles:
+- Single Responsibility Principle
+- Open/Closed Principle
+- Liskov Substitution Principle
+- Interface Segregation Principle
+- Dependency Inversion Principle
+
+### DRY Analyzer
+Detects code duplication:
+- Duplicate code blocks
+- Similar function implementations
+- Repeated imports
+- String literal duplication
+
+### Security Analyzer
+Verifies security patterns:
+- Authentication wrapper usage
+- Authorization checks
+- Rate limiting implementation
+- Public endpoint identification
+
+### Component Analyzer
+Analyzes UI components:
+- Component complexity
+- Error boundary usage
+- Prop validation
+- Nesting depth
+
+### Data Access Analyzer
+Reviews database interactions:
+- SQL injection vulnerabilities
+- Query performance issues
+- Missing security filters
+- Connection patterns
+
+## CLI Options
+
+```
+Options:
+  -c, --config <file>        Load configuration from file
+  -p, --project <dir>        Project root directory
+  -i, --include <pattern>    Include files matching pattern
+  -e, --exclude <pattern>    Exclude files matching pattern
+  -a, --analyzers <name>     Enable specific analyzers
+  -f, --format <format>      Output format: html, json, csv
+  -o, --output <dir>         Output directory for reports
+  -s, --severity <level>     Minimum severity: critical, warning, suggestion
+  --fail-on-critical         Exit with error code if critical issues found
+  --no-progress              Disable progress bar
+  -v, --verbose              Show detailed progress
+  --init                     Create a sample configuration file
+  -h, --help                 Show help
+```
+
+## Programmatic API
+
+### Basic Usage
+```typescript
+import { AuditRunner } from 'code-auditor';
+
+const runner = new AuditRunner({
+  includePaths: ['src/**/*.ts'],
+  enabledAnalyzers: ['solid', 'dry']
+});
+
+const result = await runner.run();
+console.log(`Found ${result.summary.totalViolations} issues`);
+```
+
+### Quick Audit Function
+```typescript
+import { runAudit } from 'code-auditor';
+
+const result = await runAudit({
+  projectRoot: './my-project',
+  outputFormats: ['html', 'json']
+});
+```
+
+### Project-Specific Runner
+```typescript
+import { createAuditRunner } from 'code-auditor';
+
+// Pre-configured for Next.js projects
+const runner = createAuditRunner('nextjs', {
+  thresholds: {
+    maxCritical: 0
+  }
+});
+
+const result = await runner.run();
+```
+
+### Custom Analyzer
+```typescript
+import { BaseAnalyzer, AuditRunner } from 'code-auditor';
+
+class MyCustomAnalyzer extends BaseAnalyzer {
+  async analyzeFile(filePath: string, content: string) {
+    // Your analysis logic here
+  }
+}
+
+const runner = new AuditRunner();
+runner.registerAnalyzer('custom', {
+  name: 'My Custom Analyzer',
+  instance: new MyCustomAnalyzer()
+});
+```
+
+## Understanding Reports
+
+### Health Score
+The health score (0-100) is calculated based on:
+- Number of violations per file
+- Severity of violations (critical issues have more impact)
+- Overall code coverage analyzed
+
+### Severity Levels
+- **Critical** 🔴 - Must be fixed immediately (security vulnerabilities, major bugs)
+- **Warning** 🟡 - Should be addressed soon (poor patterns, minor security issues)
+- **Suggestion** 🔵 - Nice to have improvements (optimizations, best practices)
+
+### Report Formats
+
+#### HTML Report
+Interactive web report with:
+- Summary dashboard
+- Sortable violation lists
+- Code snippets with line numbers
+- Recommendations with examples
+- Trend charts (when historical data available)
+
+#### JSON Report
+Machine-readable format containing:
+- Complete violation details
+- Metrics and statistics
+- Recommendations
+- MCP-compatible format option
+
+#### CSV Report
+Spreadsheet-friendly format with:
+- Summary metrics
+- Violation counts by category
+- Trend data for tracking
+
+## CI/CD Integration
+
+### GitHub Actions
+```yaml
+- name: Run Code Audit
+  run: |
+    npm install -g code-auditor
+    code-audit -c .auditrc.json --fail-on-critical
+```
+
+### GitLab CI
+```yaml
+code-audit:
+  script:
+    - npm install -g code-auditor
+    - code-audit -f json -o reports/
+  artifacts:
+    reports:
+      paths:
+        - reports/
+```
+
+### Jenkins
+```groovy
+stage('Code Audit') {
+  steps {
+    sh 'npm install -g code-auditor'
+    sh 'code-audit --fail-on-critical'
+  }
+}
+```
+
+## Environment Variables
+
+- `AUDIT_OUTPUT_DIR` - Override output directory
+- `AUDIT_VERBOSE` - Enable verbose output
+- `AUDIT_MIN_SEVERITY` - Set minimum severity level
+- `AUDIT_FAIL_ON_CRITICAL` - Exit with error on critical issues
+- `AUDIT_ENABLED_ANALYZERS` - Comma-separated list of analyzers
+
+## MCP Server Integration
+
+Code Auditor includes a built-in MCP (Model Context Protocol) server that enables AI assistants like Claude to analyze your code interactively.
+
+### Setting up with Claude Desktop
+
+1. Install code-auditor globally:
+   ```bash
+   npm install -g code-auditor
+   ```
+
+2. Add to your Claude Desktop configuration:
+   ```json
+   {
+     "mcpServers": {
+       "code-auditor": {
+         "command": "npx",
+         "args": ["code-auditor-mcp"]
+       }
+     }
+   }
+   ```
+
+   Configuration file locations:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - Linux: `~/.config/Claude/claude_desktop_config.json`
+
+3. Restart Claude Desktop
+
+### Available MCP Tools
+
+- **audit_run** - Run a comprehensive code audit
+- **audit_check_health** - Get a quick health score for your codebase
+
+### Usage Examples with Claude
+
+```
+"Run a code audit on my project and show me the critical issues"
+"Check the health score of the src directory"
+"Analyze my code for SOLID principle violations"
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/code-auditor/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/yourusername/code-auditor/discussions)
+- **Documentation**: [Full Documentation](https://yourusername.github.io/code-auditor)
+
+## Acknowledgments
+
+Originally extracted from the HHRA ORG-Tracker project, this tool has been generalized for use with any TypeScript/JavaScript codebase.

package/configs/hhra-compat.json

@@ -0,0 +1,168 @@
+{
+  "projectRoot": "../..",
+  "reportTitle": "HHRA Architecture & Code Quality Audit",
+  
+  "includePaths": [
+    "app/**/*.{ts,tsx}",
+    "src/**/*.{ts,tsx}",
+    "scripts/**/*.ts"
+  ],
+  
+  "excludePaths": [
+    "**/node_modules/**",
+    "**/.next/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/*.test.{ts,tsx}",
+    "**/*.spec.{ts,tsx}",
+    "**/tests/**",
+    "**/e2e/**",
+    "**/.vercel/**",
+    "**/public/**",
+    "code-auditor/**"
+  ],
+  
+  "enabledAnalyzers": [
+    "component",
+    "security",
+    "solid",
+    "dry",
+    "data-access"
+  ],
+  
+  "analyzerConfig": {
+    "security": {
+      "authPatterns": [
+        "withAuth",
+        "withAdminAuth",
+        "requireAuth",
+        "SessionAuth",
+        "useSession"
+      ],
+      "adminPatterns": [
+        "withAdminAuth",
+        "requireAdmin",
+        "adminOnly"
+      ],
+      "rateLimitPatterns": [
+        "rateLimit",
+        "withRateLimit",
+        "rateLimitGuard"
+      ],
+      "publicPatterns": [
+        "public",
+        "noAuth",
+        "skipAuth"
+      ]
+    },
+    
+    "component": {
+      "frameworkPatterns": {
+        "react": {
+          "components": ["*.tsx", "*.jsx"],
+          "hooks": ["use*"],
+          "context": ["*Context", "*Provider"]
+        }
+      },
+      "checkErrorBoundaries": true,
+      "checkPropTypes": false,
+      "maxComplexity": 15,
+      "maxNesting": 4
+    },
+    
+    "data-access": {
+      "databasePatterns": {
+        "postgres": ["app-db", "org-tracker-db", "@neondatabase", "neon"],
+        "drizzle": ["drizzle-orm", "db.query", "db.select", "db.insert", "db.update", "db.delete"]
+      },
+      "ormPatterns": {
+        "drizzle": ["drizzle-orm", "drizzle", "schema"]
+      },
+      "securityPatterns": {
+        "parameterized": ["?", "$1", ":param", "prepared"],
+        "sanitized": ["sanitize", "escape", "clean", "safe"]
+      },
+      "performanceThresholds": {
+        "maxJoins": 5,
+        "warnOnSelectStar": true
+      }
+    },
+    
+    "solid": {
+      "maxMethodsPerClass": 10,
+      "maxLinesPerMethod": 50,
+      "maxParametersPerMethod": 4,
+      "maxImportsPerFile": 20,
+      "maxComplexity": 10
+    },
+    
+    "dry": {
+      "minLineThreshold": 5,
+      "similarityThreshold": 0.85,
+      "excludePatterns": [
+        "**/*.test.ts",
+        "**/*.spec.ts",
+        "**/tests/**",
+        "**/migrations/**"
+      ],
+      "checkImports": true,
+      "checkStrings": true
+    }
+  },
+  
+  "customPatterns": {
+    "components": [
+      "**/app/**/page.{ts,tsx}",
+      "**/app/**/layout.{ts,tsx}",
+      "**/app/**/error.{ts,tsx}",
+      "**/app/**/loading.{ts,tsx}",
+      "**/app/**/not-found.{ts,tsx}",
+      "**/components/**/*.{ts,tsx}",
+      "**/app/components/**/*.{ts,tsx}"
+    ],
+    "endpoints": [
+      "**/app/api/**/route.{ts,tsx}",
+      "**/pages/api/**/*.{ts,tsx}",
+      "**/api/**/*.{ts,tsx}"
+    ],
+    "tests": [
+      "**/*.test.{ts,tsx}",
+      "**/*.spec.{ts,tsx}",
+      "**/tests/**",
+      "**/e2e/**",
+      "**/__tests__/**"
+    ]
+  },
+  
+  "outputFormats": ["html", "json"],
+  "outputDirectory": "./audit-reports",
+  
+  "minSeverity": "suggestion",
+  "failOnCritical": false,
+  "verbose": false,
+  "showProgress": true,
+  
+  "thresholds": {
+    "maxCritical": 0,
+    "maxWarnings": 100,
+    "minHealthScore": 75,
+    "maxComplexity": 10,
+    "maxDuplication": 10
+  },
+  
+  "reportTheme": {
+    "primaryColor": "#0070f3",
+    "criticalColor": "#e00",
+    "warningColor": "#f5a623",
+    "suggestionColor": "#0070f3"
+  },
+  
+  "integrations": {
+    "ci": {
+      "provider": "github",
+      "failOnThreshold": true,
+      "commentOnPR": false
+    }
+  }
+}

package/dist/analyzers/analyzerUtils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Functional utilities for analyzer development
+ * These replace the BaseAnalyzer class with composable functions
+ */
+import * as ts from 'typescript';
+import { Violation, AnalyzerResult, SeverityLevel } from '../types.js';
+export { parseTypeScriptFile } from '../utils/astParser.js';
+export { getLineAndColumn, getNodeText, getImports, findNodesByKind } from '../utils/astUtils.js';
+/**
+ * File analyzer function - processes a single file
+ */
+export type FileAnalyzerFunction = (filePath: string, sourceFile: ts.SourceFile, config: any) => Promise<Violation[]> | Violation[];
+/**
+ * Progress reporter function
+ */
+export type ProgressReporter = (current: number, total: number, file: string) => void;
+/**
+ * Standard file processing function
+ * Handles file reading, parsing, error handling, and progress reporting
+ */
+export declare function processFiles(files: string[], analyzeFile: FileAnalyzerFunction, analyzerName: string, config?: any, progressReporter?: ProgressReporter): Promise<AnalyzerResult>;
+/**
+ * Create a violation object with defaults
+ */
+export declare function createViolation(data: Violation): Violation;
+/**
+ * Get line and column from a TypeScript node
+ */
+export declare function getNodePosition(sourceFile: ts.SourceFile, node: ts.Node): {
+    line: number;
+    column: number;
+};
+/**
+ * Check if a node is exported
+ */
+export declare function isNodeExported(node: ts.Node): boolean;
+/**
+ * Get the name of a node if it has one
+ */
+export declare function getNodeName(node: ts.Node): string | undefined;
+/**
+ * Count specific node types in a subtree
+ */
+export declare function countNodesOfType<T extends ts.Node>(node: ts.Node, predicate: (node: ts.Node) => node is T): number;
+/**
+ * Find all nodes of a specific type
+ */
+export declare function findNodesOfType<T extends ts.Node>(node: ts.Node, predicate: (node: ts.Node) => node is T): T[];
+/**
+ * Traverse AST with a visitor function
+ */
+export declare function traverseAST(node: ts.Node, visitor: (node: ts.Node) => void): void;
+/**
+ * Filter violations by severity
+ */
+export declare function filterViolationsBySeverity(violations: Violation[], minSeverity?: SeverityLevel): Violation[];
+/**
+ * Sort violations by severity, file, and line
+ */
+export declare function sortViolations(violations: Violation[]): Violation[];
+/**
+ * Calculate cyclomatic complexity of a function
+ */
+export declare function calculateComplexity(node: ts.FunctionLikeDeclaration): number;
+/**
+ * Create a standard analyzer function
+ */
+export declare function createAnalyzer(name: string, fileAnalyzer: FileAnalyzerFunction, defaultConfig?: any): (files: any, config: any, options: any) => Promise<AnalyzerResult>;
+//# sourceMappingURL=analyzerUtils.d.ts.map

package/dist/analyzers/analyzerUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzerUtils.d.ts","sourceRoot":"","sources":["../../src/analyzers/analyzerUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAgB,MAAM,aAAa,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,MAAM,EAAE,GAAG,KACR,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtF;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EAAE,EACf,WAAW,EAAE,oBAAoB,EACjC,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,GAAQ,EAChB,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,OAAO,CAAC,cAAc,CAAC,CA6CzB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,GACd,SAAS,CAEX;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,IAAI,EAAE,EAAE,CAAC,IAAI,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGlC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAMrD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,GAAG,SAAS,CAQ7D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,EAAE,CAAC,IAAI,EAChD,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,GACtC,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,EAAE,CAAC,IAAI,EAC/C,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,GACtC,CAAC,EAAE,CAYL;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,GAC/B,IAAI,CAGN;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,SAAS,EAAE,EACvB,WAAW,CAAC,EAAE,aAAa,GAC1B,SAAS,EAAE,CAWb;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAcnE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,uBAAuB,GAAG,MAAM,CA4B5E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,oBAAoB,EAClC,aAAa,GAAE,GAAQ,IAET,UAAK,EAAE,WAAM,EAAE,YAAO,6BAWrC"}