dzql 0.4.4 → 0.4.6

package/docs/compiler/SESSION_SUMMARY.md

@@ -1,266 +0,0 @@
-# Compiler Development Session Summary
-
-## Latest Session: Coding Standards Compliance (2025-11-16)
-
-This session enforced DZQL coding standards across all generated functions to ensure consistency, security, and proper WebSocket API protection.
-
-### ✅ Coding Standards Fixes
-
-**What Changed**: Fixed the compiler to generate code compliant with DZQL conventions:
-
-1. **Parameter Ordering** - `p_user_id INT` now FIRST in all functions
-   - ✅ `get_*(p_user_id INT, p_id INT, ...)`
-   - ✅ `save_*(p_user_id INT, p_data JSONB)`
-   - ✅ `delete_*(p_user_id INT, p_id INT)`
-   - ✅ `lookup_*(p_user_id INT, p_filter TEXT, ...)`
-   - ✅ `search_*(p_user_id INT, p_filters JSONB, ...)`
-
-2. **Helper Function Prefixes** - Internal functions now use `_` prefix
-   - ✅ `_graph_*_on_create(p_user_id INT, p_record JSONB)`
-   - ✅ `_resolve_notification_paths_*(p_user_id INT, p_record JSONB)`
-   - Prevents direct websocket client access to internal functions
-
-3. **Standard Permission Functions** - All 4 always generated
-   - ✅ `can_view_*`, `can_create_*`, `can_update_*`, `can_delete_*`
-   - Even for public access (returns `true`)
-
-4. **Clean Function Names** - Fixed malformed names with embedded comments
-   - ❌ Before: `can_-- Anyone can create...'update_organisations`
-   - ✅ After: `can_update_organisations`
-
-**Files Modified**:
-- `src/codegen/permission-codegen.js` - Clean operation names, generate all 4 functions
-- `src/codegen/operation-codegen.js` - Fix parameter ordering, update helper calls
-- `src/codegen/notification-codegen.js` - Add underscore prefix, p_user_id first
-- `src/codegen/graph-rules-codegen.js` - Add underscore prefix, p_user_id first
-- `tests/sql-validation.test.js` - Update expectations to match standards
-
-**Documentation Added**:
-- `CODING_STANDARDS.md` - Complete coding standards reference
-- Updated `README.md` with correct function signatures
-- Updated `QUICKSTART.md` with correct examples
-
-**Test Results**: ✅ All 55 tests passing
-
----
-
-## Previous Session: Graph Rules & Advanced Filters
-
-This session continued work on the DZQL Compiler from a previous session where the core compilation infrastructure was built.
-
-## Completed Features
-
-### 1. ✅ Graph Rules Compilation
-
-**What**: Transforms declarative graph rules into executable PostgreSQL functions
-
-**Implementation**:
-- Created `GraphRulesCodegen` class
-- Supports all action types: `create`, `update`, `delete`, `validate`, `execute`
-- Resolves special variables:
-  - `@user_id` → `p_user_id`
-  - `@today` → `CURRENT_DATE`
-  - `@now` → `NOW()`
-  - `@field` → `(p_record->>'field')`
-- Generates trigger-based functions: `graph_{table}_{on_create|on_update|on_delete}`
-- Integrated into SAVE and DELETE operations
-
-**Example Generated Code** (now with correct coding standards):
-```sql
-CREATE OR REPLACE FUNCTION _graph_organisations_on_create(
-  p_user_id INT,
-  p_record JSONB
-) RETURNS VOID AS $$
-BEGIN
-  -- Creator becomes owner
-  INSERT INTO acts_for (user_id, org_id, valid_from)
-  VALUES (p_user_id, (p_record->>'id'), CURRENT_DATE);
-END;
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-```
-
-> Note: Helper functions now use `_` prefix and have `p_user_id` first
-
-**Files Changed**:
-- `src/codegen/graph-rules-codegen.js` (new)
-- `src/compiler.js` (integrated)
-- `src/codegen/operation-codegen.js` (calls graph functions)
-
-### 2. ✅ Advanced SEARCH Filter Operators
-
-**What**: Comprehensive JSONB-based filtering with multiple operators
-
-**Operators Implemented**:
-- **Comparison**: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`
-- **Array Membership**: `in`
-- **Pattern Matching**: `like`, `ilike`
-
-**Features**:
-- Dynamic WHERE clause builder
-- Type-safe value handling
-- SQL injection protection via `format()`
-- Combines with text search and temporal filters
-- Multiple operators per field
-- Multiple fields per query
-
-**Example Usage**:
-```json
-{
-  "age": {"gte": 18, "lte": 65},
-  "status": {"in": ["active", "pending"]},
-  "email": {"ilike": "%@company.com"}
-}
-```
-
-**Generated SQL**:
-```sql
-WHERE TRUE
-  AND age >= '18'
-  AND age <= '65'
-  AND status = ANY(ARRAY['active', 'pending']::TEXT[])
-  AND email ILIKE '%@company.com'
-```
-
-**Files Changed**:
-- `src/codegen/operation-codegen.js` (enhanced SEARCH function)
-- `docs/ADVANCED_FILTERS.md` (comprehensive documentation)
-
-### 3. ✅ Comprehensive Test Suite
-
-**SQL Validation Tests** (42 tests):
-- Function signature validation
-- Permission logic verification
-- CRUD operation structure
-- Graph rules generation
-- Filter operator inclusion
-- SQL syntax validation
-- Metadata verification
-
-**Integration Tests** (prepared):
-- Full workflow testing
-- Real database operations
-- Permission enforcement
-- Advanced filter testing
-- Graph rules execution
-
-**Test Organization**:
-```bash
-bun test                  # Unit + validation (55 tests)
-bun test:integration      # Integration tests (requires PostgreSQL)
-bun test:all             # Everything
-```
-
-**Files Added**:
-- `tests/sql-validation.test.js` (42 tests)
-- `tests/integration.test.skip.js` (prepared for PostgreSQL)
-- `tests/integration-README.md` (setup instructions)
-
-## Test Results
-
-✅ **55 tests passing** (13 compiler + 42 validation)
-- All core compiler functionality verified
-- All generated SQL validated
-- No regressions introduced
-
-## Commits Made
-
-1. **feat: Complete graph rules compilation** (95d4257)
-   - Full graph rules compilation implementation
-   - Integration with SAVE/DELETE operations
-   - All action types supported
-
-2. **feat: Add advanced SEARCH filter operators** (dc8b0fe)
-   - 9 filter operators implemented
-   - Dynamic WHERE clause building
-   - Comprehensive documentation
-
-3. **test: Add comprehensive test suite for compiled SQL** (1d14209)
-   - 42 SQL validation tests
-   - Integration test framework
-   - Test documentation
-
-## Code Statistics
-
-**Lines Added**: ~1,500 lines across:
-- Graph rules code generation
-- Advanced filter implementation
-- Test suites
-- Documentation
-
-**Files Created**: 6
-- `src/codegen/graph-rules-codegen.js`
-- `docs/ADVANCED_FILTERS.md`
-- `tests/sql-validation.test.js`
-- `tests/integration.test.skip.js`
-- `tests/integration-README.md`
-- `docs/SESSION_SUMMARY.md`
-
-**Files Modified**: 4
-- `src/compiler.js`
-- `src/codegen/operation-codegen.js`
-- `package.json`
-- (various generated files)
-
-## Current Compiler Capabilities
-
-The DZQL Compiler now supports:
-
-### ✅ Entity Definition Parsing
-- Complete DZQL entity syntax
-- Nested JSONB structures
-- Array parameters with depth tracking
-
-### ✅ Permission Compilation
-- Direct field checks
-- Graph traversal with filters
-- Temporal filtering (`{active}`)
-- All CRUD operations (view, create, update, delete)
-
-### ✅ Notification Path Compilation
-- User resolution via graph traversal
-- Temporal filtering
-- Multiple notification paths
-
-### ✅ Graph Rules Compilation
-- on_create, on_update, on_delete triggers
-- All action types
-- Special variable resolution
-- Automatic integration with operations
-
-### ✅ CRUD Operations
-- GET with FK expansion
-- SAVE with upsert logic
-- DELETE (soft or hard)
-- LOOKUP with filtering
-- SEARCH with advanced filters
-
-### ✅ Advanced Features
-- 9 filter operators in SEARCH
-- Dynamic WHERE clause building
-- Reproducible builds (SHA-256 checksums)
-- Git-trackable output
-- Comprehensive error handling
-
-## What's Next?
-
-Potential future enhancements:
-- [ ] Performance benchmarking vs runtime DZQL
-- [ ] Migration generator (schema changes)
-- [ ] Index recommendation based on paths
-- [ ] Query plan analysis
-- [ ] Incremental compilation
-- [ ] Type inference for better error messages
-- [ ] GraphQL/REST API generation from entities
-
-## Branch Status
-
-Branch: `claude/new-features-planning-015GH92pzBxTkA1uWjnjJqbZ`
-
-All changes committed and pushed. Ready for review or PR creation.
-
----
-
-**Session Duration**: Continued from previous session
-**Total Tests**: 55 passing
-**Code Coverage**: All major compilation paths tested
-**Documentation**: Comprehensive docs for all features