CLAUDE.md - AI Assistant Guide

CLAUDE.md - AI Assistant Guide

This document provides essential context for AI assistants working with the bloqr-backend codebase.

Project Overview

Bloqr Compiler is a Compiler-as-a-Service for adblock filter lists. It transforms, optimizes, and combines filter lists from multiple sources with real-time progress tracking.

• Version: 0.7.12
• Runtime: Deno 2.4+ (primary), Node.js compatible, Cloudflare Workers compatible
• Language: TypeScript (strict mode, 100% type-safe)
• License: MIT
• JSR Package: @bloqr/compiler

Quick Commands

# Development
deno task dev              # Development with watch mode
deno task compile          # Run compiler CLI

# Testing
deno task test             # Run all tests
deno task test:watch       # Tests in watch mode
deno task test:coverage    # Generate coverage reports

# Code Quality
deno task lint             # Lint code
deno task fmt              # Format code
deno task fmt:check        # Check formatting
deno task check            # Type check

# Build & Deploy
deno task build            # Build standalone executable
deno task wrangler:dev     # Run wrangler dev server (port 8787)
deno task wrangler:deploy  # Deploy to Cloudflare Workers

# Benchmarks
deno task bench            # Run performance benchmarks

Project Structure

mindmap
  root((Project structure))
    src["src/"]
      cli["cli/ — CLI implementation (ArgumentParser, ConfigurationLoader)"]
      compiler["compiler/ — Core compilation (FilterCompiler, SourceCompiler)"]
      configuration["configuration/ — Config validation (pure TypeScript, no AJV)"]
      transformations["transformations/ — 11 rule transformations"]
      downloader["downloader/ — Content fetching and preprocessing"]
      platform["platform/ — Platform abstraction (Workers, Deno, Node.js)"]
      storage["storage/ — Caching and health monitoring"]
      filters["filters/ — Rule filtering utilities"]
      utils["utils/ — RuleUtils, Wildcard, TldUtils, etc."]
      types["types/ — TypeScript interfaces (IConfiguration, ISource)"]
      indexTs["index.ts — Library exports"]
      modTs["mod.ts — Deno module exports"]
      cliDeno["cli.deno.ts — Deno CLI entry point"]
    worker["worker/"]
      workerTs["worker.ts — Cloudflare Worker (main API handler)"]
      htmlTs["html.ts — HTML templates"]
    public["public/ — Static web UI assets"]
    examples["examples/ — Example filter list configurations"]
    docs["docs/ — Additional documentation"]

Architecture Patterns

The codebase uses these key patterns:

• Strategy Pattern: Transformations (SyncTransformation, AsyncTransformation)
• Builder Pattern: TransformationPipeline construction
• Factory Pattern: TransformationRegistry
• Composite Pattern: CompositeFetcher for chaining fetchers
• Adapter Pattern: Platform abstraction layer

Two Compiler Classes

1. FilterCompiler (src/compiler/) - File system-based, for Deno/Node.js CLI
2. WorkerCompiler (src/platform/) - Platform-agnostic, for Workers/browsers

Transformation System

11 available transformations applied in order:

1. ConvertToAscii - Non-ASCII to Punycode
2. RemoveComments - Remove ! and # comment lines
3. Compress - Hosts to adblock syntax conversion
4. RemoveModifiers - Strip unsupported modifiers
5. Validate - Remove dangerous/incompatible rules
6. ValidateAllowIp - Like Validate but keeps IPs
7. Deduplicate - Remove duplicate rules
8. InvertAllow - Convert blocks to allow rules
9. RemoveEmptyLines - Remove blank lines
10. TrimLines - Remove leading/trailing whitespace
11. InsertFinalNewLine - Add final newline

All transformations extend SyncTransformation or AsyncTransformation base classes in src/transformations/base/.

Code Conventions

Naming

• Classes: PascalCase (FilterCompiler, RemoveCommentsTransformation)
• Functions/methods: camelCase (executeSync, validate)
• Constants: UPPER_SNAKE_CASE (CACHE_TTL, RATE_LIMIT_MAX_REQUESTS)
• Interfaces: I-prefixed (IConfiguration, ILogger, ISource)
• Enums: PascalCase (TransformationType, SourceType)

File Organization

• Each module in its own directory with index.ts exports
• Tests co-located as *.test.ts next to source files
• No deeply nested directory structures

TypeScript

• Strict mode enabled (all strict options)
• No implicit any
• Explicit return types on public methods
• Use interfaces over type aliases for object shapes

Error Handling

