graphforge 0.3.8__tar.gz → 0.3.10__tar.gz

{graphforge-0.3.8 → graphforge-0.3.10}/.github/workflows/docs.yml

@@ -6,12 +6,15 @@ on:
     paths:
       - 'docs/**'
       - 'mkdocs.yml'
+      - 'src/graphforge/**'
+      - 'pyproject.toml'
       - '.github/workflows/docs.yml'
   pull_request:
     branches: [main]
     paths:
       - 'docs/**'
       - 'mkdocs.yml'
+      - 'src/graphforge/**'
   workflow_dispatch:
 
 permissions:
@@ -19,7 +22,6 @@ permissions:
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment
 concurrency:
   group: pages
   cancel-in-progress: false
@@ -28,38 +30,38 @@ jobs:
   build:
     name: Build Documentation
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout code
+      - name: Checkout
         uses: actions/checkout@v6
         with:
-          fetch-depth: 0  # Fetch all history for git info
+          fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
 
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 
-      - name: Install documentation dependencies
-        run: |
-          uv pip install --system -e ".[docs]"
+      - name: Install docs dependencies
+        run: uv sync --group docs
 
       - name: Build documentation
-        run: mkdocs build --strict
+        run: uv run mkdocs build --strict
 
       - name: Upload Pages artifact
-        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
-        uses: actions/upload-pages-artifact@v3
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site/
 
   deploy:
     name: Deploy to GitHub Pages
     needs: build
-    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
 
     environment:
@@ -69,4 +71,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{graphforge-0.3.8 → graphforge-0.3.10}/.github/workflows/publish.yaml

@@ -11,6 +11,6 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v6
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.1.0
       - run: uv build
       - run: uv publish

{graphforge-0.3.8 → graphforge-0.3.10}/.github/workflows/test.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
 
@@ -49,7 +49,7 @@ jobs:
         run: uv run pytest tests/integration -n auto -m "not snap" --junitxml=test-results-integration.xml
 
       - name: Upload test results to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         if: always()
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -67,7 +67,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -92,7 +92,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -114,7 +114,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -140,7 +140,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -151,7 +151,7 @@ jobs:
         run: uv sync --all-extras
 
       - name: Restore test durations cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@v5
         with:
           path: .test_durations
           key: tck-durations-${{ github.ref }}
@@ -168,7 +168,7 @@ jobs:
             --junitxml=test-results-tck-${{ matrix.group }}.xml
 
       - name: Upload shard results artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: tck-shard-${{ matrix.group }}
@@ -190,7 +190,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -201,9 +201,10 @@ jobs:
         run: uv sync --all-extras
 
       - name: Download all shard results
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           pattern: tck-shard-*
+          run-id: ${{ github.run_id }}
           merge-multiple: true
           path: tck-results/
 
@@ -253,7 +254,7 @@ jobs:
           " || echo "No duration files found, skipping merge"
 
       - name: Save test durations cache
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@v5
         if: always()
         with:
           path: .test_durations
@@ -265,10 +266,10 @@ jobs:
 
       - name: Report TCK performance metrics
         if: always()
-        run: uv run python3 scripts/tck_perf_report.py test-results-tck.xml --threshold 5
+        run: uv run python3 scripts/tck_perf_report.py test-results-tck.xml --threshold 2
 
       - name: Upload TCK results to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         if: always()
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -278,7 +279,7 @@ jobs:
           fail_ci_if_error: false
 
       - name: Upload merged TCK results artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: tck-test-results
@@ -297,7 +298,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -325,7 +326,7 @@ jobs:
             --junitxml=test-results-cov-${{ matrix.group }}.xml
 
       - name: Upload coverage shard artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: coverage-shard-${{ matrix.group }}
@@ -344,7 +345,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -355,9 +356,10 @@ jobs:
         run: uv sync --all-extras
 
       - name: Download all coverage shards
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           pattern: coverage-shard-*
+          run-id: ${{ github.run_id }}
           merge-multiple: true
           path: cov-results/
 
@@ -387,11 +389,20 @@ jobs:
 
       - name: Check coverage threshold
         run: |
