mdcontext 0.0.1 → 0.2.0

package/src/__tests__/fixtures/semantic-search/multi-word-corpus/configuration-management.md

@@ -0,0 +1,99 @@
+# Configuration Management
+
+## Overview
+
+Configuration management is the practice of handling system configuration in a systematic, versioned, and automated way. It ensures consistency across environments and enables reproducible deployments.
+
+## Core Principles
+
+### Infrastructure as Code
+
+Configuration should be:
+- Version controlled in Git
+- Reviewed through pull requests
+- Tested before deployment
+- Reproducible across environments
+
+### Separation of Concerns
+
+Keep configuration separate from code:
+- Environment-specific values in config files
+- Secrets in secure vaults
+- Feature flags in dedicated systems
+
+## Configuration Sources
+
+### Hierarchy of Configuration
+
+Configuration typically follows precedence:
+1. Command-line arguments (highest)
+2. Environment variables
+3. Configuration files
+4. Default values (lowest)
+
+### Configuration File Formats
+
+Common formats include:
+- **YAML** - Human readable, supports comments
+- **JSON** - Machine readable, widely supported
+- **TOML** - Simple, explicit typing
+- **INI** - Simple key-value pairs
+
+## Implementation
+
+```typescript
+interface ConfigService {
+  get<T>(key: string): T;
+  getOrDefault<T>(key: string, defaultValue: T): T;
+  has(key: string): boolean;
+  reload(): Promise<void>;
+}
+
+class ConfigManager implements ConfigService {
+  private config: Map<string, unknown>;
+
+  constructor(sources: ConfigSource[]) {
+    // Load and merge from all sources
+    // Respect precedence rules
+  }
+
+  get<T>(key: string): T {
+    // Return typed configuration value
+    // Throw if missing
+  }
+}
+```
+
+## Best Practices
+
+1. **Validate early** - Check configuration at startup
+2. **Document everything** - Keep config schema documented
+3. **Use sensible defaults** - Most users shouldn't need to configure
+4. **Support hot reload** - Allow config changes without restart
+5. **Audit changes** - Track who changed what and when
+
+## Common Patterns
+
+### Feature Flags
+
+```typescript
+if (config.get('features.newDashboard')) {
+  renderNewDashboard();
+} else {
+  renderLegacyDashboard();
+}
+```
+
+### Environment-Specific Configuration
+
+```yaml
+# config.production.yaml
+database:
+  host: prod-db.example.com
+  poolSize: 100
+
+# config.development.yaml
+database:
+  host: localhost
+  poolSize: 5
+```

package/src/__tests__/fixtures/semantic-search/multi-word-corpus/distributed-systems.md

