@mandujs/core 0.8.2 → 0.9.0

package/src/brain/types.ts

@@ -0,0 +1,268 @@
+/**
+ * Brain v0.1 - Core Type Definitions
+ *
+ * Brain handles two responsibilities:
+ * 1. Doctor (error recovery): Guard failure analysis + minimal patch suggestions
+ * 2. Watch (error prevention): File change warnings (no blocking)
+ */
+
+import type { GuardViolation } from "../guard/rules";
+import type { RoutesManifest } from "../spec/schema";
+
+// ========== LLM Adapter Types ==========
+
+/**
+ * Message role for LLM conversations
+ */
+export type MessageRole = "system" | "user" | "assistant";
+
+/**
+ * Chat message structure
+ */
+export interface ChatMessage {
+  role: MessageRole;
+  content: string;
+}
+
+/**
+ * LLM completion options
+ */
+export interface CompletionOptions {
+  /** Temperature (0-1, lower = more deterministic) */
+  temperature?: number;
+  /** Maximum tokens to generate */
+  maxTokens?: number;
+  /** Stop sequences */
+  stop?: string[];
+}
+
+/**
+ * LLM completion result
+ */
+export interface CompletionResult {
+  content: string;
+  /** Token usage (if available) */
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+/**
+ * LLM adapter status
+ */
+export interface AdapterStatus {
+  available: boolean;
+  model: string | null;
+  error?: string;
+}
+
+/**
+ * LLM adapter configuration
+ */
+export interface AdapterConfig {
+  /** Base URL for the LLM API */
+  baseUrl: string;
+  /** Model name to use */
+  model: string;
+  /** Connection timeout in ms */
+  timeout?: number;
+}
+
+// ========== Doctor Types ==========
+
+/**
+ * Patch suggestion from Doctor
+ */
+export interface PatchSuggestion {
+  /** Target file path */
+  file: string;
+  /** Description of the change */
+  description: string;
+  /** Type of patch */
+  type: "add" | "modify" | "delete" | "command";
+  /** Content to add/modify (for add/modify types) */
+  content?: string;
+  /** Line number to modify (for modify type) */
+  line?: number;
+  /** Command to run (for command type) */
+  command?: string;
+  /** Confidence level (0-1) */
+  confidence: number;
+}
+
+/**
+ * Doctor analysis result
+ */
+export interface DoctorAnalysis {
+  /** Original violations */
+  violations: GuardViolation[];
+  /** Root cause summary */
+  summary: string;
+  /** Detailed explanation */
+  explanation: string;
+  /** Suggested patches */
+  patches: PatchSuggestion[];
+  /** Whether LLM was used for analysis */
+  llmAssisted: boolean;
+  /** Recommended next command */
+  nextCommand?: string;
+}
+
+/**
+ * Doctor options
+ */
+export interface DoctorOptions {
+  /** Whether to use LLM for enhanced analysis */
+  useLLM?: boolean;
+  /** Maximum patches to suggest */
+  maxPatches?: number;
+  /** Minimum confidence for suggestions */
+  minConfidence?: number;
+}
+
+// ========== Watch Types ==========
+
+/**
+ * Architecture rule for Watch
+ */
+export interface ArchRule {
+  /** Unique rule identifier */
+  id: string;
+  /** Human-readable rule name */
+  name: string;
+  /** Rule description */
+  description: string;
+  /** File pattern to match (glob) */
+  pattern: string;
+  /** Rule action */
+  action: "warn" | "error";
+  /** Warning message template */
+  message: string;
+  /** Optional: file extension requirement */
+  mustEndWith?: string;
+  /** Optional: forbidden imports */
+  forbiddenImports?: string[];
+  /** Optional: required patterns in content */
+  requiredPatterns?: RegExp[];
+}
+
+/**
+ * Watch warning
+ */
+export interface WatchWarning {
+  /** Rule that triggered the warning */
+  ruleId: string;
+  /** Affected file path */
+  file: string;
+  /** Warning message */
+  message: string;
+  /** Timestamp */
+  timestamp: Date;
+  /** Event type that triggered the warning */
+  event: "create" | "modify" | "delete";
+}
+
+/**
+ * Watch status
+ */
+export interface WatchStatus {
+  /** Whether watching is active */
+  active: boolean;
+  /** Root directory being watched */
+  rootDir: string | null;
+  /** Number of files being watched */
+  fileCount: number;
+  /** Recent warnings */
+  recentWarnings: WatchWarning[];
+  /** Start time */
+  startedAt: Date | null;
+}
+
+/**
+ * Watch event handler
+ */
+export type WatchEventHandler = (warning: WatchWarning) => void;
+
+// ========== Memory Types ==========
+
+/**
+ * Session memory (lightweight, no persistence)
+ */
+export interface BrainMemory {
+  /** Last Guard check result */
+  lastGuardResult: GuardViolation[] | null;
+  /** Last file diff */
+  lastDiff: string | null;
+  /** Current spec snapshot */
+  specSnapshot: RoutesManifest | null;
+  /** Session start time */
+  sessionStart: Date;
+  /** Last activity time */
+  lastActivity: Date;
+}
+
+// ========== Brain Configuration ==========
+
+/**
+ * Environment detection result
+ */
+export interface EnvironmentInfo {
+  /** Is running in CI environment */
+  isCI: boolean;
+  /** CI provider name (if detected) */
+  ciProvider?: string;
+  /** Is development environment */
+  isDevelopment: boolean;
+  /** Detected model availability */
+  modelAvailable: boolean;
+}
+
+/**
+ * Brain configuration
+ */
+export interface BrainConfig {
+  /** Whether Brain is enabled */
+  enabled: boolean;
+  /** LLM adapter configuration */
+  adapter?: AdapterConfig;
+  /** Auto-apply patches (default: false, experimental) */
+  autoApply?: boolean;
+  /** Maximum retry attempts */
+  maxRetries?: number;
+  /** Watch configuration */
+  watch?: {
+    /** Extra commands to run on violations */
+    extraCommands?: string[];
+    /** Debounce delay in ms */
+    debounceMs?: number;
+  };
+}
+
+/**
+ * Brain policy
+ */
+export interface BrainPolicy {
+  /** Auto-detection mode: auto | always | never */
+  enabled: "auto" | "always" | "never";
+  /** CI environment handling */
+  ci: boolean;
+  /** Behavior when model is not available */
+  localNoModel: "guidance-only" | "disabled";
+  /** Behavior when model is available */
+  localWithModel: boolean;
+  /** Core isolation (Brain failure doesn't affect Core) */
+  coreIsolation: boolean;
+}
+
+/**
+ * Default Brain policy
+ */
+export const DEFAULT_BRAIN_POLICY: BrainPolicy = {
+  enabled: "auto",
+  ci: false,
+  localNoModel: "guidance-only",
+  localWithModel: true,
+  coreIsolation: true,
+};

package/src/contract/contract.test.ts

@@ -0,0 +1,381 @@
+/**
+ * Contract System Tests
+ */
+
+import { describe, test, expect } from "bun:test";
+import { z } from "zod";
+import { createContract } from "./index";
+import { ContractValidator, formatValidationErrors } from "./validator";
+import type { ContractSchema } from "./schema";
+
+// Test schemas
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string().min(2),
+  createdAt: z.string().datetime(),
+});
+
+const CreateUserInput = UserSchema.omit({ id: true, createdAt: true });
+
+const UserListQuery = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+  search: z.string().optional(),
+});
+
+describe("createContract", () => {
+  test("should create a contract with definition", () => {
+    const contract = createContract({
+      description: "Users API",
+      tags: ["users"],
+      request: {
+        GET: { query: UserListQuery },
+        POST: { body: CreateUserInput },
+      },
+      response: {
+        200: z.object({ data: z.array(UserSchema) }),
+        201: z.object({ data: UserSchema }),
+        400: z.object({ error: z.string() }),
+      },
+    });
+
+    expect(contract.description).toBe("Users API");
+    expect(contract.tags).toEqual(["users"]);
+    expect(contract._validated).toBe(false);
+  });
+
+  test("should preserve request schemas", () => {
+    const contract = createContract({
+      request: {
+        GET: { query: UserListQuery },
+      },
+      response: {},
+    });
+
+    expect(contract.request.GET).toBeDefined();
+    expect(contract.request.GET!.query === UserListQuery).toBe(true);
+  });
+});
+
+describe("ContractValidator", () => {
+  const contractSchema: ContractSchema = {
+    request: {
+      GET: { query: UserListQuery },
+      POST: { body: CreateUserInput },
+    },
+    response: {
+      200: z.object({ data: z.array(UserSchema) }),
+      201: z.object({ data: UserSchema }),
+      400: z.object({ error: z.string() }),
+    },
+  };
+
+  const validator = new ContractValidator(contractSchema);
+
+  describe("validateRequest", () => {
+    test("should validate GET request with valid query", async () => {
+      const req = new Request("http://localhost/api/users?page=1&limit=10");
+      const result = await validator.validateRequest(req, "GET");
+
+      expect(result.success).toBe(true);
+    });
+
+    test("should validate GET request with default values", async () => {
+      const req = new Request("http://localhost/api/users");
+      const result = await validator.validateRequest(req, "GET");
+
+      expect(result.success).toBe(true);
+    });
+
+    test("should fail GET request with invalid query", async () => {
+      const req = new Request("http://localhost/api/users?page=-1&limit=200");
+      const result = await validator.validateRequest(req, "GET");
+
+      expect(result.success).toBe(false);
+      expect(result.errors).toBeDefined();
+      expect(result.errors!.length).toBeGreaterThan(0);
+      expect(result.errors![0].type).toBe("query");
+    });
+
+    test("should validate POST request with valid body", async () => {
+      const req = new Request("http://localhost/api/users", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          email: "test@example.com",
+          name: "Test User",
+        }),
+      });
+      const result = await validator.validateRequest(req, "POST");
+
+      expect(result.success).toBe(true);
+    });
+
+    test("should fail POST request with invalid body", async () => {
+      const req = new Request("http://localhost/api/users", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          email: "invalid-email",
+          name: "A", // Too short (min 2)
+        }),
+      });
+      const result = await validator.validateRequest(req, "POST");
+
+      expect(result.success).toBe(false);
+      expect(result.errors).toBeDefined();
+      expect(result.errors![0].type).toBe("body");
+    });
+
+    test("should fail POST request with missing required fields", async () => {
+      const req = new Request("http://localhost/api/users", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          email: "test@example.com",
+          // name is missing
+        }),
+      });
+      const result = await validator.validateRequest(req, "POST");
+
+      expect(result.success).toBe(false);
+      expect(result.errors).toBeDefined();
+    });
+
+    test("should pass through undefined methods", async () => {
+      const req = new Request("http://localhost/api/users", {
+        method: "DELETE",
+      });
+      const result = await validator.validateRequest(req, "DELETE");
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("validateResponse", () => {
+    test("should validate 200 response with valid data", () => {
+      const responseBody = {
+        data: [
+          {
+            id: "550e8400-e29b-41d4-a716-446655440000",
+            email: "test@example.com",
+            name: "Test User",
+            createdAt: "2024-01-15T10:30:00Z",
+          },
+        ],
+      };
+      const result = validator.validateResponse(responseBody, 200);
+
+      expect(result.success).toBe(true);
+    });
+
+    test("should validate 201 response with valid user", () => {
+      const responseBody = {
+        data: {
+          id: "550e8400-e29b-41d4-a716-446655440000",
+          email: "test@example.com",
+          name: "Test User",
+          createdAt: "2024-01-15T10:30:00Z",
+        },
+      };
+      const result = validator.validateResponse(responseBody, 201);
+
+      expect(result.success).toBe(true);
+    });
+
+    test("should fail 200 response with invalid data", () => {
+      const responseBody = {
+        data: [
+          {
+            id: "not-a-uuid",
+            email: "invalid",
+            name: "T",
+            createdAt: "not-a-date",
+          },
+        ],
+      };
+      const result = validator.validateResponse(responseBody, 200);
+
+      expect(result.success).toBe(false);
+      expect(result.errors).toBeDefined();
+      expect(result.errors![0].type).toBe("response");
+    });
+
+    test("should pass through undefined status codes", () => {
+      const responseBody = { anything: "works" };
+      const result = validator.validateResponse(responseBody, 500);
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("helper methods", () => {
+    test("getMethods should return defined methods", () => {
+      const methods = validator.getMethods();
+      expect(methods).toContain("GET");
+      expect(methods).toContain("POST");
+      expect(methods).not.toContain("DELETE");
+    });
+
+    test("getStatusCodes should return defined status codes", () => {
+      const codes = validator.getStatusCodes();
+      expect(codes).toContain(200);
+      expect(codes).toContain(201);
+      expect(codes).toContain(400);
+      expect(codes).not.toContain(500);
+    });
+
+    test("hasMethodSchema should check method existence", () => {
+      expect(validator.hasMethodSchema("GET")).toBe(true);
+      expect(validator.hasMethodSchema("POST")).toBe(true);
+      expect(validator.hasMethodSchema("DELETE")).toBe(false);
+    });
+
+    test("hasResponseSchema should check status code existence", () => {
+      expect(validator.hasResponseSchema(200)).toBe(true);
+      expect(validator.hasResponseSchema(400)).toBe(true);
+      expect(validator.hasResponseSchema(500)).toBe(false);
+    });
+  });
+});
+
+describe("formatValidationErrors", () => {
+  test("should format validation errors for HTTP response", () => {
+    const errors = [
+      {
+        type: "query" as const,
+        issues: [
+          { path: ["page"], message: "Number must be greater than 0", code: "too_small" },
+        ],
+      },
+      {
+        type: "body" as const,
+        issues: [
+          { path: ["email"], message: "Invalid email", code: "invalid_string" },
+          { path: ["name"], message: "String must contain at least 2 character(s)", code: "too_small" },
+        ],
+      },
+    ];
+
+    const formatted = formatValidationErrors(errors);
+
+    expect(formatted.error).toBe("Validation Error");
+    expect(formatted.details).toHaveLength(2);
+    expect(formatted.details[0].type).toBe("query");
+    expect(formatted.details[0].issues[0].path).toBe("page");
+    expect(formatted.details[1].type).toBe("body");
+    expect(formatted.details[1].issues).toHaveLength(2);
+  });
+
+  test("should handle root path errors", () => {
+    const errors = [
+      {
+        type: "body" as const,
+        issues: [{ path: [], message: "Invalid JSON", code: "invalid_type" }],
+      },
+    ];
+
+    const formatted = formatValidationErrors(errors);
+    expect(formatted.details[0].issues[0].path).toBe("(root)");
+  });
+});
+
+describe("Path Parameters Validation", () => {
+  const contractWithParams: ContractSchema = {
+    request: {
+      GET: {
+        params: z.object({
+          id: z.string().uuid(),
+        }),
+      },
+      PUT: {
+        params: z.object({
+          id: z.string().uuid(),
+        }),
+        body: CreateUserInput,
+      },
+    },
+    response: {
+      200: z.object({ data: UserSchema }),
+    },
+  };
+
+  const validator = new ContractValidator(contractWithParams);
+
+  test("should validate path parameters", async () => {
+    const req = new Request("http://localhost/api/users/550e8400-e29b-41d4-a716-446655440000");
+    const result = await validator.validateRequest(req, "GET", {
+      id: "550e8400-e29b-41d4-a716-446655440000",
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test("should fail invalid path parameters", async () => {
+    const req = new Request("http://localhost/api/users/not-a-uuid");
+    const result = await validator.validateRequest(req, "GET", {
+      id: "not-a-uuid",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.errors![0].type).toBe("params");
+  });
+
+  test("should validate both params and body", async () => {
+    const req = new Request("http://localhost/api/users/550e8400-e29b-41d4-a716-446655440000", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: "updated@example.com",
+        name: "Updated User",
+      }),
+    });
+    const result = await validator.validateRequest(req, "PUT", {
+      id: "550e8400-e29b-41d4-a716-446655440000",
+    });
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("Headers Validation", () => {
+  const contractWithHeaders: ContractSchema = {
+    request: {
+      GET: {
+        headers: z.object({
+          authorization: z.string().startsWith("Bearer "),
+          "x-api-key": z.string().min(32),
+        }),
+      },
+    },
+    response: {},
+  };
+
+  const validator = new ContractValidator(contractWithHeaders);
+
+  test("should validate headers", async () => {
+    const req = new Request("http://localhost/api/protected", {
+      headers: {
+        Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
+        "X-API-Key": "12345678901234567890123456789012",
+      },
+    });
+    const result = await validator.validateRequest(req, "GET");
+
+    expect(result.success).toBe(true);
+  });
+
+  test("should fail invalid headers", async () => {
+    const req = new Request("http://localhost/api/protected", {
+      headers: {
+        Authorization: "Invalid token",
+        "X-API-Key": "short",
+      },
+    });
+    const result = await validator.validateRequest(req, "GET");
+
+    expect(result.success).toBe(false);
+    expect(result.errors![0].type).toBe("headers");
+  });
+});