-          uv run coverage combine cov-results/.coverage* 2>/dev/null || true
-          uv run coverage report --fail-under=85 || echo "Coverage below 85% - expected during initial development"
+          uv run python3 -c "
+          import xml.etree.ElementTree as ET, sys
+          tree = ET.parse('coverage.xml')
+          line_rate = float(tree.getroot().get('line-rate', 0))
+          pct = round(line_rate * 100, 1)
+          print(f'Coverage: {pct}%')
+          if pct < 85:
+              print(f'Coverage {pct}% is below 85% threshold')
+              sys.exit(1)
+          print('Coverage meets 85% threshold')
+          " || echo "Coverage check failed - see above for details"
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.xml
@@ -400,7 +411,7 @@ jobs:
           fail_ci_if_error: false
 
       - name: Upload test results to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         if: always()
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -410,7 +421,7 @@ jobs:
           fail_ci_if_error: false
 
       - name: Upload coverage artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: coverage-report
           path: coverage.xml

{graphforge-0.3.8 → graphforge-0.3.10}/.gitignore

@@ -173,6 +173,13 @@ profile_*
 *.log
 .temp/
 tmp/
+
+# macOS Finder "keep both" duplicates (e.g. "file 2.py", "file 2.md", "file 3")
+* [0-9]
+* [0-9].*
 # MkDocs build output
 site/
 tck_*.txt
+
+# Perf baseline results (machine-specific, generated by make test-perf)
+benchmarks/real_dataset_baseline_v*.json

