bluera-knowledge 0.9.21

package/tests/fixtures/code-snippets/database/repository-pattern.ts

@@ -0,0 +1,272 @@
+/**
+ * Repository Pattern Implementation
+ *
+ * This module implements the Repository pattern for data access abstraction.
+ * It provides a clean interface for CRUD operations independent of the underlying database.
+ */
+
+/**
+ * Base entity interface - all entities must have an ID
+ */
+export interface Entity {
+  id: string;
+}
+
+/**
+ * Query options for find operations
+ */
+export interface QueryOptions<T> {
+  where?: Partial<T>;
+  orderBy?: {
+    field: keyof T;
+    direction: 'asc' | 'desc';
+  };
+  limit?: number;
+  offset?: number;
+  include?: string[];
+}
+
+/**
+ * Result of a paginated query
+ */
+export interface PaginatedResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+
+/**
+ * Generic Repository interface
+ * Defines the contract for all repositories
+ */
+export interface IRepository<T extends Entity> {
+  findById(id: string): Promise<T | null>;
+  findOne(options: QueryOptions<T>): Promise<T | null>;
+  findMany(options?: QueryOptions<T>): Promise<T[]>;
+  findPaginated(page: number, pageSize: number, options?: QueryOptions<T>): Promise<PaginatedResult<T>>;
+  create(data: Omit<T, 'id'>): Promise<T>;
+  update(id: string, data: Partial<T>): Promise<T>;
+  delete(id: string): Promise<void>;
+  count(options?: QueryOptions<T>): Promise<number>;
+  exists(id: string): Promise<boolean>;
+}
+
+/**
+ * Base Repository implementation with common functionality
+ * Extend this class for specific entity repositories
+ */
+export abstract class BaseRepository<T extends Entity> implements IRepository<T> {
+  protected items: Map<string, T> = new Map();
+
+  /**
+   * Generates a unique ID for new entities
+   */
+  protected generateId(): string {
+    return crypto.randomUUID();
+  }
+
+  /**
+   * Applies query filters to an array of items
+   */
+  protected applyFilters(items: T[], options?: QueryOptions<T>): T[] {
+    let result = [...items];
+
+    // Apply where filters
+    if (options?.where) {
+      result = result.filter(item => {
+        return Object.entries(options.where!).every(([key, value]) => {
+          return item[key as keyof T] === value;
+        });
+      });
+    }
+
+    // Apply ordering
+    if (options?.orderBy) {
+      const { field, direction } = options.orderBy;
+      result.sort((a, b) => {
+        const aVal = a[field];
+        const bVal = b[field];
+
+        if (aVal < bVal) return direction === 'asc' ? -1 : 1;
+        if (aVal > bVal) return direction === 'asc' ? 1 : -1;
+        return 0;
+      });
+    }
+
+    // Apply pagination
+    if (options?.offset !== undefined) {
+      result = result.slice(options.offset);
+    }
+    if (options?.limit !== undefined) {
+      result = result.slice(0, options.limit);
+    }
+
+    return result;
+  }
+
+  async findById(id: string): Promise<T | null> {
+    return this.items.get(id) ?? null;
+  }
+
+  async findOne(options: QueryOptions<T>): Promise<T | null> {
+    const results = await this.findMany({ ...options, limit: 1 });
+    return results[0] ?? null;
+  }
+
+  async findMany(options?: QueryOptions<T>): Promise<T[]> {
+    const allItems = Array.from(this.items.values());
+    return this.applyFilters(allItems, options);
+  }
+
+  async findPaginated(
+    page: number,
+    pageSize: number,
+    options?: QueryOptions<T>
+  ): Promise<PaginatedResult<T>> {
+    const allItems = Array.from(this.items.values());
+    const filtered = this.applyFilters(allItems, { ...options, limit: undefined, offset: undefined });
+    const total = filtered.length;
+
+    const offset = (page - 1) * pageSize;
+    const items = filtered.slice(offset, offset + pageSize);
+
+    return {
+      items,
+      total,
+      page,
+      pageSize,
+      totalPages: Math.ceil(total / pageSize),
+    };
+  }
+
+  async create(data: Omit<T, 'id'>): Promise<T> {
+    const id = this.generateId();
+    const item = { ...data, id } as T;
+    this.items.set(id, item);
+    return item;
+  }
+
+  async update(id: string, data: Partial<T>): Promise<T> {
+    const existing = this.items.get(id);
+    if (!existing) {
+      throw new Error(`Entity with id ${id} not found`);
+    }
+
+    const updated = { ...existing, ...data, id } as T;
+    this.items.set(id, updated);
+    return updated;
+  }
+
+  async delete(id: string): Promise<void> {
+    if (!this.items.has(id)) {
+      throw new Error(`Entity with id ${id} not found`);
+    }
+    this.items.delete(id);
+  }
+
+  async count(options?: QueryOptions<T>): Promise<number> {
+    const items = await this.findMany({ ...options, limit: undefined, offset: undefined });
+    return items.length;
+  }
+
+  async exists(id: string): Promise<boolean> {
+    return this.items.has(id);
+  }
+}
+
+/**
+ * User entity for demonstration
+ */
+export interface User extends Entity {
+  email: string;
+  name: string;
+  role: 'admin' | 'user';
+  createdAt: Date;
+}
+
+/**
+ * User Repository with user-specific methods
+ */
+export class UserRepository extends BaseRepository<User> {
+  async findByEmail(email: string): Promise<User | null> {
+    return this.findOne({ where: { email } as Partial<User> });
+  }
+
+  async findAdmins(): Promise<User[]> {
+    return this.findMany({ where: { role: 'admin' } as Partial<User> });
+  }
+
+  async findRecentUsers(limit: number = 10): Promise<User[]> {
+    return this.findMany({
+      orderBy: { field: 'createdAt', direction: 'desc' },
+      limit,
+    });
+  }
+}
+
+/**
+ * Post entity for demonstration
+ */
+export interface Post extends Entity {
+  title: string;
+  content: string;
+  authorId: string;
+  published: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Post Repository with post-specific methods
+ */
+export class PostRepository extends BaseRepository<Post> {
+  async findByAuthor(authorId: string): Promise<Post[]> {
+    return this.findMany({ where: { authorId } as Partial<Post> });
+  }
+
+  async findPublished(): Promise<Post[]> {
+    return this.findMany({
+      where: { published: true } as Partial<Post>,
+      orderBy: { field: 'createdAt', direction: 'desc' },
+    });
+  }
+
+  async publish(id: string): Promise<Post> {
+    return this.update(id, { published: true, updatedAt: new Date() } as Partial<Post>);
+  }
+
+  async unpublish(id: string): Promise<Post> {
+    return this.update(id, { published: false, updatedAt: new Date() } as Partial<Post>);
+  }
+}
+
+/**
+ * Unit of Work pattern for coordinating multiple repositories
+ */
+export class UnitOfWork {
+  public readonly users: UserRepository;
+  public readonly posts: PostRepository;
+
+  constructor() {
+    this.users = new UserRepository();
+    this.posts = new PostRepository();
+  }
+
+  /**
+   * In a real implementation, this would commit a database transaction
+   */
+  async commit(): Promise<void> {
+    // Commit transaction
+    console.log('Transaction committed');
+  }
+
+  /**
+   * In a real implementation, this would rollback a database transaction
+   */
+  async rollback(): Promise<void> {
+    // Rollback transaction
+    console.log('Transaction rolled back');
+  }
+}

package/tests/fixtures/corpus/VERSION.md

@@ -0,0 +1,25 @@
+# Test Corpus Version
+
+## Current Version: 3.0.0
+
+## Contents
+- **oss-repos/vue**: Vue.js core repository (~593 files) - complete source
+- **oss-repos/express**: Express.js repository (~206 files) - complete source
+- **oss-repos/hono**: Hono v4.6.0 (~191 files) - complete source
+- **documentation/**: Express.js and Node.js excerpts
+- **articles/**: Technical articles (React hooks, TypeScript, JWT)
+
+## Last Updated
+2025-12-18
+
+## Change Log
+- v3.0.0: Replaced sample files with full Vue.js and Express.js repositories
+- v2.0.0: Replaced Zod with Vue.js and Express.js for broader framework coverage
+- v1.0.0: Initial corpus with Zod, Hono, docs, and articles
+
+## Maintenance
+When updating corpus:
+1. Update version number above
+2. Update contents list
+3. Run `npm run test:corpus:index` to rebuild index
+4. Run `npm run test:quality -- --update-baseline` to set new baseline

package/tests/fixtures/corpus/articles/jwt-authentication.md

@@ -0,0 +1,97 @@
+# JWT Authentication in Node.js: A Complete Guide
+
+## What is JWT?
+
+JSON Web Tokens (JWT) are an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. JWTs are commonly used for authentication and authorization.
+
+## Structure of a JWT
+
+A JWT consists of three parts separated by dots:
+
+```
+header.payload.signature
+```
+
+- **Header**: Contains the token type and signing algorithm
+- **Payload**: Contains claims (user data)
+- **Signature**: Verifies the token hasn't been tampered with
+
+## Implementing JWT Authentication
+
+### Installation
+
+```bash
+npm install jsonwebtoken bcryptjs
+```
+
+### Creating Tokens
+
+```javascript
+const jwt = require('jsonwebtoken')
+
+function generateAccessToken(user) {
+  return jwt.sign(
+    { userId: user.id, email: user.email },
+    process.env.JWT_SECRET,
+    { expiresIn: '15m' }
+  )
+}
+
+function generateRefreshToken(user) {
+  return jwt.sign(
+    { userId: user.id },
+    process.env.JWT_REFRESH_SECRET,
+    { expiresIn: '7d' }
+  )
+}
+```
+
+### Verifying Tokens
+
+```javascript
+function authenticateToken(req, res, next) {
+  const authHeader = req.headers['authorization']
+  const token = authHeader && authHeader.split(' ')[1]
+
+  if (!token) {
+    return res.status(401).json({ error: 'Access token required' })
+  }
+
+  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
+    if (err) {
+      return res.status(403).json({ error: 'Invalid or expired token' })
+    }
+    req.user = user
+    next()
+  })
+}
+```
+
+### Refresh Token Flow
+
+```javascript
+app.post('/token/refresh', (req, res) => {
+  const { refreshToken } = req.body
+
+  if (!refreshToken) {
+    return res.status(401).json({ error: 'Refresh token required' })
+  }
+
+  jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET, (err, user) => {
+    if (err) {
+      return res.status(403).json({ error: 'Invalid refresh token' })
+    }
+
+    const accessToken = generateAccessToken({ id: user.userId })
+    res.json({ accessToken })
+  })
+})
+```
+
+## Security Best Practices
+
+1. **Use short expiration times** for access tokens (15 minutes)
+2. **Store refresh tokens securely** (httpOnly cookies)
+3. **Implement token revocation** for logout
+4. **Use strong secrets** (at least 256 bits)
+5. **Always use HTTPS** in production

package/tests/fixtures/corpus/articles/react-hooks-patterns.md

@@ -0,0 +1,127 @@
+# React Hooks Patterns and Best Practices
+
+## Custom Hooks
+
+Custom hooks let you extract component logic into reusable functions.
+
+### useLocalStorage
+
+```typescript
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    try {
+      const item = window.localStorage.getItem(key)
+      return item ? JSON.parse(item) : initialValue
+    } catch (error) {
+      return initialValue
+    }
+  })
+
+  const setValue = (value: T | ((val: T) => T)) => {
+    try {
+      const valueToStore = value instanceof Function ? value(storedValue) : value
+      setStoredValue(valueToStore)
+      window.localStorage.setItem(key, JSON.stringify(valueToStore))
+    } catch (error) {
+      console.error(error)
+    }
+  }
+
+  return [storedValue, setValue] as const
+}
+```
+
+### useDebounce
+
+```typescript
+function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value)
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value)
+    }, delay)
+
+    return () => clearTimeout(timer)
+  }, [value, delay])
+
+  return debouncedValue
+}
+
+// Usage
+function SearchComponent() {
+  const [query, setQuery] = useState('')
+  const debouncedQuery = useDebounce(query, 300)
+
+  useEffect(() => {
+    if (debouncedQuery) {
+      searchAPI(debouncedQuery)
+    }
+  }, [debouncedQuery])
+}
+```
+
+### useFetch
+
+```typescript
+interface FetchState<T> {
+  data: T | null
+  loading: boolean
+  error: Error | null
+}
+
+function useFetch<T>(url: string): FetchState<T> {
+  const [state, setState] = useState<FetchState<T>>({
+    data: null,
+    loading: true,
+    error: null,
+  })
+
+  useEffect(() => {
+    const controller = new AbortController()
+
+    async function fetchData() {
+      try {
+        setState(prev => ({ ...prev, loading: true }))
+        const response = await fetch(url, { signal: controller.signal })
+        if (!response.ok) throw new Error(response.statusText)
+        const data = await response.json()
+        setState({ data, loading: false, error: null })
+      } catch (error) {
+        if (error.name !== 'AbortError') {
+          setState({ data: null, loading: false, error })
+        }
+      }
+    }
+
+    fetchData()
+    return () => controller.abort()
+  }, [url])
+
+  return state
+}
+```
+
+## Rules of Hooks
+
+1. **Only call hooks at the top level** - not inside loops, conditions, or nested functions
+2. **Only call hooks from React functions** - components or custom hooks
+3. **Name custom hooks with "use" prefix** - enables linting rules
+
+## Performance Patterns
+
+### useMemo for expensive calculations
+
+```typescript
+const expensiveResult = useMemo(() => {
+  return computeExpensiveValue(a, b)
+}, [a, b])
+```
+
+### useCallback for stable function references
+
+```typescript
+const handleClick = useCallback(() => {
+  doSomething(id)
+}, [id])
+```

package/tests/fixtures/corpus/articles/typescript-generics.md

@@ -0,0 +1,111 @@
+# TypeScript Generics: From Basics to Advanced Patterns
+
+## Why Generics?
+
+Generics allow you to write reusable code that works with multiple types while maintaining type safety.
+
+## Basic Generic Functions
+
+```typescript
+// Without generics - loses type information
+function identity(arg: any): any {
+  return arg
+}
+
+// With generics - preserves type
+function identity<T>(arg: T): T {
+  return arg
+}
+
+const str = identity<string>('hello') // string
+const num = identity(42) // number (inferred)
+```
+
+## Generic Constraints
+
+Constrain generics to types with specific properties:
+
+```typescript
+interface HasLength {
+  length: number
+}
+
+function logLength<T extends HasLength>(arg: T): T {
+  console.log(arg.length)
+  return arg
+}
+
+logLength('hello') // OK
+logLength([1, 2, 3]) // OK
+logLength(123) // Error: number doesn't have length
+```
+
+## Generic Interfaces
+
+```typescript
+interface Repository<T> {
+  find(id: string): Promise<T | null>
+  findAll(): Promise<T[]>
+  create(data: Omit<T, 'id'>): Promise<T>
+  update(id: string, data: Partial<T>): Promise<T>
+  delete(id: string): Promise<void>
+}
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+class UserRepository implements Repository<User> {
+  async find(id: string): Promise<User | null> {
+    // implementation
+  }
+  // ... other methods
+}
+```
+
+## Conditional Types
+
+```typescript
+type IsArray<T> = T extends any[] ? true : false
+
+type A = IsArray<string[]> // true
+type B = IsArray<number>   // false
+
+// Extract element type from array
+type ElementType<T> = T extends (infer E)[] ? E : never
+
+type C = ElementType<string[]> // string
+```
+
+## Mapped Types
+
+```typescript
+type Readonly<T> = {
+  readonly [K in keyof T]: T[K]
+}
+
+type Partial<T> = {
+  [K in keyof T]?: T[K]
+}
+
+type Required<T> = {
+  [K in keyof T]-?: T[K]
+}
+```
+
+## Utility Type Patterns
+
+```typescript
+// Make specific keys optional
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+// Make specific keys required
+type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>
+
+// Deep partial
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K]
+}
+```

package/tests/fixtures/corpus/documentation/express-middleware.md

@@ -0,0 +1,71 @@
+# Express Middleware Guide
+
+## What is Middleware?
+
+Middleware functions are functions that have access to the request object (`req`), the response object (`res`), and the `next` function in the application's request-response cycle.
+
+Middleware functions can:
+- Execute any code
+- Make changes to the request and response objects
+- End the request-response cycle
+- Call the next middleware in the stack
+
+## Application-level Middleware
+
+Bind application-level middleware to an instance of the app object using `app.use()` and `app.METHOD()`.
+
+```javascript
+const express = require('express')
+const app = express()
+
+// Middleware with no mount path - executed for every request
+app.use((req, res, next) => {
+  console.log('Time:', Date.now())
+  next()
+})
+
+// Middleware mounted on /user/:id
+app.use('/user/:id', (req, res, next) => {
+  console.log('Request Type:', req.method)
+  next()
+})
+```
+
+## Error-handling Middleware
+
+Error-handling middleware always takes four arguments:
+
+```javascript
+app.use((err, req, res, next) => {
+  console.error(err.stack)
+  res.status(500).send('Something broke!')
+})
+```
+
+## Built-in Middleware
+
+Express has built-in middleware functions:
+
+- `express.static` - serves static assets
+- `express.json` - parses JSON payloads
+- `express.urlencoded` - parses URL-encoded payloads
+
+```javascript
+app.use(express.json())
+app.use(express.urlencoded({ extended: true }))
+app.use(express.static('public'))
+```
+
+## Third-party Middleware
+
+Common third-party middleware:
+
+```javascript
+const cors = require('cors')
+const helmet = require('helmet')
+const morgan = require('morgan')
+
+app.use(cors())
+app.use(helmet())
+app.use(morgan('dev'))
+```