@corbat-tech/coding-standards-mcp 1.1.0 → 2.1.0

package/README.md

@@ -22,6 +22,8 @@
 
 **Works with GitHub Copilot, Continue, Cline, Tabnine, Amazon Q, and [25+ more tools](docs/compatibility.md)**
 
+⚡ **Try it in 30 seconds** — just add the config below and start coding.
+
 </div>
 
 ---
@@ -32,13 +34,16 @@ AI-generated code works, but rarely passes code review:
 
 | Without Corbat | With Corbat |
 |----------------|-------------|
+| Methods with 50+ lines | Max 20 lines per method |
 | No dependency injection | Proper DI with interfaces |
-| Missing error handling | Custom error types with context |
-| Basic tests (if any) | 80%+ coverage with TDD |
-| God classes, long methods | SOLID, max 20 lines/method |
-| Fails SonarQube | Passes quality gates |
+| `throw new Error('failed')` | Custom exceptions with context |
+| Missing or minimal tests | Tests included, TDD approach |
+| God classes, mixed concerns | SOLID principles, clean layers |
+| Works on my machine | Production-ready patterns |
+
+**Sound familiar?** You spend more time fixing AI code than writing it yourself.
 
-**Result:** Production-ready code that passes code review.
+**Corbat MCP solves this** by injecting your team's coding standards *before* the AI generates code — not after.
 
 ---
 
@@ -70,140 +75,252 @@ AI-generated code works, but rarely passes code review:
 
 > [Complete setup guide](docs/setup.md) for all 25+ tools
 
-**3. Done!** Corbat auto-detects your stack.
+**3. Done!** Corbat auto-detects your stack and applies the right standards.
 
-```
-You: "Create a payment service"
+> **Zero overhead.** Corbat runs locally and adds ~50ms to detect your stack. After that, it's just context for the AI.
 
-Corbat: ✓ Detected: Java 21, Spring Boot 3, Maven
-        ✓ Profile: java-spring-backend
-        ✓ Architecture: Hexagonal + DDD
-        ✓ Testing: TDD, 80%+ coverage
-```
+> **Fully customizable.** Don't like a rule? Override it in `.corbat.json`. [Jump to customization →](#customize)
 
 ---
 
-## Benchmark Results
-
-Tested across 20 real-world scenarios:
-
-| Metric | Without | With | Impact |
-|--------|:-------:|:----:|:------:|
-| **Quality Score** | 63/100 | 93/100 | +48% |
-| **Code Smells** | 43 | 0 | -100% |
-| **SOLID Compliance** | 50% | 89% | +78% |
-| **Tests Generated** | 219 | 558 | +155% |
-| **SonarQube** | FAIL | PASS | Fixed |
-
-[View detailed benchmark report with code samples](docs/comparison-tests/RESULTS-REPORT.md)
-
----
+## See It In Action
 
-## Code Comparison
+```
+You: "Create a user registration service"
+```
 
-### Before: Without Corbat MCP
+**Without Corbat**, you get:
 
 ```typescript
 class UserService {
-  private users: User[] = [];
+  private users: Map<string, User> = new Map();
 
-  getUser(id: string) {
-    return this.users.find(u => u.id === id);
-  }
-
-  createUser(name: string, email: string) {
-    const user = { id: Date.now(), name, email };
-    this.users.push(user);
+  register(name: string, email: string, password: string) {
+    if (!name || !email || !password) throw new Error('Invalid input');
+    const user = { id: crypto.randomUUID(), name, email, password };
+    this.users.set(user.id, user);
     return user;
   }
 }
-// Problems: returns undefined, no validation, no DI, no tests
+// ✗ Hardcoded storage  ✗ Password in plain text  ✗ Generic error  ✗ No tests
 ```
 
