crucible-mcp 0.4.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

crucible/knowledge/principles/SYSTEM_DESIGN.md

@@ -0,0 +1,153 @@
+---
+name: System Design
+description: Architecture patterns, scalability, distributed systems
+triggers: [architecture, system-design, scalability, distributed]
+type: principle
+---
+
+# System Design Principles
+
+---
+
+## Monolith to Microservices
+
+```
+Progression:
+├── Monolith: One deployable, one database
+├── Modular monolith: Clear boundaries, could split
+├── Microservices: Multiple deployables, distributed
+
+Indicators to split:
+├── Teams blocked by shared codebase
+├── Components have different scaling requirements
+├── Regulatory isolation required
+└── Deployment coupling causes issues
+```
+
+---
+
+## Reference Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                    Client                        │
+│            (Web / Mobile / CLI)                  │
+└─────────────────────┬───────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────┐
+│                 API Layer                        │
+│         (Next.js API / tRPC / REST)             │
+└─────────────────────┬───────────────────────────┘
+                      │
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼
+┌─────────────┐ ┌───────────┐ ┌───────────────┐
+│  Database   │ │   Cache   │ │  File Storage │
+│ (Postgres)  │ │  (Redis)  │ │     (S3)      │
+└─────────────┘ └───────────┘ └───────────────┘
+```
+
+---
+
+## Stateless Servers
+
+App servers should hold no state.
+
+```
+Stateful patterns (avoid):
+├── Session stored in server memory
+├── Uploaded files on local disk
+├── In-memory cache per instance
+└── Breaks on horizontal scaling
+
+Stateless patterns:
+├── Session in database or JWT
+├── Files in S3/object storage
+├── Cache in Redis (shared)
+└── Any server can handle any request
+```
+
+---
+
+## Scaling
+
+```
+Vertical (scale up):
+├── Larger server instance
+├── No code changes required
+└── Simpler to operate
+
+Horizontal (scale out):
+├── Multiple server instances
+├── Requires stateless design
+└── More complex to operate
+```
+
+---
+
+## Async Processing
+
+```
+Queue candidates:
+├── Emails / notifications
+├── Image processing
+├── Report generation
+├── Third-party API calls
+└── Any operation that can fail and retry
+```
+
+---
+
+## Caching
+
+```
+Good candidates:
+├── Read-heavy, write-light data
+├── Expensive to compute
+├── Infrequent changes
+├── Stale data acceptable
+
+Poor candidates:
+├── Frequently changing data
+├── Strong consistency required
+├── Already fast enough
+```
+
+Invalidation strategies: time-based expiry, event-based invalidation, cache-aside pattern.
+
+---
+
+## Idempotency
+
+Operations that can be retried should produce the same result.
+
+```typescript
+// Non-idempotent: double-charge on retry
+stripe.charge(userId, amount);
+
+// Idempotent: same result on retry
+stripe.charge(userId, amount, { idempotencyKey });
+```
+
+---
+
+## Failure Handling
+
+```
+Design assumptions:
+├── External APIs will fail
+├── Database latency will spike
+├── Code has bugs
+
+Strategies:
+├── Timeouts on all external calls
+├── Retries with exponential backoff
+├── Circuit breakers
+├── Graceful degradation
+└── Health checks
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/TESTING.md