{graphforge-0.3.8 → graphforge-0.3.10}/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.10] - 2026-05-06
+
+### Added
+- **Schema introspection API** (#469, #499) — `labels()`, `relationship_types()`, `node_count(label=None)`, `relationship_count(type=None)` on `GraphForge`; efficient set-union over storage backend
+- **JSON export/import** (#470, #500) — `gf.to_json(path, metadata, indent)` serialises the full graph to a portable JSON file; `GraphForge.from_json(path)` reconstructs it; Hypothesis roundtrip property test
+- **`merge_node()` safe upsert** (#471, #501) — `merge_node(labels, match_on, on_create, on_match)` with regex label validation, index-safe on_match updates, and create/match semantics matching MERGE clause behaviour
+- **`add_graph_documents()` LangChain-compatible ingestion** (#472, #502) — duck-typed batch ingestion accepting any object with `.nodes`/`.relationships` attributes; idempotent edges; rel type pre-check; no `langchain-community` import required
+- **Parse/plan LRU cache** (#464, #504) — `GraphForge(cache_size=N)` caches parsed+planned query pipelines; `clear_cache()` and `cache_info()` for introspection; thread-safe; default size 128
+
+### Fixed
+- **ORDER BY on aliased RETURN DISTINCT property no longer raises UndefinedVariable** (#481, #494) — planner now records `(variable, property)` paths for aliased `PropertyAccess` return items, so `RETURN DISTINCT a.year AS year ORDER BY a.year` resolves correctly
+- **Variable reuse across WITH boundary no longer raises KeyError** (#482, #495) — optimizer's redundant-traversal-elimination pass now treats `Aggregate` as a scope boundary (same as `With`/`Union`/`Subquery`), preventing fresh post-WITH variable bindings from being silently dropped
+- **EXISTS {} subquery crash on anonymous inner node with outer-scope property** (#474, #496) — `_plan_match` now passes `var_name` (always set, from pattern variable or generated) instead of `node_pattern.variable` (can be None) to `_properties_to_predicate`
+- **`shortestPath()` / `allShortestPaths()` parse correctly and raise NotImplementedError** (#468, #497) — previously caused unhelpful `SyntaxError: Unexpected token`; now parsed into `ShortestPathExpression` AST nodes; planner raises `NotImplementedError` with BFS workaround: `MATCH path = (a)-[*1..N]-(b) RETURN length(path) ORDER BY length(path) LIMIT 1`
+
+## [0.3.9] - 2026-05-04
+
+### Added
+- **LALR(1) parser migration** (#365, #430) — grammar refactored to LALR(1); linear-time parsing replaces Earley; unknown function names now detected at parse time; 586 new parser tests; OOM-safe local coverage via sharded `make coverage`
+- **Property equality index for O(1) node lookup** (#390, #427) — in-memory `_prop_index` (prop → value → {node\_id}) on `Graph`; `get_nodes_by_property` and `get_nodes_by_label_and_property` methods; executor `_extract_equality_hints` replaces full scan with index lookup when a `ScanNodes` is followed by a simple equality `Filter`; index maintained on `SET`/`REMOVE`/`DELETE`
+- **Bulk ingestion API** (#389, #444) — `create_node_bulk`, `create_relationship_bulk` (skip per-call Pydantic validation); `bulk_ingest()` context manager defers statistics rebuilds until exit via `_flush_deferred_stats()`; CSV loader uses bulk path; significant throughput improvement for dataset loading
+- **Real-dataset QA and performance profiling suite** (#417, #419) — 5-tier perf suite (karate 34n, ego-facebook 4k, amazon 334k, livejournal 4M, orkut 117M edges); `scripts/perf_report.py` renders baseline/delta Markdown tables; `make test-perf`, `make test-perf-xs`, `make test-perf-large`, `make test-perf-slow` targets; L/XL tier benchmarks added; `perf_slow` marker applied consistently (#440, #441)
+- **`elementId()` scalar function** (#211, #447) — GQL-spec `elementId(node|rel)` returns the element id as `CypherString`; `id()` continues to return `CypherInt`; NULL-safe; arity-checked
+- **Scale limits documentation** — `docs/reference/scale-limits.md` explains LIMIT-respecting (~20M edges) vs full-scan (~1M edges) performance ceilings; README graph-size claim updated to reflect edge-count as binding constraint (#443)
+- **`make pre-push-fast`** (#429, #437) — fast-fail pre-push shortcut (format, lint, type, security, docstrings; no coverage); inline coverage thresholds (85% total, 90% patch)
+
+### Fixed
+- **Fixed-length hop ignores rel predicate** (#431, #439) — fixed-length traversal now evaluates `rel_pattern.predicate` inline; parser predicate whitelist replaced with open accept
+- **var-length relationship predicates** (#381, #425) — `_var_length_reachable` now evaluates inline relationship predicates (e.g. `[*1..3 {weight: 1}]`) at each hop instead of ignoring them
+- **Cross-hop edge uniqueness in multi-segment patterns** (#382, #425) — `initial_used_edge_ids` seeds the visited-edge set from prior hops, preventing the same edge being traversed twice across pattern segments
+- **SQLite delete persistence** (#409, #421) — deleted nodes and edges now removed from SQLite backend; previously they resurrected on reload
+- **SQLite bulk I/O** (#392, #421) — `save_nodes_bulk` / `save_edges_bulk` use `executemany`; `_save_graph_to_backend` wrapped in rollback; resolves >20s hang on M-tier reload
+- **`sys.setrecursionlimit` thread safety** (#433, #445) — limit set once in `CypherParser.__init__` instead of per-request get/set/restore, eliminating races in concurrent parser use
+- **Transaction rollback restores ID counters** (#412) — `rollback()` restores `_next_node_id` and `_next_edge_id`, preventing ID gaps after aborted transactions
+- **Closed-instance guard** (#411) — `execute()` and mutation methods raise `RuntimeError` after `close()`
+- **`DatasetInfo` rejects `ftp://` URLs** (#414)
+- **TCK metrics CI gate** (#410) — `tck_metrics.py` exits non-zero on TCK failures
+
+### Performance
+- **UNWIND + WITH LIMIT short-circuit** (#393, #443) — `_pipeline_limit` reverse-scan treats pass-through `With(limit_count=N, no sort, no filter)` as transparent; `_execute_unwind` respects `row_limit` and exits early; `UNWIND range(1M, 2M) AS i WITH i LIMIT 3000 RETURN sum(i)` drops from ~4.5s to <10ms
+- **LIMIT short-circuit for scan and expand operators** (#422, #423) — `_pipeline_limit` look-ahead stops scan/expand at row budget; write operators and Filter block short-circuit to preserve correctness
+- **SQLite PRAGMA tuning** (#392, #446) — `synchronous=NORMAL` (eliminates `fdatasync` per commit), 64 MB page cache (`cache_size=-65536`), `temp_store=MEMORY`; safe with WAL mode for analytical workloads
+- **Lazy statistics timestamp** — `_stats_last_updated` stamped at read time in `get_statistics()` rather than on every add; `_defer_stats` flag eliminates per-edge stat overhead during bulk ingest
+
+### CI / Tooling
+- **Test suite zero-base renovation** (#428, #438) — fixture strategy audit, duplication removal, marker consistency, parametrization improvements across unit and integration suites
+- **GHA actions updated** — `actions/upload-artifact` v7, `actions/download-artifact` v8, `codecov/codecov-action` v6, `actions/upload-pages-artifact` v5, `astral-sh/setup-uv` v8.1.0
+
 ## [0.3.8] - 2026-05-02
 
 ### Fixed - TCK Feature Completeness (3885/3885 passing)

{graphforge-0.3.8 → graphforge-0.3.10}/CLAUDE.md

@@ -51,6 +51,16 @@ make pre-push
 
 Runs: format-check, lint, type-check, coverage (85% total, 90% patch).
 
+**Before running tests locally during planning:** If the branch has no committed changes yet (i.e., you're still in the planning phase), check the last CI run instead of running the full test suite locally. This avoids OOM errors from running all tests unnecessarily.
+
+```bash
+# Check last CI run status and test results
+gh run list --branch main --limit 5
+gh run view <run-id> --log-failed   # see only failed tests
+```
+
+Only run tests locally once you have actual code changes to validate.
+
 ### 5. Commit with Issue Number
 
 ```bash
@@ -77,16 +87,21 @@ GitHub automatically closes the issue when PR merges.
 ## Development Commands
 
 ```bash
-make pre-push          # Run all checks (mirrors CI)
+make pre-push          # Run all checks (mirrors CI): format, lint, type, security, docstrings, coverage + thresholds
+make pre-push-fast     # Fast checks only (no coverage, ~30s): format, lint, type, security, docstrings
 make test              # All tests
 make test-unit         # Unit tests only
 make test-integration  # Integration tests only
-make coverage          # Run with coverage
+make coverage          # Run with coverage + validate thresholds (sharded, includes 85%/90% checks)
+make coverage-quick    # Coverage on unit tests only (fast feedback during development)
 make coverage-report   # View HTML coverage report
 make coverage-diff     # Coverage for changed files only
 
 # Run tests in parallel (4x faster for TCK)
 pytest tests/ -n auto
+
+# Override worker count (default 4, lower to reduce memory)
+PYTEST_WORKERS=2 make test
 ```
 
 **Coverage Requirements:**
@@ -94,6 +109,8 @@ pytest tests/ -n auto
 - Patch: 90% minimum for changed files
 - Best practice: Aim for 100% on new code
 
+**When to use `pre-push-fast`:** iterating on non-test changes (refactors, docs, config). Always run the full `pre-push` before opening a PR.
+
 ## Architecture: 4-Layer System
 
 ```

graphforge-0.3.10/Makefile

@@ -0,0 +1,189 @@
+.PHONY: help lint format type-check security test pre-push pre-push-fast clean test-tck docstring-coverage test-network test-perf test-perf-xs test-perf-slow test-perf-large coverage coverage-quick coverage-report coverage-diff coverage-strict check-coverage check-patch-coverage test-durations test-analytics docs-serve docs-build docs-clean
+
+help:  ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+lint:  ## Run ruff linter
+	uv run ruff check .
+
+format:  ## Format code with ruff
+	uv run ruff format .
+
+format-check:  ## Check code formatting
+	uv run ruff format --check .
+
+type-check:  ## Run mypy type checker
+	uv run mypy src/graphforge --strict-optional --show-error-codes
+
+security:  ## Run Bandit security scanner
+	uv run bandit -c pyproject.toml -r src/
+
+docstring-coverage:  ## Check docstring coverage (90% minimum)
+	uv run interrogate src/graphforge --fail-under 90 --quiet
+
+test:  ## Run all tests in parallel (excludes snap/network downloads)
+	uv run pytest tests/ -n $${PYTEST_WORKERS:-4} -m "not snap"
+
+test-unit:  ## Run unit tests in parallel
+	uv run pytest tests/unit -n $${PYTEST_WORKERS:-4}
+
+test-integration:  ## Run integration tests in parallel (excludes snap/network downloads)
+	uv run pytest tests/integration -n $${PYTEST_WORKERS:-4} -m "not snap"
+
+test-network:  ## Run external network/download tests (snap datasets; requires internet)
+	uv run pytest tests/ -m "snap" -v
+
+test-perf-xs:  ## Run perf QA for XS/S datasets only (karate + ego-facebook, ~3 MB total)
+	uv run pytest tests/perf/ -m "perf and not perf_large and not perf_slow" -k "xs or s_face" -v -s
+
+test-perf:  ## Run perf QA through M-tier (Amazon 334k nodes, ~15 MB); writes baseline JSON
+	uv run pytest tests/perf/ -m "perf and not perf_large and not perf_slow" -v -s
+	@echo ""
+	@echo "Baseline written to benchmarks/real_dataset_baseline_v0.3.9.json"
+
+test-perf-slow:  ## Run slow two-hop full-expansion benchmarks (opt-in; minutes on S/M, hours on L)
+	uv run pytest tests/perf/ -m "perf_slow" -v -s
+
+test-perf-large:  ## Run L/XL tiers (livejournal 500 MB, cit-patents 270 MB, orkut 1.7 GB); needs 16 GB RAM
+	uv run pytest tests/perf/ -m "perf and perf_large" -v -s --timeout=3600
+
+test-tck:  ## Run TCK compliance tests in parallel
+	uv run pytest tests/tck/ -n $${PYTEST_WORKERS:-4} -v
+
+coverage:  ## Run tests with coverage and validate thresholds (sharded to avoid OOM)
+	@echo "━━━ Coverage shard 1/2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	uv run coverage erase
+	uv run pytest tests/unit tests/integration -m "not snap" \
+		--splits 2 --group 1 \
+		-n $${PYTEST_WORKERS:-4} \
+		--cov=src --cov-branch \
+		--cov-report= \
+		--cov-append
+	@echo "━━━ Coverage shard 2/2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	uv run pytest tests/unit tests/integration -m "not snap" \
+		--splits 2 --group 2 \
+		-n $${PYTEST_WORKERS:-4} \
+		--cov=src --cov-branch \
+		--cov-report=term-missing \
+		--cov-report=xml \
+		--cov-append
+	@echo "━━━ Threshold checks ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@uv run coverage report --fail-under=85 || \
+		(echo "❌ Total coverage below 85% threshold" && exit 1)
+	@echo "✅ Total coverage ≥ 85%"
+	@DIFF_OUT=$$(git diff --name-only origin/main... 2>&1) || \
+		{ echo "❌ git diff failed — check that origin/main is accessible"; exit 1; }; \
+	CHANGED_FILES=$$(printf '%s\n' "$$DIFF_OUT" | grep '^src/.*\.py$$' || true); \
+	if [ -z "$$CHANGED_FILES" ]; then \
+		echo "ℹ️  No source files changed — skipping patch coverage check"; \
+	else \
+		echo "Changed files:"; \
+		echo "$$CHANGED_FILES" | sed 's/^/  - /'; \
+		INCLUDE_PATTERN=$$(echo "$$CHANGED_FILES" | tr '\n' ',' | sed 's/,$$//'); \
+		uv run coverage report --include="$$INCLUDE_PATTERN" --fail-under=90 || \
+			(echo "❌ Patch coverage below 90% for changed files" && \
+			 echo "   Run 'make coverage-report' to see detailed coverage" && \
+			 exit 1); \
+		echo "✅ Patch coverage ≥ 90%"; \
+	fi
+
+coverage-quick:  ## Quick coverage on unit tests only (for iterative development)
+	@echo "Running unit tests with coverage..."
+	uv run pytest tests/unit \
+		-n $${PYTEST_WORKERS:-4} \
+		--cov=src --cov-branch \
+		--cov-report=term-missing \
+		--cov-report=xml
+
+test-durations:  ## Generate .test_durations for pytest-split shard balancing
+	uv run pytest tests/unit tests/integration -m "not snap" \
+		--store-durations --durations-path=.test_durations -q
+
+test-analytics:  ## Run tests with analytics output (JUnit XML)
+	@echo "Running tests with analytics output..."
+	uv run pytest tests/unit tests/integration \
+		--junitxml=test-results-local.xml \
+		-v
+
+check-coverage:  ## Validate total coverage meets 85% threshold (uses existing .coverage data)
+	@echo "Checking coverage thresholds..."
+	@uv run coverage report --fail-under=85 || \
+		(echo "❌ Coverage below 85% threshold" && exit 1)
+	@echo "✅ Coverage meets threshold"
+
+coverage-strict:  ## Strict 90% coverage check for new features
+	@echo "Checking strict coverage (90%)..."
+	@uv run coverage report --fail-under=90 || \
+		(echo "❌ Coverage below 90% - consider adding more tests" && exit 1)
+	@echo "✅ Coverage meets strict threshold"
+
+coverage-report:  ## Generate HTML coverage report and open in browser
+	@echo "Generating HTML coverage report..."
+	uv run coverage html
+	@echo "Opening coverage report in browser..."
+	@open htmlcov/index.html || xdg-open htmlcov/index.html || \
+		echo "Coverage report generated at htmlcov/index.html"
+
+coverage-diff:  ## Show coverage for changed files only
+	@echo "Showing coverage for changed files..."
+	@CHANGED_FILES=$$(git diff --name-only origin/main... | grep '\.py$$' || true); \
+	if [ -z "$$CHANGED_FILES" ]; then \
+		echo "ℹ️  No Python files changed"; \
+	else \
+		INCLUDE_PATTERN=$$(echo "$$CHANGED_FILES" | tr '\n' ',' | sed 's/,$$//'); \
+		uv run coverage report --include="$$INCLUDE_PATTERN"; \
+	fi
+
+check-patch-coverage:  ## Validate patch coverage for changed files (90% threshold, uses existing .coverage data)
+	@echo "Checking patch coverage for changed files..."
+	@DIFF_OUT=$$(git diff --name-only origin/main... 2>&1) || \
+		{ echo "❌ git diff failed — check that origin/main is accessible"; exit 1; }; \
+	CHANGED_FILES=$$(printf '%s\n' "$$DIFF_OUT" | grep '^src/.*\.py$$' || true); \
+	if [ -z "$$CHANGED_FILES" ]; then \
+		echo "ℹ️  No source files changed - skipping patch coverage check"; \
+	else \
+		echo "Changed files:"; \
+		echo "$$CHANGED_FILES" | sed 's/^/  - /'; \
+		INCLUDE_PATTERN=$$(echo "$$CHANGED_FILES" | tr '\n' ',' | sed 's/,$$//'); \
+		uv run coverage report --include="$$INCLUDE_PATTERN" --fail-under=90 || \
+			(echo "❌ Patch coverage below 90% for changed files" && \
+			 echo "   Run 'make coverage-report' to see detailed coverage" && \
+			 exit 1); \
+		echo "✅ Patch coverage meets 90% threshold"; \
+	fi
+
+pre-push-fast:  ## Run fast checks only — format, lint, type, security, docstrings (no coverage, ~30s)
+	@echo "━━━ Format check ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@$(MAKE) format-check
+	@echo "━━━ Lint ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@$(MAKE) lint
+	@echo "━━━ Type check ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@$(MAKE) type-check
+	@echo "━━━ Security ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@$(MAKE) security
+	@echo "━━━ Docstring coverage ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@$(MAKE) docstring-coverage
+	@echo "✅ Fast checks passed! Run 'make pre-push' to include coverage."
+
+pre-push:  ## Run all pre-push checks — fast checks + coverage with thresholds (mirrors CI)
+	@$(MAKE) pre-push-fast
+	@echo "━━━ Coverage + thresholds ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@$(MAKE) coverage
+	@echo "✅ All pre-push checks passed!"
+
+clean:  ## Clean up cache files
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	rm -f test-results*.xml coverage.xml 2>/dev/null || true
+	rm -rf htmlcov/ 2>/dev/null || true
+
+docs-serve:  ## Serve docs locally with live reload (http://127.0.0.1:8000)
+	uv run --group docs mkdocs serve
+
+docs-build:  ## Build docs site to site/ (strict mode)
+	uv run --group docs mkdocs build --strict
+
+docs-clean:  ## Remove built docs
+	rm -rf site/