bluera-knowledge 0.9.21

package/tests/fixtures/README.md

@@ -0,0 +1,114 @@
+# Test Fixtures
+
+This directory contains pre-downloaded fixtures used for integration testing of the bluera-knowledge CLI. Using static fixtures ensures consistent, reproducible tests that work offline.
+
+## Directory Structure
+
+```
+fixtures/
+├── README.md                 # This file
+├── github-readmes/           # README files from popular repositories
+├── code-snippets/            # Realistic code samples
+│   ├── auth/                 # Authentication patterns
+│   ├── api/                  # API patterns
+│   └── database/             # Database patterns
+└── documentation/            # Technical documentation samples
+```
+
+## Fixture Sources
+
+### GitHub READMEs
+
+| File | Source | Description |
+|------|--------|-------------|
+| typescript.md | microsoft/TypeScript | TypeScript compiler README |
+| react.md | facebook/react | React library README |
+| express.md | expressjs/express | Express.js framework README |
+| nextjs.md | vercel/next.js | Next.js framework README |
+| vite.md | vitejs/vite | Vite build tool README |
+
+**Original URLs:**
+- https://raw.githubusercontent.com/microsoft/TypeScript/main/README.md
+- https://raw.githubusercontent.com/facebook/react/main/README.md
+- https://raw.githubusercontent.com/expressjs/express/master/Readme.md
+- https://raw.githubusercontent.com/vercel/next.js/canary/readme.md
+- https://raw.githubusercontent.com/vitejs/vite/main/README.md
+
+### Code Snippets
+
+| File | Pattern | Description |
+|------|---------|-------------|
+| auth/jwt-auth.ts | JWT Authentication | Token generation, verification, middleware |
+| auth/oauth-flow.ts | OAuth 2.0 | PKCE, state management, token exchange |
+| api/error-handling.ts | Error Handling | Custom errors, middleware, formatting |
+| api/rest-controller.ts | REST Controller | CRUD operations, validation, pagination |
+| database/repository-pattern.ts | Repository Pattern | Data access abstraction, Unit of Work |
+
+### Documentation
+
+| File | Type | Description |
+|------|------|-------------|
+| architecture.md | Architecture | System design, components, data flow |
+| api-reference.md | API Reference | Endpoints, authentication, error codes |
+| deployment-guide.md | Operations | Deployment, Docker, Kubernetes, monitoring |
+
+## Usage in Tests
+
+```typescript
+import { loadFixture, loadAllFixtures } from '../helpers/fixture-loader';
+
+// Load a single fixture
+const readme = await loadFixture('github-readmes/typescript.md');
+
+// Load all fixtures from a directory
+const codeSnippets = await loadAllFixtures('code-snippets');
+
+// Load fixtures by pattern
+const authFiles = await loadFixturesByPattern('code-snippets/auth/*.ts');
+```
+
+## Refreshing Fixtures
+
+To update fixtures with the latest versions from their sources:
+
+```bash
+# Fetch latest README files
+curl -o tests/fixtures/github-readmes/typescript.md \
+  https://raw.githubusercontent.com/microsoft/TypeScript/main/README.md
+
+curl -o tests/fixtures/github-readmes/react.md \
+  https://raw.githubusercontent.com/facebook/react/main/README.md
+
+# ... etc
+```
+
+**Note:** After refreshing, verify tests still pass as content changes may affect expected search results.
+
+## Test Scenarios
+
+These fixtures enable the following test scenarios:
+
+### E2E Workflow Tests
+- Index README fixtures and search for framework features
+- Index code snippets and find authentication patterns
+- Multi-store search across different content types
+
+### Search Quality Tests
+- Semantic search: "user authentication" finds auth code
+- Mode comparison: vector vs FTS vs hybrid results
+- Relevance scoring: exact matches rank higher
+- Threshold filtering: configurable similarity cutoffs
+
+### Stress Tests
+- Index all fixtures plus generated files (150+)
+- Performance benchmarks for large datasets
+- Concurrent search operations
+
+## Adding New Fixtures
+
+When adding new fixtures:
+
+1. Place files in the appropriate subdirectory
+2. Update this README with source information
+3. Ensure content is representative for search testing
+4. Include diverse vocabulary for semantic search validation

package/tests/fixtures/code-snippets/api/error-handling.ts