-### After: With Corbat MCP
+**With Corbat**, you get:
 
 ```typescript
+// Domain
 interface UserRepository {
-  findById(id: UserId): User | null;
-  save(user: User): void;
+  save(user: User): Promise<void>;
+  findByEmail(email: string): Promise<User | null>;
 }
 
-class UserService {
+class EmailAlreadyExistsError extends Error {
+  constructor(email: string) {
+    super(`Email already registered: ${email}`);
+  }
+}
+
+// Application
+class RegisterUserUseCase {
   constructor(
     private readonly repository: UserRepository,
-    private readonly idGenerator: IdGenerator
+    private readonly hasher: PasswordHasher
   ) {}
 
-  getUser(id: UserId): User {
-    const user = this.repository.findById(id);
-    if (!user) throw new UserNotFoundError(id);
-    return user;
-  }
+  async execute(input: RegisterUserInput): Promise<User> {
+    const existing = await this.repository.findByEmail(input.email);
+    if (existing) throw new EmailAlreadyExistsError(input.email);
 
-  createUser(input: CreateUserInput): User {
-    this.validateInput(input);
-    const user = User.create(
-      this.idGenerator.generate(),
-      input.name.trim(),
-      input.email.toLowerCase()
-    );
-    this.repository.save(user);
+    const user = User.create({
+      ...input,
+      password: await this.hasher.hash(input.password)
+    });
+    await this.repository.save(user);
     return user;
   }
 }
-// ✓ Dependency injection ✓ Custom errors ✓ Validation ✓ 15 tests
+// ✓ Repository interface  ✓ Password hashing  ✓ Custom error  ✓ Testable
 ```
 
+```typescript
+// Test included
+describe('RegisterUserUseCase', () => {
+  const repository = { save: vi.fn(), findByEmail: vi.fn() };
+  const hasher = { hash: vi.fn() };
+  const useCase = new RegisterUserUseCase(repository, hasher);
+
+  beforeEach(() => vi.clearAllMocks());
+
+  it('should hash password before saving', async () => {
+    repository.findByEmail.mockResolvedValue(null);
+    hasher.hash.mockResolvedValue('hashed_password');
+
+    await useCase.execute({ name: 'John', email: 'john@test.com', password: 'secret' });
+
+    expect(hasher.hash).toHaveBeenCalledWith('secret');
+    expect(repository.save).toHaveBeenCalledWith(
+      expect.objectContaining({ password: 'hashed_password' })
+    );
+  });
+
+  it('should reject duplicate emails', async () => {
+    repository.findByEmail.mockResolvedValue({ id: '1', email: 'john@test.com' });
+
+    await expect(
+      useCase.execute({ name: 'John', email: 'john@test.com', password: 'secret' })
+    ).rejects.toThrow(EmailAlreadyExistsError);
+  });
+});
+```
+
+**This is what "passes code review on the first try" looks like.**
+
+---
+
+## What Corbat Enforces
+
+Corbat injects these guardrails before code generation:
+
+### Code Quality
+| Rule | Why It Matters |
+|------|----------------|
+| **Max 20 lines per method** | Readable, testable, single-purpose functions |
+| **Max 200 lines per class** | Single Responsibility Principle |
+| **Meaningful names** | No `data`, `info`, `temp`, `x` |
+| **No magic numbers** | Constants with descriptive names |
+
+### Architecture
+| Rule | Why It Matters |
+|------|----------------|
+| **Interfaces for dependencies** | Testable code, easy mocking |
+| **Layer separation** | Domain logic isolated from infrastructure |
+| **Hexagonal/Clean patterns** | Framework-agnostic business rules |
+
+### Error Handling
+| Rule | Why It Matters |
+|------|----------------|
+| **Custom exceptions** | `UserNotFoundError` vs `Error('not found')` |
+| **Error context** | Include IDs, values, state in errors |
+| **No empty catches** | Every error handled or propagated |
+
+### Security (verified against OWASP Top 10)
+| Rule | Why It Matters |
+|------|----------------|
+| **Input validation** | Reject bad data at boundaries |
+| **No hardcoded secrets** | Environment variables only |
+| **Parameterized queries** | Prevent SQL injection |
+| **Output encoding** | Prevent XSS |
+
+---
+
+## Benchmark Results v3.0
+
+We evaluated Corbat across **15 real-world scenarios** in 6 languages.
+
+### The Key Insight
+
+Corbat generates **focused, production-ready code** — not verbose boilerplate:
+
+| Scenario | With Corbat | Without Corbat | What This Means |
+|----------|:-----------:|:--------------:|-----------------|
+| Kotlin Coroutines | 236 lines | 1,923 lines | Same functionality, 8x less to maintain |
+| Java Hexagonal | 623 lines | 2,740 lines | Clean architecture without the bloat |
+| Go Clean Arch | 459 lines | 2,012 lines | Idiomatic Go, not Java-in-Go |
+| TypeScript NestJS | 395 lines | 1,554 lines | Right patterns, right size |
+
+**This isn't "less code for less code's sake"** — it's the right abstractions without over-engineering.
+
+### Value Metrics
+
+When we measure what actually matters for production code:
+
+| Metric | Result | What It Means |
+|--------|:------:|---------------|
+| **Code Reduction** | 67% | Less to maintain, review, and debug |
+| **Security** | 100% | Zero vulnerabilities across all scenarios |
+| **Maintainability** | 93% win | Easier to understand and modify |
+| **Architecture Efficiency** | 87% win | Better patterns per line of code |
+| **Cognitive Load** | -59% | Faster onboarding for new developers |
+
+📊 [Detailed value analysis](benchmarks/v3/CORBAT_VALUE_REPORT.md)
+
+### Security: Zero Vulnerabilities Detected
+
+Every scenario was analyzed using pattern detection for OWASP Top 10 vulnerabilities:
+
+- ✓ No SQL/NoSQL injection patterns
+- ✓ No XSS vulnerabilities
+- ✓ No hardcoded credentials
+- ✓ Input validation at all boundaries
+- ✓ Proper error messages (no stack traces to users)
+
+### Languages & Patterns Tested
+
+| Language | Scenarios | Patterns |
+|:--------:|:---------:|:---------|
+| ☕ Java | 5 | Spring Boot, DDD Aggregates, Hexagonal, Kafka Events, Saga |
+| 📘 TypeScript | 4 | Express REST, NestJS Clean, React Components, Next.js Full-Stack |
+| 🐍 Python | 2 | FastAPI CRUD, Repository Pattern |
+| 🐹 Go | 2 | HTTP Handlers, Clean Architecture |
+| 🦀 Rust | 1 | Axum with Repository Trait |
+| 🟣 Kotlin | 1 | Coroutines + Strategy Pattern |
+
+📖 [Full benchmark methodology](benchmarks/v3/BENCHMARK_REPORT_V3.md) · [Value analysis](benchmarks/v3/CORBAT_VALUE_REPORT.md)
+
 ---
 
 ## Built-in Profiles
 