@@ -0,0 +1,129 @@
+---
+name: Testing Principles
+description: Test pyramid, unit/integration/e2e, mocking patterns
+triggers: [testing, tests, unit-tests, integration, e2e]
+type: principle
+---
+
+# Testing Principles
+
+What to test, how to structure tests, and patterns that work.
+
+---
+
+## The Pyramid
+
+```
+        /\          Few E2E (critical paths only)
+       /  \
+      /────\        Some integration (API, DB)
+     /      \
+    /────────\      Many unit tests (fast, pure)
+```
+
+---
+
+## What to Test
+
+```
+Test:
+├── Business logic (core package)
+├── Edge cases
+├── Regression bugs (write test, then fix)
+├── Complex calculations
+└── State machines
+
+Don't test:
+├── Framework behavior
+├── Third-party libraries
+├── Implementation details
+├── Things that change constantly (UI specifics)
+└── Obvious code (getters, setters)
+```
+
+---
+
+## FP Makes Testing Easy
+
+Pure functions = same input, same output. No mocking needed.
+
+```typescript
+const calculateFee = (amount: Cents): Cents => {
+  return Math.round(amount * 0.01) as Cents;
+};
+
+test('calculates 1% fee', () => {
+  expect(calculateFee(1000 as Cents)).toBe(10);
+  expect(calculateFee(999 as Cents)).toBe(10);
+  expect(calculateFee(100 as Cents)).toBe(1);
+});
+```
+
+---
+
+## Test Naming
+
+```typescript
+// Vague
+test('it works', () => { ... });
+
+// Descriptive
+test('calculateFee rounds up for fractional cents', () => { ... });
+test('returns NOT_FOUND when user does not exist', () => { ... });
+```
+
+---
+
+## Integration Tests
+
+Test real behavior, not mocks.
+
+```typescript
+// Mocking everything
+jest.mock('../database');
+jest.mock('../stripe');
+// What are you even testing?
+
+// Test real behavior with test database
+beforeEach(() => db.reset());
+test('creates user in database', async () => {
+  await createUser({ email: 'test@example.com' });
+  const user = await db.user.findFirst({ where: { email: 'test@example.com' } });
+  expect(user).not.toBeNull();
+});
+```
+
+---
+
+## Property-Based Testing
+
+For invariants that should always hold:
+
+```typescript
+import fc from 'fast-check';
+
+test('fee is always positive', () => {
+  fc.assert(
+    fc.property(fc.integer({ min: 1 }), (amount) => {
+      return calculateFee(amount as Cents) >= 0;
+    })
+  );
+});
+```
+
+---
+
+## The Rule
+
+```
+If you find a bug:
+1. Write a test that reproduces it
+2. Watch it fail
+3. Fix the bug
+4. Watch it pass
+5. Never have that bug again
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/TYPE_SAFETY.md

@@ -0,0 +1,170 @@
+---
+name: Type Safety
+description: Type annotations, generics, strict mode, type guards
+triggers: [types, typescript, typing, mypy, type-safety]
+type: principle
+---
+
+# Type Safety Principles
+
+Patterns for making invalid states unrepresentable.
+
+---
+
+## No `any`
+
+```typescript
+// any (defeats the purpose of TypeScript)
+const process = (data: any) => { ... }
+
+// unknown + narrowing
+const process = (data: unknown) => {
+  if (typeof data === 'string') {
+    // TypeScript knows it's a string here
+  }
+}
+```
+
+---
+
+## Branded Types
+
+Prevent mixing up similar primitives:
+
+```typescript
+// Easy to mix up
+const createTip = (pageId: string, amount: number) => { ... }
+// createTip(tipId, pageId) compiles but is wrong!
+
+// Branded types
+type PageId = string & { readonly _brand: 'PageId' };
+type TipId = string & { readonly _brand: 'TipId' };
+type Cents = number & { readonly _brand: 'Cents' };
+
+const createTip = (pageId: PageId, amount: Cents) => { ... }
+// createTip(tipId, pageId) → Type error!
+```
+
+---
+
+## Discriminated Unions
+
+Make invalid states unrepresentable:
+
+```typescript
+// Boolean flags (invalid states possible)
+type Response = {
+  loading: boolean;
+  error: Error | null;
+  data: Data | null;
+}
+// What if loading=true AND error is set?
+
+// Discriminated union (only valid states)
+type Response =
+  | { status: 'loading' }
+  | { status: 'error'; error: Error }
+  | { status: 'success'; data: Data };
+```
+
+---
+
+## Zod at Boundaries
+
+Validate external data, then trust the types:
+
+```typescript
+import { z } from 'zod';
+
+const TipSchema = z.object({
+  pageId: z.string().uuid(),
+  amountCents: z.number().int().positive().max(100000),
+  message: z.string().max(500).optional(),
+});
+
+type Tip = z.infer<typeof TipSchema>;
+
+// Validate at API boundary
+const handler = (req: Request) => {
+  const result = TipSchema.safeParse(req.body);
+  if (!result.success) {
+    return { error: result.error };
+  }
+  // result.data is fully typed and validated
+  return createTip(result.data);
+};
+```
+
+---
+
+## Exhaustiveness Checking
+
+TypeScript tells you when you miss a case:
+
+```typescript
+type Status = 'pending' | 'active' | 'cancelled';
+
+const getLabel = (status: Status): string => {
+  switch (status) {
+    case 'pending': return 'Pending';
+    case 'active': return 'Active';
+    // TypeScript error: 'cancelled' not handled
+  }
+};
+
+// Force exhaustiveness with never
+const assertNever = (x: never): never => {
+  throw new Error(`Unexpected: ${x}`);
+};
+
+const getLabel = (status: Status): string => {
+  switch (status) {
+    case 'pending': return 'Pending';
+    case 'active': return 'Active';
+    case 'cancelled': return 'Cancelled';
+    default: return assertNever(status);
+  }
+};
+```
+
+---
+
+## Strict Mode
+
+Always enable:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+---
+
+## Optional vs Required
+
+Be explicit:
+
+```typescript
+// Ambiguous
+interface User {
+  name: string;
+  email: string;
+  phone: string; // Required? Or just always present?
+}
+
+// Explicit
+interface User {
+  name: string;
+  email: string;
+  phone?: string; // Optional
+}
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/review/core.py

@@ -1,8 +1,11 @@
 """Core review functionality shared between CLI and MCP server."""
 
+from __future__ import annotations
+
 from collections import Counter
 from pathlib import Path
 
