first commit

plugin/filter/MAINTENANCE.md

@@ -0,0 +1,50 @@
+# Maintaining the Memo Filter Engine
+
+The engine is memo-specific; any future field or behavior changes must stay
+consistent with the memo schema and store implementations. Use this guide when
+extending or debugging the package.
+
+## Adding a New Memo Field
+
+1. **Update the schema**  
+   - Add the field entry in `schema.go`.  
+   - Define the backing column (`Column`), JSON path (if applicable), type, and
+     allowed operators.  
+   - Include the CEL variable in `EnvOptions`.
+2. **Adjust parser or renderer (if needed)**  
+   - For non-scalar fields (JSON booleans, lists), add handling in
+     `parser.go` or extend the renderer helpers.  
+   - Keep validation in the parser (e.g., reject unsupported operators).
+3. **Write a golden test**  
+   - Extend the dialect-specific memo filter tests under
+     `store/db/{sqlite,mysql,postgres}/memo_filter_test.go` with a case that
+     exercises the new field.
+4. **Run `go test ./...`** to ensure the SQL output matches expectations across
+   all dialects.
+
+## Supporting Dialect Nuances
+
+- Centralize differences inside `render.go`. If a new dialect-specific behavior
+  emerges (e.g., JSON operators), add the logic there rather than leaking it
+  into store code.
+- Use the renderer helpers (`jsonExtractExpr`, `jsonArrayExpr`, etc.) rather than
+  sprinkling ad-hoc SQL strings.
+- When placeholders change, adjust `addArg` so that argument numbering stays in
+  sync with store queries.
+
+## Debugging Tips
+
+- **Parser errors** – Most originate in `buildCondition` or schema validation.
+  Enable logging around `parser.go` when diagnosing unknown identifier/operator
+  messages.
+- **Renderer output** – Temporary printf/log statements in `renderCondition` help
+  identify which IR node produced unexpected SQL.
+- **Store integration** – Ensure drivers call `filter.DefaultEngine()` exactly once
+  per process; the singleton caches the parsed CEL environment.
+
+## Testing Checklist
+
+- `go test ./store/...` ensures all dialect tests consume the engine correctly.
+- Add targeted unit tests whenever new IR nodes or renderer paths are introduced.
+- When changing boolean or JSON handling, verify all three dialect test suites
+  (SQLite, MySQL, Postgres) to avoid regression.