-| Profile | Stack | Architecture | Testing |
-|---------|-------|--------------|---------|
-| `java-spring-backend` | Java 21 + Spring Boot 3 | Hexagonal + DDD + CQRS | TDD, 80%+ coverage |
-| `kotlin-spring` | Kotlin + Spring Boot 3 | Hexagonal + Coroutines | Kotest, MockK |
-| `nodejs` | Node.js + TypeScript | Clean Architecture | Vitest |
-| `nextjs` | Next.js 14+ | Feature-based + RSC | Vitest, Playwright |
-| `react` | React 18+ | Feature-based | Testing Library |
-| `vue` | Vue 3.5+ | Feature-based | Vitest |
-| `angular` | Angular 19+ | Feature modules | Jest |
-| `python` | Python + FastAPI | Hexagonal + async | pytest |
-| `go` | Go 1.22+ | Clean + idiomatic | Table-driven tests |
-| `rust` | Rust + Axum | Clean + ownership | Built-in + proptest |
-| `csharp-dotnet` | C# 12 + ASP.NET Core 8 | Clean + CQRS | xUnit, FluentAssertions |
-| `flutter` | Dart 3 + Flutter | Clean + BLoC/Riverpod | flutter_test |
-| `minimal` | Any | Basic quality rules | Optional |
-
-**Auto-detection:** Corbat reads `pom.xml`, `package.json`, `go.mod`, `Cargo.toml`, `pubspec.yaml`, `*.csproj` to select the right profile.
-
-### Architecture Patterns Enforced
-
-- **Hexagonal Architecture** — Ports & Adapters, infrastructure isolation
-- **Domain-Driven Design** — Aggregates, Value Objects, Domain Events
-- **SOLID Principles** — Single responsibility, dependency inversion
-- **Clean Code** — Max 20 lines/method, meaningful names, no magic numbers
-- **Error Handling** — Custom exceptions with context, no generic catches
-- **Testing** — TDD workflow, unit + integration, mocking strategies
+Corbat auto-detects your stack and applies the right standards:
+
+| Profile | Stack | What You Get |
+|---------|-------|--------------|
+| `java-spring-backend` | Java 21 + Spring Boot 3 | Hexagonal + DDD, TDD with 80%+ coverage |
+| `kotlin-spring` | Kotlin + Spring Boot 3 | Coroutines, Kotest + MockK |
+| `nodejs` | Node.js + TypeScript | Clean Architecture, Vitest |
+| `nextjs` | Next.js 14+ | App Router patterns, Server Components |
+| `react` | React 18+ | Hooks, Testing Library, accessible components |
+| `vue` | Vue 3.5+ | Composition API, Vitest |
+| `angular` | Angular 19+ | Standalone components, Jest |
+| `python` | Python + FastAPI | Async patterns, pytest |
+| `go` | Go 1.22+ | Idiomatic Go, table-driven tests |
+| `rust` | Rust + Axum | Ownership patterns, proptest |
+| `csharp-dotnet` | C# 12 + ASP.NET Core 8 | Clean + CQRS, xUnit |
+| `flutter` | Dart 3 + Flutter | BLoC/Riverpod, widget tests |
+
+**Auto-detection:** Corbat reads `pom.xml`, `package.json`, `go.mod`, `Cargo.toml`, etc.
 
 ---
 
