bluera-knowledge 0.13.3 → 0.14.1

package/tests/fixtures/README.md

@@ -1,114 +0,0 @@
-# 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

@@ -1,256 +0,0 @@
-/**
- * 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

@@ -1,297 +0,0 @@
-/**
- * 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;