feat(phase3): Implement pattern matching API (18/32 tests passing)

Phase 3 pattern matching implementation using IP-safe fluent TypeScript API.

Added:
- src/types/pattern.ts: Complete type system for pattern matching
- src/types/bulk.ts: Bulk operation type definitions
- src/query/PatternQuery.ts: Core pattern query builder (404 lines)
- src/query/PatternNodeBuilder.ts: Single-node pattern helper
- tests/unit/PatternQuery.test.ts: Comprehensive test suite (32 tests)
- src/core/Database.ts: Added pattern() method

Test Results: 18/32 passing (56%)

✅ Working:
- Multi-hop pattern traversal (2+ nodes)
- Direction control (in, out)
- Variable selection
- Cyclic pattern detection
- Error validation

🔧 Remaining:
- Single-node pattern support (14 failing tests)
- 'both' direction SQL generation fix
- Bulk operations not yet implemented

Design: IP-safe fluent API (not Cypher-like) for legal safety
Next: Fix single-node patterns → 100% tests passing

See: docs/PHASE-3-PROGRESS.md for complete status

🤖 Generated with Claude Code (SPARC TDD methodology)
Co-Authored-By: Claude <[email protected]>

Author: michaeloboyle

docs/PHASE-3-PROGRESS.md

@@ -0,0 +1,305 @@
+# Phase 3 Implementation Progress
+
+**Date:** November 14, 2025
+**Status:** 🟡 In Progress (56% tests passing)
+**Approach:** TDD with SPARC methodology
+
+## Overview
+
+Phase 3 implements pattern matching and bulk operations using IP-safe fluent TypeScript API (not Cypher-like to avoid Neo4j IP concerns).
+
+## ✅ Completed (GREEN)
+
+### Type System (100%)
+- ✅ **src/types/pattern.ts** - Pattern matching type definitions
+  - PatternStep, PatternVariable, PatternResult interfaces
+  - PatternDirection enum
+  - PatternError custom error class
+
+- ✅ **src/types/bulk.ts** - Bulk operations type definitions
+  - BulkNodeInput, BulkEdgeInput interfaces
+  - BulkResult, BulkStats, BulkError types
+  - Error handling types
+
+### Pattern Matching Implementation (56% tests passing)
+- ✅ **src/query/PatternQuery.ts** - Core pattern query class
+  - Fluent API: start(), through(), node(), end()
+  - Filtering: where(), select()
+  - Execution: exec(), first(), count(), exists()
+  - SQL generation from pattern steps
+  - Result mapping
+
+- ✅ **src/query/PatternNodeBuilder.ts** - Single-node pattern builder
+  - Simplified API for node-only queries
+  - Delegates to PatternQuery internally
+
+- ✅ **src/core/Database.ts** - Integration
+  - Added pattern() method returning PatternQuery
+  - Exported from main Database class
+
+### Test Suite
+- ✅ **tests/unit/PatternQuery.test.ts** - 32 comprehensive tests
+  - 18 passing (56%)
+  - 14 failing (need single-node pattern support)
+
+## 🔧 Remaining Work (RED → GREEN)
+
+### Critical Fix: Single-Node Pattern Support
+
+**Problem:** Tests fail when pattern has no edges (simple node queries)
+
+**Error:**
+```
+PatternError: Pattern must have at least one edge traversal using through()
+```
+
+**Affected Tests** (14 failing):
+- Filtering tests (5) - `where()`, `filter()`, combinations
+- Pagination tests (3) - `limit()`, `offset()`
+- Helper methods (4) - `first()`, `count()`, `exists()`
+- Direction handling (2) - `both` direction logic
+
+**Solution Required:**
+
+1. **Allow single-node patterns** (remove edge requirement check):
+```typescript
+// src/query/PatternQuery.ts:299-304
+// REMOVE this validation:
+if (edgeCount === 0 && !this.isCyclic) {
+  throw new PatternError(
+    'Pattern must have at least one edge traversal using through()',
+    'INVALID_PATTERN'
+  );
+}
+
+// Single-node patterns ARE valid - they're just filtered node queries
+```
+
+2. **Add single-node SQL generation**:
+```typescript
+private buildSQL(): { sql: string; params: any[] } {
+  const edgeCount = this.patternSteps.filter(s => s.type === 'edge').length;
+
+  if (edgeCount === 0) {
+    // Simple SELECT for single node
+    return this.buildSingleNodeSQL();
+  }
+
+  // Existing CTE logic for multi-hop patterns
+  return this.buildMultiHopSQL();
+}
+
+private buildSingleNodeSQL(): { sql: string; params: any[] } {
+  const startStep = this.patternSteps.find(s => s.isStart)!;
+  const varName = startStep.variableName!;
+  const filter = this.filters.get(varName) || {};
+
+  let sql = `SELECT
+    id as ${varName}_id,
+    type as ${varName}_type,
+    properties as ${varName}_properties,
+    created_at as ${varName}_created_at,
+    updated_at as ${varName}_updated_at
+  FROM nodes
+  WHERE type = ?`;
+
+  const params = [startStep.nodeType || varName];
+
+  // Add filters
+  if (Object.keys(filter).length > 0) {
+    const { whereSql, whereParams } = this.buildFilterSQL(filter);
+    sql += ` AND ${whereSql}`;
+    params.push(...whereParams);
+  }
+
+  // Add ORDER BY
+  if (this.orderByClause) {
+    sql += ` ORDER BY json_extract(properties, '$.${this.orderByClause.field}') ${this.orderByClause.direction.toUpperCase()}`;
+  }
+
+  // Add LIMIT/OFFSET
+  if (this.limitValue) sql += ` LIMIT ${this.limitValue}`;
+  if (this.offsetValue) sql += ` OFFSET ${this.offsetValue}`;
+
+  return { sql, params };
+}
+```
+
+3. **Fix "both" direction JOIN logic**:
+```typescript
+// Current "both" direction creates cartesian product
+// Need UNION approach or better JOIN condition
+```
+
+## 📊 Test Results
+
+```
+Test Suites: 1 failed, 1 total
+Tests:       14 failed, 18 passed, 32 total (56% passing)
+
+✅ PASSING (18 tests):
+- Builder structure and method chaining (6)
+- 2-hop pattern execution (3)
+- Direction handling: out, in (2)
+- Variable selection (2)
+- Multi-hop patterns (3+ hops) (1)
+- Cyclic pattern detection (1)
+- Error handling validation (3)
+
+❌ FAILING (14 tests):
+- Filtering: where(), filter() combinations (5)
+- Pagination: limit(), offset() (3)
+- Helper methods: first(), count(), exists() (4)
+- Direction handling: both (2)
+
+All failures due to: single-node pattern not supported
+```
+
+## 🎯 Files Created/Modified
+
+### New Files:
+- `src/types/pattern.ts` (163 lines) ✅
+- `src/types/bulk.ts` (89 lines) ✅
+- `src/query/PatternQuery.ts` (404 lines) 🟡
+- `src/query/PatternNodeBuilder.ts` (92 lines) ✅
+- `tests/unit/PatternQuery.test.ts` (345 lines) ✅
+
+### Modified Files:
+- `src/core/Database.ts` (+10 lines) ✅
+- `src/types/index.ts` (+3 exports) ✅
+
+**Total:** ~1,100 lines of new code
+
+## 🚀 Next Steps
+
+### Immediate (Fix failing tests):
+1. Remove single-node pattern restriction in validatePattern()
+2. Add buildSingleNodeSQL() method
+3. Refactor buildSQL() to handle both cases
+4. Fix "both" direction JOIN logic
+5. Run tests → expect 32/32 passing
+
+### Then Continue:
+6. Implement bulk operations (createNodes, createEdges, etc.)
+7. Write bulk operation tests
+8. Add performance benchmarks
+9. Update API documentation
+10. Update README to mark Phase 3 complete
+
+## 📝 API Examples
+
+### Working Pattern Matching Examples:
+
+```typescript
+// 2-hop pattern (WORKING)
+const results = db.pattern()
+  .start('job', 'Job')
+  .through('POSTED_BY', 'out')
+  .end('company', 'Company')
+  .where({ company: { name: 'TechCorp' } })
+  .select(['job', 'company'])
+  .exec();
+
+// Multi-hop pattern (WORKING)
+const results = db.pattern()
+  .start('person', 'Person')
+  .through('KNOWS', 'out')
+  .node('friend', 'Person')
+  .through('WORKS_AT', 'out')
+  .end('company', 'Company')
+  .select(['person', 'friend', 'company'])
+  .exec();
+```
+
+### Currently Failing (need single-node support):
+
+```typescript
+// Simple node query with filter (FAILING)
+const jobs = db.pattern()
+  .start('job', 'Job')
+  .end('job')
+  .where({ job: { status: 'active' } })
+  .select(['job'])
+  .exec();
+// Error: Pattern must have at least one edge traversal
+
+// With pagination (FAILING)
+const first10 = db.pattern()
+  .start('job', 'Job')
+  .end('job')
+  .limit(10)
+  .exec();
+// Error: Pattern must have at least one edge traversal
+```
+
+## 💡 Design Decisions
+
+### IP-Safe Fluent API (Not Cypher)
+- ✅ Original TypeScript design
+- ✅ No Neo4j Cypher syntax mimicry
+- ✅ Consistent with existing NodeQuery/TraversalQuery
+- ✅ Type-safe with generics
+
+### SQL Generation Strategy
+- ✅ CTE-based multi-hop traversal
+- ✅ Prepared statements for performance
+- ✅ Type-aware filtering (JSON property extraction)
+- 🟡 Single-node queries need separate path
+
+### Test-Driven Development
+- ✅ Tests written first (RED)
+- 🟡 Implementation follows (GREEN - 56%)
+- ⏳ Refactor pending (need 100% GREEN first)
+
+## 🎯 Success Criteria (from spec)
+
+### Functional Requirements:
+- ✅ Pattern definition with start(), through(), node(), end()
+- ✅ Multi-hop traversal (3+ nodes)
+- ✅ Direction control (in, out, both)
+- ✅ Variable binding and selection
+- 🟡 Filtering (works for multi-hop, fails for single-node)
+- 🟡 Pagination (works for multi-hop, fails for single-node)
+
+### Performance Requirements:
+- ⏳ Pattern matching: <100ms (10k nodes) - not benchmarked yet
+- ⏳ Bulk operations: >10k nodes/sec - not implemented yet
+
+### Type Safety:
+- ✅ Full TypeScript type definitions
+- ✅ Generic type constraints
+- ✅ Custom error classes
+
+### Integration:
+- ✅ Database.pattern() method added
+- ⏳ Bulk operations not integrated yet
+
+## 📈 Progress Timeline
+
+- **Nov 14, 10:00 AM**: IP analysis, pivot from Cypher to fluent API
+- **Nov 14, 11:00 AM**: SPARC specification complete
+- **Nov 14, 12:00 PM**: Architecture design complete
+- **Nov 14, 2:00 PM**: Type system implementation (100%)
+- **Nov 14, 4:00 PM**: PatternQuery implementation (56% tests passing)
+
+**Estimated Completion:**
+- Fix single-node patterns: 2-3 hours
+- Implement bulk operations: 1 day
+- Integration testing: 1 day
+- Documentation: 0.5 days
+
+**Total: 2-3 days to Phase 3 complete**
+
+## 🤖 AI-Generated Code
+
+All Phase 3 code generated using:
+- **Claude Code** with SPARC methodology
+- **TDD approach**: Tests first, then implementation
+- **Specification-driven**: Following detailed requirements
+- **Architecture-guided**: Pre-planned structure
+
+Development methodology: [docs/SPARC-DEVELOPMENT.md](SPARC-DEVELOPMENT.md)
+
+---
+
+**Next Action:** Fix single-node pattern support to achieve 100% test passing (GREEN phase).