-## Customize
+## When to Use Corbat
+
+| Use Case | Why Corbat Helps |
+|----------|------------------|
+| **Starting a new project** | Correct architecture from day one |
+| **Teams with juniors** | Everyone produces senior-level patterns |
+| **Strict code review standards** | AI code meets your bar automatically |
+| **Regulated industries** | Consistent security and documentation |
+| **Legacy modernization** | New code follows modern patterns |
 
-### Ready-to-use templates
+### When Corbat Might Not Be Needed
 
-Copy a production-ready configuration for your stack:
+- Quick prototypes where quality doesn't matter
+- One-off scripts you'll throw away
+- Learning projects where you want to make mistakes
 
-**[Browse 14 templates](docs/templates.md)** — Java, Python, Node.js, React, Vue, Angular, Go, Kotlin, Rust, Flutter, and more.
+---
+
+## Customize
 
-### Generate a custom profile
+### Option 1: Interactive Setup
 
 ```bash
 npx corbat-init
 ```
 
-Interactive wizard that auto-detects your stack and lets you configure architecture, DDD patterns, and quality metrics.
+Detects your stack and generates a `.corbat.json` with sensible defaults.
 
-### Manual config
+### Option 2: Manual Configuration
 
 Create `.corbat.json` in your project root:
 
@@ -214,54 +331,80 @@ Create `.corbat.json` in your project root:
     "pattern": "hexagonal",
     "layers": ["domain", "application", "infrastructure", "api"]
   },
-  "ddd": {
-    "aggregates": true,
-    "valueObjects": true,
-    "domainEvents": true
-  },
   "quality": {
     "maxMethodLines": 20,
     "maxClassLines": 200,
     "minCoverage": 80
   },
   "rules": {
-    "always": ["Use records for DTOs", "Prefer Optional over null"],
-    "never": ["Use field injection", "Catch generic Exception"]
+    "always": [
+      "Use records for DTOs",
+      "Prefer Optional over null"
+    ],
+    "never": [
+      "Use field injection",
+      "Catch generic Exception"
+    ]
   }
 }
 ```
 
+### Option 3: Use a Template
+
+**[Browse 14 ready-to-use templates](docs/templates.md)** for Java, Python, Node.js, React, Go, Rust, and more.
+
 ---
 
 ## How It Works
 
 ```