@@ -0,0 +1,92 @@
+# Distributed Systems Architecture
+
+## What Are Distributed Systems?
+
+A distributed system is a collection of independent computers that appear to users as a single coherent system. These systems enable scalability, fault tolerance, and geographic distribution.
+
+## Key Challenges
+
+### Network Partitions
+
+Networks can fail, causing:
+- Message loss
+- Message delays
+- Split-brain scenarios
+
+### Consistency vs Availability
+
+The CAP theorem states you can only have two of:
+- **Consistency** - All nodes see same data
+- **Availability** - System responds to requests
+- **Partition tolerance** - System works despite network issues
+
+### Clock Synchronization
+
+Distributed systems struggle with time:
+- Physical clocks drift
+- Network delays vary
+- Ordering events is challenging
+
+## Design Patterns
+
+### Service Discovery
+
+Services need to find each other:
+- DNS-based discovery
+- Service registries (Consul, etcd)
+- Load balancer integration
+
+### Circuit Breakers
+
+Prevent cascade failures:
+
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private state: 'closed' | 'open' | 'half-open' = 'closed';
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      throw new CircuitOpenError();
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+}
+```
+
+### Event Sourcing
+
+Store state as sequence of events:
+- Complete audit trail
+- Temporal queries
+- Easy replay and debugging
+
+## Communication Patterns
+
+### Synchronous (Request-Response)
+
+- REST APIs
+- gRPC
+- Direct service calls
+
+### Asynchronous (Message-Based)
+
+- Message queues
+- Event streams
+- Pub/sub systems
+
+## Best Practices
+
+1. **Design for failure** - Assume components will fail
+2. **Embrace eventual consistency** - Not everything needs strong consistency
+3. **Use idempotent operations** - Safe to retry
+4. **Monitor everything** - Observability is critical
+5. **Test failure modes** - Chaos engineering validates resilience

package/src/__tests__/fixtures/semantic-search/multi-word-corpus/error-handling.md

@@ -0,0 +1,78 @@
+# Error Handling Patterns
+
+## Introduction to Error Handling
+
+Error handling is the process of responding to and recovering from error conditions in software. Good error handling improves reliability and user experience.
+
+## Error Types
+
+### Operational Errors
+
+Errors that can occur during normal operation:
+- Network timeouts
+- File not found
+- Invalid user input
+- Database connection failures
+
+### Programming Errors
+
+Bugs in the code:
+- Null pointer exceptions
+- Type errors
+- Logic errors
+- Array bounds violations
+
+## Handling Strategies
+
+### Try-Catch Blocks
+
+```typescript
+try {
+  await riskyOperation();
+} catch (error) {
+  if (error instanceof NetworkError) {
+    // Retry logic
+  } else if (error instanceof ValidationError) {
+    // Return user-friendly message
+  } else {
+    // Log and re-throw unknown errors
+    throw error;
+  }
+}
+```
+
+### Result Types
+
+Instead of throwing, return success/failure:
+
+```typescript
+type Result<T, E> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parseConfig(path: string): Result<Config, ConfigError> {
+  // Return structured result instead of throwing
+}
+```
+
+### Error Boundaries
+
+In UI applications, error boundaries prevent entire app crashes:
+- Catch errors in component trees
+- Display fallback UI
+- Log errors for debugging
+
+## Best Practices
+
+1. **Be specific** - Catch specific error types, not generic Exception
+2. **Fail fast** - Detect errors early before causing more damage
+3. **Provide context** - Error messages should explain what and why
+4. **Log appropriately** - Stack traces for debugging, summaries for users
+5. **Clean up resources** - Use finally blocks or try-with-resources
+
+## Error Handling Anti-Patterns
+
+- Swallowing errors silently
+- Catching too broadly
+- Exposing internal details to users
+- Not cleaning up on errors

package/src/__tests__/fixtures/semantic-search/multi-word-corpus/failure-automation.md

@@ -0,0 +1,55 @@
+# Failure Automation
+
+## Overview
+
+Failure automation is the practice of automatically detecting, reporting, and responding to system failures without human intervention. This approach is essential for maintaining high availability in modern distributed systems.
+
+## Core Concepts
+
+### Automated Failure Detection
+
+Systems use health checks, heartbeats, and monitoring to detect when components fail. Failure detection must be fast and accurate to minimize downtime.
+
+### Automatic Recovery
+
+Once a failure is detected, automation can:
+- Restart failed services
+- Failover to backup systems
+- Scale up healthy instances
+- Alert operations teams
+
+### Failure Isolation
+
+Automated systems can isolate failures to prevent cascading effects. Circuit breakers and bulkheads are common patterns for failure isolation.
+
+## Best Practices
+
+1. **Test failure scenarios regularly** - Chaos engineering validates that automation works
+2. **Set appropriate timeouts** - Balance between fast detection and false positives
+3. **Log everything** - Automated responses need audit trails
+4. **Graceful degradation** - Systems should partially function during failures
+
+## Implementation Example
+
+```typescript
+class FailureAutomation {
+  detectFailure(component: string): boolean {
+    // Check health endpoint
+    // Monitor error rates
+    // Analyze latency patterns
+  }
+
+  respondToFailure(component: string): void {
+    // Trigger automatic recovery
+    // Send alerts
+    // Update status page
+  }
+}
+```
+
+## Related Topics
+
+- Error handling and recovery
+- Distributed systems resilience
+- Site reliability engineering
+- Chaos engineering practices

package/src/__tests__/fixtures/semantic-search/multi-word-corpus/job-context.md

@@ -0,0 +1,69 @@
+# Job Context
+
+## What is Job Context?
+
+Job context refers to the environment, state, and metadata associated with a running job or task. Understanding job context is crucial for debugging, monitoring, and managing batch processing systems.
+
+## Components of Job Context
+
+### Runtime Environment
+
+The job context includes:
+- Working directory and file paths
+- Environment variables
+- Process information (PID, memory, CPU)
+- User and permission context
+
+### Execution Metadata
+
+Each job carries metadata about its execution:
+- Job ID and name
+- Start time and duration
+- Parent job or workflow reference
+- Retry count and history
+
+### State Information
+
+Job context tracks current state:
+- Input parameters received
+- Progress percentage
+- Intermediate results
+- Checkpoints for recovery
+
+## Passing Context Between Jobs
+
+In workflow systems, context flows between jobs:
+
+```typescript
+interface JobContext {
+  jobId: string;
+  workflowId: string;
+  inputs: Record<string, unknown>;
+  outputs: Record<string, unknown>;
+  metadata: {
+    startedAt: Date;
+    parent?: string;
+    retryCount: number;
+  };
+}
+
+function executeJob(context: JobContext): Promise<JobContext> {
+  // Access context for execution
+  // Update outputs and state
+  // Return enriched context
+}
+```
+
+## Best Practices
+
+1. **Keep context immutable** - Create new context objects rather than mutating
+2. **Serialize context carefully** - Ensure all context can be persisted
+3. **Scope context appropriately** - Don't pass more than needed
+4. **Log context changes** - Track how context evolves
+
+## Use Cases
+
+- Debugging failed jobs by examining their context
+- Replaying jobs with captured context
+- Monitoring job progress through context updates
+- Implementing job dependencies based on context

package/src/__tests__/fixtures/semantic-search/multi-word-corpus/process-orchestration.md

@@ -0,0 +1,99 @@
+# Process Orchestration
+
+## Introduction
+
+Process orchestration is the automated coordination of multiple tasks, services, or workflows to achieve a business goal. It differs from choreography where services coordinate themselves.
+
+## Orchestration vs Choreography
+
+### Orchestration (Central Control)
+
+A central orchestrator directs the workflow:
+- Single point of control
+- Easy to understand flow
+- Simpler error handling
+- Can become bottleneck
+
+### Choreography (Distributed)
+
+Services react to events independently:
+- No central point of failure
+- More scalable
+- Harder to track overall flow
+- Complex error handling
+
+## Orchestration Patterns
+
+### Sequential Execution
+
+Tasks run one after another:
+
+```typescript
+async function processOrder(order: Order): Promise<void> {
+  await validateOrder(order);
+  await reserveInventory(order.items);
+  await processPayment(order.payment);
+  await scheduleShipping(order);
+  await notifyCustomer(order);
+}
+```
+
+### Parallel Execution
+
+Independent tasks run concurrently:
+
+```typescript
+async function enrichOrder(order: Order): Promise<EnrichedOrder> {
+  const [customer, inventory, pricing] = await Promise.all([
+    fetchCustomerDetails(order.customerId),
+    checkInventoryLevels(order.items),
+    calculatePricing(order.items),
+  ]);
+
+  return { ...order, customer, inventory, pricing };
+}
+```
+
+### Saga Pattern
+
+Long-running transactions with compensation:
+
+```typescript
+class OrderSaga {
+  async execute(order: Order): Promise<void> {
+    const compensations: (() => Promise<void>)[] = [];
+
+    try {
+      await this.reserveInventory(order);
+      compensations.push(() => this.releaseInventory(order));
+
+      await this.chargePayment(order);
+      compensations.push(() => this.refundPayment(order));
+
+      await this.shipOrder(order);
+    } catch (error) {
+      // Run compensations in reverse
+      for (const compensate of compensations.reverse()) {
+        await compensate();
+      }
+      throw error;
+    }
+  }
+}
+```
+
+## Workflow Engines
+
+Popular orchestration tools:
+- **Temporal** - Durable execution
+- **Apache Airflow** - Data pipelines
+- **Kubernetes Jobs** - Container orchestration
+- **Step Functions** - AWS serverless workflows
+
+## Best Practices
+
+1. **Idempotent operations** - Safe to retry on failure
+2. **Clear compensation logic** - Know how to rollback
+3. **Visibility and monitoring** - Track workflow state
+4. **Timeout handling** - Don't wait forever
+5. **Version workflows carefully** - Running instances need compatibility

package/src/cli/argv-preprocessor.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Unit tests for argv-preprocessor
+ */
+
+import { describe, expect, it } from 'vitest'
+import { preprocessArgvWithValidation } from './argv-preprocessor.js'
+
+describe('preprocessArgvWithValidation', () => {
+  const node = '/usr/bin/node'
+  const script = '/path/to/mdcontext'
+
+  describe('flag reordering', () => {
+    it('reorders flags before positional args', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'search',
+        'query',
+        '--limit',
+        '5',
+        'docs/',
+      ])
+      expect(result.argv).toEqual([
+        node,
+        script,
+        'search',
+        '--limit',
+        '5',
+        'query',
+        'docs/',
+      ])
+      expect(result.error).toBeUndefined()
+    })
+
+    it('handles --flag=value syntax', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'search',
+        'query',
+        '--limit=5',
+        'docs/',
+      ])
+      expect(result.argv).toEqual([
+        node,
+        script,
+        'search',
+        '--limit=5',
+        'query',
+        'docs/',
+      ])
+      expect(result.error).toBeUndefined()
+    })
+
+    it('handles boolean flags', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        'file.md',
+        '--brief',
+      ])
+      expect(result.argv).toEqual([
+        node,
+        script,
+        'context',
+        '--brief',
+        'file.md',
+      ])
+      expect(result.error).toBeUndefined()
+    })
+
+    it('passes through --help flag', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        '--help',
+      ])
+      expect(result.argv).toEqual([node, script, 'context', '--help'])
+      expect(result.error).toBeUndefined()
+    })
+  })
+
+  describe('unknown flag detection', () => {
+    it('returns error for unknown flag', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        '-z',
+        'file.md',
+      ])
+      expect(result.error).toContain("Unknown option '-z'")
+      expect(result.error).toContain("'context'")
+    })
+
+    it('returns error for unknown long flag', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'search',
+        '--invalid',
+        'query',
+      ])
+      expect(result.error).toContain("Unknown option '--invalid'")
+    })
+
+    it('returns error for unknown flag with value', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        '--foo=bar',
+        'file.md',
+      ])
+      expect(result.error).toContain("Unknown option '--foo'")
+    })
+  })
+
+  describe('typo suggestions', () => {
+    it('suggests --json for --jsno', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        '--jsno',
+        'file.md',
+      ])
+      expect(result.error).toContain("Did you mean '--json'")
+    })
+
+    it('suggests --limit for --limt', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'search',
+        '--limt',
+        '5',
+        'query',
+      ])
+      expect(result.error).toContain("Did you mean '--limit'")
+    })
+
+    it('suggests --tokens for --toekns', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        '--toekns',
+        '100',
+        'file.md',
+      ])
+      expect(result.error).toContain("Did you mean '--tokens'")
+    })
+  })
+
+  describe('edge cases', () => {
+    it('passes through empty args', () => {
+      const result = preprocessArgvWithValidation([node, script])
+      expect(result.argv).toEqual([node, script])
+      expect(result.error).toBeUndefined()
+    })
+
+    it('passes through unknown subcommand', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'unknown',
+        '--flag',
+      ])
+      // Unknown subcommand should pass through (no schema)
+      expect(result.argv).toEqual([node, script, 'unknown', '--flag'])
+      expect(result.error).toBeUndefined()
+    })
+
+    it('handles -- end of flags marker', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        '--',
+        '--not-a-flag',
+        'file.md',
+      ])
+      // After --, everything is positional
+      expect(result.argv).toEqual([
+        node,
+        script,
+        'context',
+        '--not-a-flag',
+        'file.md',
+      ])
+      expect(result.error).toBeUndefined()
+    })
+
+    it('validates alias flags', () => {
+      const result = preprocessArgvWithValidation([
+        node,
+        script,
+        'context',
+        '-t',
+        '100',
+        'file.md',
+      ])
+      expect(result.error).toBeUndefined()
+      expect(result.argv).toContain('-t')
+    })
+  })
+})