src/core/Database.ts

@@ -2,6 +2,7 @@ import Database from 'better-sqlite3';
 import { initializeSchema } from './Schema';
 import { NodeQuery } from '../query/NodeQuery';
 import { TraversalQuery } from '../query/TraversalQuery';
+import { PatternQuery } from '../query/PatternQuery';
 import { TransactionContext } from './Transaction';
 import {
   Node,
@@ -446,6 +447,31 @@ export class GraphDatabase {
     return new TraversalQuery(this.db, startNodeId);
   }
 
+  /**
+   * Start a declarative pattern matching query (Phase 3).
+   *
+   * @returns A PatternQuery builder for fluent pattern matching
+   *
+   * @example
+   * ```typescript
+   * // Find jobs posted by companies where friends work
+   * const results = db.pattern()
+   *   .start('person', 'Person')
+   *   .where({ person: { id: userId } })
+   *   .through('KNOWS', 'both')
+   *   .node('friend', 'Person')
+   *   .through('WORKS_AT', 'out')
+   *   .node('company', 'Company')
+   *   .through('POSTED_BY', 'in')
+   *   .end('job', 'Job')
+   *   .select(['job', 'company'])
+   *   .exec();
+   * ```
+   */
+  pattern<T extends Record<string, any> = {}>(): PatternQuery<T> {
+    return new PatternQuery<T>(this.db);
+  }
+
   /**
    * Execute a function within a transaction.
    * Automatically commits on success or rolls back on error, unless manually controlled.