chore: crush git history - reborn from consolidation on 2026-03-10

2026-03-10 00:00:00 -07:00
commit d278c4b105
313 changed files with 87549 additions and 0 deletions
@@ -0,0 +1,114 @@
+# Cache & CI/CD Integration
+
+APOPHIS includes an incremental test cache that speeds up test runs by skipping unchanged routes. This document covers cache invalidation strategies and CI/CD integration.
+
+## How the Cache Works
+
+The cache stores generated test commands per route in `.apophis-cache.json`:
+
+```json
+{
+  "version": 1,
+  "entries": {
+    "a1b2c3d4": {
+      "routeHash": "a1b2c3d4",
+      "schemaHash": "e5f6g7h8",
+      "path": "/users",
+      "method": "GET",
+      "commands": [{ "params": {}, "headers": {} }],
+      "timestamp": 1704067200000
+    }
+  }
+}
+```
+
+Each entry is keyed by a hash of the route's path, method, and schema. If the schema changes, the entry is automatically invalidated.
+
+## Environment Behavior
+
+| Environment | Cache | Reason |
+|-------------|-------|--------|
+| `production` | Disabled | No file I/O, no cache hits needed |
+| `test` | Disabled | Tests should be deterministic, no cache pollution |
+| `development` | Enabled | Speeds up iterative testing |
+| default | Enabled | Backward compatible |
+
+## Cache Invalidation
+
+### 1. Automatic Invalidation
+
+The cache is automatically invalidated when:
+- A route's schema changes (detected via schema hash mismatch)
+- The cache file is corrupted or has the wrong version
+
+### 2. CI/CD Hints via Environment Variable
+
+Set `APOPHIS_CHANGED_ROUTES` to invalidate specific routes on the next test run. The cache is checked during `contract()` and `stateful()` test runs:
+
+```bash
+# Exact path
+APOPHIS_CHANGED_ROUTES=/users
+
+# Multiple paths (comma-separated)
+APOPHIS_CHANGED_ROUTES=/users,/items,/orders
+
+# Method prefix
+APOPHIS_CHANGED_ROUTES=GET /users,POST /orders
+
+# Wildcards
+APOPHIS_CHANGED_ROUTES=/api/*,/admin/**
+```
+
+Patterns support:
+- **Exact path**: `/users`
+- **Method prefix**: `GET /users`
+- **Single wildcard**: `/api/*` (matches one segment)
+- **Double wildcard**: `/api/**` (matches any depth)
+
+### 3. CI/CD Hints via File
+
+Create `.apophis-hints.json` in your project root:
+
+```json
+{
+  "changed": [
+    "/users",
+    "GET /items",
+    "/api/**"
+  ]
+}
+```
+
+This is useful when your CI system can write a file but setting env vars is awkward.
+
+## CI/CD Examples
+
+### GitHub Actions
+
+See `docs/examples/github-actions.yml` for a complete workflow.
+
+Key steps:
+1. Run tests with cache
+2. If tests fail, re-run without cache to rule out cache issues
+3. On main branch, clear cache after deployment
+
+### GitLab CI
+
+See `docs/examples/gitlab-ci.yml` for a complete pipeline.
+
+### Best Practices
+
+1. **Commit the cache file?** No — `.apophis-cache.json` should be in `.gitignore`
+2. **Cache in CI?** Yes — cache `.apophis-cache.json` between runs for faster builds
+3. **Invalidate on deploy?** Yes — set `APOPHIS_CHANGED_ROUTES` from your deployment diff
+4. **Debug cache issues?** Set `APOPHIS_LOG_LEVEL=debug` to see cache hits/misses
+
+## Logging
+
+Cache operations are logged at the `info` level:
+
+```
+[apophis] Invalidated 3 cached route(s) from CI/CD hints
+```
+
+Set `APOPHIS_LOG_LEVEL=debug` to see detailed cache operations.