+from crucible.enforcement.models import BudgetState, ComplianceConfig
 from crucible.models import Domain, Severity, ToolFinding
 from crucible.tools.delegation import (
     delegate_bandit,
@@ -313,31 +316,42 @@ def run_enforcement(
     content: str | None = None,
     changed_files: list[str] | None = None,
     repo_root: str | None = None,
-) -> tuple[list, list[str], int, int]:
-    """Run pattern assertions.
+    compliance_config: ComplianceConfig | None = None,
+) -> tuple[list, list[str], int, int, BudgetState | None]:
+    """Run pattern and LLM assertions.
 
     Args:
         path: File or directory path
         content: File content (for single file mode)
         changed_files: List of changed files (for git mode)
         repo_root: Repository root path (for git mode)
+        compliance_config: Configuration for LLM compliance checking (optional)
 
     Returns:
-        (enforcement_findings, errors, assertions_checked, assertions_skipped)
+        (enforcement_findings, errors, assertions_checked, assertions_skipped, budget_state)
     """
     import os
 
     from crucible.enforcement.assertions import load_assertions
+    from crucible.enforcement.compliance import run_llm_assertions, run_llm_assertions_batch
     from crucible.enforcement.models import EnforcementFinding
     from crucible.enforcement.patterns import run_pattern_assertions
 
     assertions, errors = load_assertions()
     if not assertions:
-        return [], errors, 0, 0
+        return [], errors, 0, 0, None
 
     findings: list[EnforcementFinding] = []
     checked = 0
     skipped = 0
+    budget_state: BudgetState | None = None
+
+    # Default compliance config if not provided
+    if compliance_config is None:
+        compliance_config = ComplianceConfig()
+
+    # Collect files for batch LLM processing
+    files_for_llm: list[tuple[str, str]] = []
 
     if changed_files and repo_root:
         # Git mode: check each changed file
@@ -346,26 +360,67 @@ def run_enforcement(
             try:
                 with open(full_path) as f:
                     file_content = f.read()
+
+                # Run pattern assertions
                 f_findings, c, s = run_pattern_assertions(file_path, file_content, assertions)
                 findings.extend(f_findings)
                 checked = max(checked, c)
                 skipped = max(skipped, s)
+
+                # Collect for LLM processing
+                if compliance_config.enabled:
+                    files_for_llm.append((file_path, file_content))
             except OSError:
                 pass  # File may have been deleted
+
+        # Run LLM assertions in batch
+        if files_for_llm and compliance_config.enabled:
+            llm_findings, budget_state, llm_errors = run_llm_assertions_batch(
+                files_for_llm, assertions, compliance_config
+            )
+            findings.extend(llm_findings)
+            errors.extend(llm_errors)
+            if budget_state:
+                skipped += budget_state.assertions_skipped
+
     elif content is not None:
         # Single file with provided content
         f_findings, checked, skipped = run_pattern_assertions(path, content, assertions)
         findings.extend(f_findings)
+
+        # Run LLM assertions
+        if compliance_config.enabled:
+            llm_findings, budget_state, llm_errors = run_llm_assertions(
+                path, content, assertions, compliance_config
+            )
+            findings.extend(llm_findings)
+            errors.extend(llm_errors)
+            if budget_state:
+                skipped += budget_state.assertions_skipped
+
     elif os.path.isfile(path):
         # Single file
         try:
             with open(path) as f:
                 file_content = f.read()
-            findings, checked, skipped = run_pattern_assertions(path, file_content, assertions)
+
+            p_findings, checked, skipped = run_pattern_assertions(path, file_content, assertions)
+            findings.extend(p_findings)
+
+            # Run LLM assertions
+            if compliance_config.enabled:
+                llm_findings, budget_state, llm_errors = run_llm_assertions(
+                    path, file_content, assertions, compliance_config
+                )
+                findings.extend(llm_findings)
+                errors.extend(llm_errors)
+                if budget_state:
+                    skipped += budget_state.assertions_skipped
         except OSError as e:
             errors.append(f"Failed to read {path}: {e}")
+
     elif os.path.isdir(path):
-        # Directory
+        # Directory - collect all files for batch processing
         for root, _, files in os.walk(path):
             for fname in files:
                 fpath = os.path.join(root, fname)
@@ -373,11 +428,27 @@ def run_enforcement(
                 try:
                     with open(fpath) as f:
                         file_content = f.read()
+
+                    # Run pattern assertions
                     f_findings, c, s = run_pattern_assertions(rel_path, file_content, assertions)
                     findings.extend(f_findings)
                     checked = max(checked, c)
                     skipped = max(skipped, s)
+
+                    # Collect for LLM processing
+                    if compliance_config.enabled:
+                        files_for_llm.append((rel_path, file_content))
                 except (OSError, UnicodeDecodeError):
                     pass  # Skip unreadable files
 
-    return findings, errors, checked, skipped
+        # Run LLM assertions in batch
+        if files_for_llm and compliance_config.enabled:
+            llm_findings, budget_state, llm_errors = run_llm_assertions_batch(
+                files_for_llm, assertions, compliance_config
+            )
+            findings.extend(llm_findings)
+            errors.extend(llm_errors)
+            if budget_state:
+                skipped += budget_state.assertions_skipped
+
+    return findings, errors, checked, skipped, budget_state