• Custom error types for specific scenarios
• Validation results over exceptions where possible
• Retry logic with exponential backoff for network operations

Testing

Tests use Deno’s native testing framework:

# Run all tests
deno test --allow-read --allow-write --allow-net --allow-env

# Run specific test file
deno test src/utils/RuleUtils.test.ts --allow-read

# Run with coverage
deno task test:coverage

Test file conventions:

• Co-located with source: FileName.ts -> FileName.test.ts
• Use Deno.test() with descriptive names
• Mock external dependencies (network, file system)

Configuration Schema

interface IConfiguration {
    name: string; // Required
    description?: string;
    homepage?: string;
    license?: string;
    version?: string;
    sources: ISource[]; // Required, non-empty
    transformations?: TransformationType[];
    exclusions?: string[]; // Patterns to exclude
    inclusions?: string[]; // Patterns to include
}

interface ISource {
    source: string; // URL or file path
    name?: string;
    type?: 'adblock' | 'hosts';
    transformations?: TransformationType[];
    exclusions?: string[];
    inclusions?: string[];
}

Pattern types: plain string (contains), *.wildcard, /regex/

API Endpoints (Worker)

• POST /compile - JSON compilation API
• POST /compile/stream - Streaming with SSE
• POST /compile/batch - Batch up to 10 lists
• POST /compile/async - Queue-based async compilation
• POST /compile/batch/async - Queue-based batch compilation
• GET /metrics - Performance metrics
• GET / - Interactive web UI

Key Files to Know

File	Purpose
src/compiler/FilterCompiler.ts	Main compilation logic
src/platform/WorkerCompiler.ts	Platform-agnostic compiler
src/transformations/TransformationRegistry.ts	Transformation management
src/configuration/ConfigurationValidator.ts	Config validation
src/downloader/FilterDownloader.ts	Content fetching with retries
src/types/index.ts	Core type definitions
worker/worker.ts	Cloudflare Worker API handler
deno.json	Deno tasks and configuration
wrangler.toml	Cloudflare Workers config

Platform Support

The codebase supports multiple runtimes through the platform abstraction layer:

• Deno (primary) - Full file system access
• Node.js - npm-compatible via package.json
• Cloudflare Workers - No file system, HTTP-only
• Web Workers - Browser background threads

Use FilterCompiler for CLI/server environments, WorkerCompiler for edge/browser.

Dependencies

Minimal external dependencies:

• @luca/cases (JSR) - String case conversion
• @std/* (Deno Standard Library) - Core utilities
• tldts (npm) - TLD/domain parsing
• wrangler (dev) - Cloudflare deployment

Common Tasks

Adding a New Transformation

1. Create src/transformations/MyTransformation.ts
2. Extend SyncTransformation or AsyncTransformation
3. Implement execute(lines: string[]): string[]
4. Register in TransformationRegistry.ts
5. Add to TransformationType enum in src/types/index.ts
6. Write co-located tests

Modifying the API

1. Edit worker/worker.ts
2. Update route handlers
3. Test with deno task wrangler:dev
4. Deploy with deno task wrangler:deploy

Adding CLI Options

1. Add to ParsedArguments interface in src/cli/ArgumentParser.ts
2. Update parseArgs() in src/cli/ArgumentParser.ts (add to boolean, string, or collect arrays)
3. Add to ICliArgs interface in src/cli/CliApp.deno.ts
4. Update parseArgs() in src/cli/CliApp.deno.ts
5. Handle the new flag in buildTransformations(), createConfig(), readConfig(), or run() as appropriate
6. Add the field to CliArgumentsOutput type and CliArgumentsSchema in src/configuration/schemas.ts
7. Update showHelp() in both ArgumentParser.ts and CliApp.deno.ts
8. Update docs/usage/CLI.md

CI/CD Pipeline

GitHub Actions workflow (.github/workflows/ci.yml):

1. Test: Run all tests with coverage
2. Type Check: Full TypeScript validation
3. Security: Trivy vulnerability scanning
4. JSR Publish: Auto-publish on master push
5. Worker Deploy: Deploy to Cloudflare Workers
6. Pages Deploy: Deploy static assets

Environment Variables

See .env.example for available options:

• PORT - Server port (default: 8787)
• DENO_DIR - Deno cache directory
• Cloudflare bindings configured in wrangler.toml

Useful Links

• README.md - Full project documentation
• TESTING.md - Testing guide
• docs/api/README.md - API documentation
• docs/EXTENSIBILITY.md - Custom extensions
• CHANGELOG.md - Version history