-Your Prompt ──▶ Corbat MCP ──▶ AI + Standards
-                    │
-                    ├─ 1. Detect stack (pom.xml, package.json...)
-                    ├─ 2. Classify task (feature, bugfix, refactor)
-                    ├─ 3. Load profile with architecture rules
-                    └─ 4. Inject guardrails before code generation
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│ Your Prompt │────▶│ Corbat MCP  │────▶│ AI + Rules  │
+└─────────────┘     └──────┬──────┘     └─────────────┘
+                          │
+           ┌──────────────┼──────────────┐
+           ▼              ▼              ▼
+    ┌────────────┐ ┌────────────┐ ┌────────────┐
+    │ 1. Detect  │ │ 2. Load    │ │ 3. Inject  │
+    │   Stack    │ │  Profile   │ │ Guardrails │
+    └────────────┘ └────────────┘ └────────────┘
+     pom.xml        hexagonal      max 20 lines
+     package.json   + DDD          + interfaces
+     go.mod         + SOLID        + custom errors
 ```
 
+Corbat doesn't modify AI output — it ensures the AI knows your standards *before* generating.
+
+**Important:** Corbat provides context and guidelines to the AI. The actual code quality depends on how well the AI model follows these guidelines. In our testing, models like Claude and GPT-4 consistently respect these guardrails.
+
 ---
 
 ## Documentation
 
 | Resource | Description |
 |----------|-------------|
-| [Setup Guide](docs/setup.md) | Installation for all 25+ tools |
+| [Setup Guide](docs/setup.md) | Installation for Cursor, VS Code, JetBrains, and 25+ more |
 | [Templates](docs/templates.md) | Ready-to-use `.corbat.json` configurations |
-| [Compatibility](docs/compatibility.md) | Full list of supported tools |
-| [Benchmark Report](docs/comparison-tests/RESULTS-REPORT.md) | 20 real-world tests with code samples |
-| [API Reference](docs/full-documentation.md) | Tools, prompts, and configuration |
+| [Compatibility](docs/compatibility.md) | Full list of supported AI tools |
+| [Benchmark Analysis](benchmarks/v3/BENCHMARK_REPORT_V3.md) | Detailed results from 15 scenarios |
+| [API Reference](docs/full-documentation.md) | Tools, prompts, and configuration options |
 
 ---
 
 <div align="center">
 
-**Stop fixing AI code. Start shipping it.**
+### Stop fixing AI code. Start shipping it.
+
+Add to your MCP config and you're done:
+
+```json
+{ "mcpServers": { "corbat": { "command": "npx", "args": ["-y", "@corbat-tech/coding-standards-mcp"] }}}
+```
+
+**Your code reviews will thank you.**
+
+---
 
-*Recommended by [corbat-tech](https://corbat.tech) — We use Claude Code internally, but Corbat MCP works with any MCP-compatible tool.*
+*Developed by [corbat-tech](https://corbat.tech)*
 
 </div>

package/dist/analysis/code-analyzer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Lightweight code analyzer using regex and heuristics.
+ * No AST parsing to keep it fast and dependency-free.
+ *
+ * This module provides real code analysis instead of just returning checklists.
+ * It detects anti-patterns, measures code quality metrics, and provides
+ * actionable feedback.
+ */
+export interface AnalysisIssue {
+    type: 'CRITICAL' | 'WARNING' | 'INFO';
+    rule: string;
+    message: string;
+    line?: number;
+    suggestion?: string;
+}
+export interface CodeMetrics {
+    totalLines: number;
+    codeLines: number;
+    commentLines: number;
+    methodCount: number;
+    classCount: number;
+    interfaceCount: number;
+    testCount: number;
+    maxMethodLines: number;
+    maxClassLines: number;
+    customErrorCount: number;
+    importCount: number;
+}
+export interface AnalysisResult {
+    issues: AnalysisIssue[];
+    score: number;
+    summary: string;
+    metrics: CodeMetrics;
+    passed: boolean;
+}
+/**
+ * Analyze code and return issues, metrics, and score.
+ * @throws Error if code exceeds MAX_CODE_SIZE
+ */
+export declare function analyzeCode(code: string): AnalysisResult;
+/**
+ * Format analysis result as markdown.
+ */
+export declare function formatAnalysisAsMarkdown(result: AnalysisResult): string;
+//# sourceMappingURL=code-analyzer.d.ts.map

package/dist/analysis/code-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-analyzer.d.ts","sourceRoot":"","sources":["../../src/analysis/code-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACjB;AAsLD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAkGxD;AA0OD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAwFvE"}