@@ -0,0 +1,267 @@
+/**
+ * API Error Handling Module
+ *
+ * Centralized error handling for REST APIs with custom error classes,
+ * middleware, and consistent error response formatting.
+ */
+
+import type { Request, Response, NextFunction, ErrorRequestHandler } from 'express';
+
+/**
+ * Base API Error class
+ * All custom errors should extend this class
+ */
+export class ApiError extends Error {
+  public readonly statusCode: number;
+  public readonly code: string;
+  public readonly isOperational: boolean;
+  public readonly timestamp: Date;
+
+  constructor(
+    statusCode: number,
+    message: string,
+    code?: string,
+    isOperational = true
+  ) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code || 'API_ERROR';
+    this.isOperational = isOperational;
+    this.timestamp = new Date();
+
+    // Maintains proper stack trace for where error was thrown
+    Error.captureStackTrace(this, this.constructor);
+
+    // Set the prototype explicitly for proper instanceof checks
+    Object.setPrototypeOf(this, ApiError.prototype);
+  }
+}
+
+/**
+ * 400 Bad Request - Invalid client request
+ */
+export class BadRequestError extends ApiError {
+  public readonly fields?: Record<string, string>;
+
+  constructor(message: string, fields?: Record<string, string>) {
+    super(400, message, 'BAD_REQUEST');
+    this.fields = fields;
+    Object.setPrototypeOf(this, BadRequestError.prototype);
+  }
+}
+
+/**
+ * 401 Unauthorized - Authentication required
+ */
+export class UnauthorizedError extends ApiError {
+  constructor(message = 'Authentication required') {
+    super(401, message, 'UNAUTHORIZED');
+    Object.setPrototypeOf(this, UnauthorizedError.prototype);
+  }
+}
+
+/**
+ * 403 Forbidden - Insufficient permissions
+ */
+export class ForbiddenError extends ApiError {
+  constructor(message = 'Access denied') {
+    super(403, message, 'FORBIDDEN');
+    Object.setPrototypeOf(this, ForbiddenError.prototype);
+  }
+}
+
+/**
+ * 404 Not Found - Resource does not exist
+ */
+export class NotFoundError extends ApiError {
+  public readonly resource: string;
+
+  constructor(resource: string, id?: string) {
+    const message = id
+      ? `${resource} with ID '${id}' not found`
+      : `${resource} not found`;
+    super(404, message, 'NOT_FOUND');
+    this.resource = resource;
+    Object.setPrototypeOf(this, NotFoundError.prototype);
+  }
+}
+
+/**
+ * 409 Conflict - Resource conflict
+ */
+export class ConflictError extends ApiError {
+  constructor(message: string) {
+    super(409, message, 'CONFLICT');
+    Object.setPrototypeOf(this, ConflictError.prototype);
+  }
+}
+
+/**
+ * 422 Unprocessable Entity - Validation error
+ */
+export class ValidationError extends ApiError {
+  public readonly errors: Array<{
+    field: string;
+    message: string;
+    value?: unknown;
+  }>;
+
+  constructor(
+    errors: Array<{ field: string; message: string; value?: unknown }>
+  ) {
+    super(422, 'Validation failed', 'VALIDATION_ERROR');
+    this.errors = errors;
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}
+
+/**
+ * 429 Too Many Requests - Rate limit exceeded
+ */
+export class RateLimitError extends ApiError {
+  public readonly retryAfter: number;
+
+  constructor(retryAfter: number) {
+    super(429, 'Rate limit exceeded', 'RATE_LIMIT_EXCEEDED');
+    this.retryAfter = retryAfter;
+    Object.setPrototypeOf(this, RateLimitError.prototype);
+  }
+}
+
+/**
+ * 500 Internal Server Error
+ */
+export class InternalError extends ApiError {
+  constructor(message = 'Internal server error') {
+    super(500, message, 'INTERNAL_ERROR', false);
+    Object.setPrototypeOf(this, InternalError.prototype);
+  }
+}
+
+/**
+ * 503 Service Unavailable
+ */
+export class ServiceUnavailableError extends ApiError {
+  constructor(message = 'Service temporarily unavailable') {
+    super(503, message, 'SERVICE_UNAVAILABLE');
+    Object.setPrototypeOf(this, ServiceUnavailableError.prototype);
+  }
+}
+
+/**
+ * Standard error response format
+ */
+export interface ErrorResponse {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    statusCode: number;
+    timestamp: string;
+    path?: string;
+    requestId?: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Formats an error into a standard response
+ */
+export function formatErrorResponse(
+  error: ApiError,
+  req?: Request,
+  requestId?: string
+): ErrorResponse {
+  const response: ErrorResponse = {
+    success: false,
+    error: {
+      code: error.code,
+      message: error.message,
+      statusCode: error.statusCode,
+      timestamp: error.timestamp.toISOString(),
+    },
+  };
+
+  if (req) {
+    response.error.path = req.path;
+  }
+
+  if (requestId) {
+    response.error.requestId = requestId;
+  }
+
+  // Add additional details for specific error types
+  if (error instanceof ValidationError) {
+    response.error.details = { validationErrors: error.errors };
+  } else if (error instanceof BadRequestError && error.fields) {
+    response.error.details = { fields: error.fields };
+  } else if (error instanceof RateLimitError) {
+    response.error.details = { retryAfter: error.retryAfter };
+  }
+
+  return response;
+}
+
+/**
+ * Express error handling middleware
+ * Should be registered last in the middleware chain
+ */
+export const errorHandler: ErrorRequestHandler = (
+  err: Error,
+  req: Request,
+  res: Response,
+  _next: NextFunction
+): void => {
+  // Get request ID if available
+  const requestId = req.headers['x-request-id'] as string | undefined;
+
+  // Log the error
+  console.error(`[${requestId || 'no-id'}] Error:`, {
+    name: err.name,
+    message: err.message,
+    stack: err.stack,
+    path: req.path,
+    method: req.method,
+  });
+
+  // Handle known API errors
+  if (err instanceof ApiError) {
+    const response = formatErrorResponse(err, req, requestId);
+
+    // Add Retry-After header for rate limit errors
+    if (err instanceof RateLimitError) {
+      res.setHeader('Retry-After', err.retryAfter);
+    }
+
+    res.status(err.statusCode).json(response);
+    return;
+  }
+
+  // Handle unknown errors
+  const internalError = new InternalError(
+    process.env.NODE_ENV === 'production'
+      ? 'An unexpected error occurred'
+      : err.message
+  );
+
+  const response = formatErrorResponse(internalError, req, requestId);
+  res.status(500).json(response);
+};
+
+/**
+ * Async handler wrapper to catch errors in async route handlers
+ */
+export function asyncHandler(
+  fn: (req: Request, res: Response, next: NextFunction) => Promise<void>
+) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+/**
+ * 404 handler for undefined routes
+ */
+export function notFoundHandler(req: Request, _res: Response, next: NextFunction): void {
+  next(new NotFoundError('Route', req.path));
+}

package/tests/fixtures/code-snippets/api/rest-controller.ts

@@ -0,0 +1,303 @@
+/**
+ * REST API Controller Pattern
+ *
+ * This module demonstrates a clean REST controller implementation
+ * with proper routing, validation, and response formatting.
+ */
+
+import { Router, Request, Response } from 'express';
+import { z } from 'zod';
+import { asyncHandler, NotFoundError, ValidationError, BadRequestError } from './error-handling';
+import { authenticateToken, requireRoles } from '../auth/jwt-auth';
+
+/**
+ * User entity interface
+ */
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  role: 'admin' | 'user' | 'guest';
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Pagination parameters
+ */
+export interface PaginationParams {
+  page: number;
+  limit: number;
+  sortBy: string;
+  sortOrder: 'asc' | 'desc';
+}
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedResponse<T> {
+  success: true;
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+  };
+}
+
+/**
+ * Single item response wrapper
+ */
+export interface SingleResponse<T> {
+  success: true;
+  data: T;
+}
+
+/**
+ * Zod schema for user creation
+ */
+const createUserSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+  role: z.enum(['admin', 'user', 'guest']).default('user'),
+});
+
+/**
+ * Zod schema for user update
+ */
+const updateUserSchema = z.object({
+  email: z.string().email('Invalid email address').optional(),
+  name: z.string().min(2, 'Name must be at least 2 characters').optional(),
+  role: z.enum(['admin', 'user', 'guest']).optional(),
+});
+
+/**
+ * Zod schema for pagination query params
+ */
+const paginationSchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().positive().max(100).default(20),
+  sortBy: z.string().default('createdAt'),
+  sortOrder: z.enum(['asc', 'desc']).default('desc'),
+});
+
+/**
+ * Validates request body against a Zod schema
+ */
+function validateBody<T>(schema: z.ZodSchema<T>, data: unknown): T {
+  const result = schema.safeParse(data);
+
+  if (!result.success) {
+    const errors = result.error.errors.map(err => ({
+      field: err.path.join('.'),
+      message: err.message,
+    }));
+    throw new ValidationError(errors);
+  }
+
+  return result.data;
+}
+
+/**
+ * Mock user database (replace with actual database in production)
+ */
+const users: Map<string, User> = new Map();
+
+/**
+ * User Controller Class
+ * Handles all user-related HTTP endpoints
+ */
+export class UserController {
+  public router: Router;
+
+  constructor() {
+    this.router = Router();
+    this.initializeRoutes();
+  }
+
+  private initializeRoutes(): void {
+    // Public routes
+    this.router.get('/', asyncHandler(this.getUsers.bind(this)));
+    this.router.get('/:id', asyncHandler(this.getUserById.bind(this)));
+
+    // Protected routes
+    this.router.post(
+      '/',
+      authenticateToken,
+      requireRoles('admin'),
+      asyncHandler(this.createUser.bind(this))
+    );
+
+    this.router.put(
+      '/:id',
+      authenticateToken,
+      asyncHandler(this.updateUser.bind(this))
+    );
+
+    this.router.delete(
+      '/:id',
+      authenticateToken,
+      requireRoles('admin'),
+      asyncHandler(this.deleteUser.bind(this))
+    );
+  }
+
+  /**
+   * GET /users
+   * List all users with pagination
+   */
+  private async getUsers(req: Request, res: Response): Promise<void> {
+    const pagination = validateBody(paginationSchema, req.query);
+
+    // Convert map to array and apply pagination
+    const allUsers = Array.from(users.values());
+    const total = allUsers.length;
+
+    // Sort
+    allUsers.sort((a, b) => {
+      const aValue = a[pagination.sortBy as keyof User];
+      const bValue = b[pagination.sortBy as keyof User];
+
+      if (aValue < bValue) return pagination.sortOrder === 'asc' ? -1 : 1;
+      if (aValue > bValue) return pagination.sortOrder === 'asc' ? 1 : -1;
+      return 0;
+    });
+
+    // Paginate
+    const start = (pagination.page - 1) * pagination.limit;
+    const paginatedUsers = allUsers.slice(start, start + pagination.limit);
+
+    const totalPages = Math.ceil(total / pagination.limit);
+
+    const response: PaginatedResponse<User> = {
+      success: true,
+      data: paginatedUsers,
+      pagination: {
+        page: pagination.page,
+        limit: pagination.limit,
+        total,
+        totalPages,
+        hasNext: pagination.page < totalPages,
+        hasPrev: pagination.page > 1,
+      },
+    };
+
+    res.json(response);
+  }
+
+  /**
+   * GET /users/:id
+   * Get a single user by ID
+   */
+  private async getUserById(req: Request, res: Response): Promise<void> {
+    const { id } = req.params;
+    const user = users.get(id);
+
+    if (!user) {
+      throw new NotFoundError('User', id);
+    }
+
+    const response: SingleResponse<User> = {
+      success: true,
+      data: user,
+    };
+
+    res.json(response);
+  }
+
+  /**
+   * POST /users
+   * Create a new user
+   */
+  private async createUser(req: Request, res: Response): Promise<void> {
+    const data = validateBody(createUserSchema, req.body);
+
+    // Check for existing user
+    const existingUser = Array.from(users.values()).find(
+      u => u.email === data.email
+    );
+
+    if (existingUser) {
+      throw new BadRequestError('User with this email already exists', {
+        email: 'Email is already taken',
+      });
+    }
+
+    const now = new Date();
+    const user: User = {
+      id: crypto.randomUUID(),
+      email: data.email,
+      name: data.name,
+      role: data.role,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    users.set(user.id, user);
+
+    const response: SingleResponse<User> = {
+      success: true,
+      data: user,
+    };
+
+    res.status(201).json(response);
+  }
+
+  /**
+   * PUT /users/:id
+   * Update an existing user
+   */
+  private async updateUser(req: Request, res: Response): Promise<void> {
+    const { id } = req.params;
+    const data = validateBody(updateUserSchema, req.body);
+
+    const user = users.get(id);
+
+    if (!user) {
+      throw new NotFoundError('User', id);
+    }
+
+    // Check if user can update this user (admin or self)
+    if (req.user?.userId !== id && !req.user?.roles.includes('admin')) {
+      throw new BadRequestError('Cannot update other users');
+    }
+
+    const updatedUser: User = {
+      ...user,
+      ...data,
+      updatedAt: new Date(),
+    };
+
+    users.set(id, updatedUser);
+
+    const response: SingleResponse<User> = {
+      success: true,
+      data: updatedUser,
+    };
+
+    res.json(response);
+  }
+
+  /**
+   * DELETE /users/:id
+   * Delete a user
+   */
+  private async deleteUser(req: Request, res: Response): Promise<void> {
+    const { id } = req.params;
+
+    if (!users.has(id)) {
+      throw new NotFoundError('User', id);
+    }
+
+    users.delete(id);
+
+    res.status(204).send();
+  }
+}
+
+// Export router instance
+export const userRouter = new UserController().router;