graphforge 0.3.8__tar.gz → 0.3.9__tar.gz

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

@@ -36,7 +36,7 @@ jobs:
           fetch-depth: 0  # Fetch all history for git info
 
       - 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
@@ -52,7 +52,7 @@ jobs:
 
       - 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
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site/
 
@@ -69,4 +69,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.9}/.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.9}/.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
@@ -268,7 +269,7 @@ jobs:
         run: uv run python3 scripts/tck_perf_report.py test-results-tck.xml --threshold 5
 
       - 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.9}/.gitignore

@@ -176,3 +176,6 @@ tmp/
 # 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.9}/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.9}/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.9/Makefile

@@ -0,0 +1,180 @@
+.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
+
+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

{graphforge-0.3.8 → graphforge-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphforge
-Version: 0.3.8
+Version: 0.3.9
 Summary: Composable graph tooling for analysis, construction, and refinement
 Project-URL: Homepage, https://github.com/DecisionNerd/graphforge
 Project-URL: Repository, https://github.com/DecisionNerd/graphforge
@@ -38,7 +38,7 @@ Requires-Dist: pytest-split>=0.9.0; extra == 'dev'
 Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
-Requires-Dist: ruff==0.15.4; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-autorefs>=1.0.0; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
@@ -84,6 +84,9 @@ Description-Content-Type: text/markdown
 
 ## Why GraphForge?
 
+> *We are not building a database for applications.*
+> *We are building a graph execution environment for thinking.*
+
 Modern data science and ML workflows increasingly produce graph-shaped data — entity relationships extracted by LLMs, citation networks, dependency graphs, social connections, knowledge bases. Working with this data shouldn't require running a database server. GraphForge brings the full expressiveness of the openCypher query language to the Python notebook and script environment: zero configuration, single-file persistence, and first-class Python integration.
 
 | | NetworkX | **GraphForge** | Neo4j / Memgraph |
@@ -92,19 +95,20 @@ Modern data science and ML workflows increasingly produce graph-shaped data —
 | **Query language** | Python API | **Full openCypher** | Full Cypher |
 | **Persistence** | Manual | **SQLite (automatic)** | Native |
 | **Notebook-friendly** | ✓ | ✓ | Requires connection |
-| **Graph size** | Millions | < 10M nodes | Billions |
+| **Graph size** | Millions | up to ~20M edges† | Billions |
 | **TCK compliance** | N/A | **100% (3,885/3,885)** | ~100% |
 
 **Use GraphForge for:** knowledge graphs, citation networks, research workflows, LLM output storage, social network analysis in notebooks.
 
-**Use a production database for:** high throughput, multi-user access, graphs > 10M nodes.
+**Use a production database for:** high throughput, multi-user access, or graphs beyond the limits in [Scale Limits](docs/reference/scale-limits.md).
 
-> *We are not building a database for applications.*
-> *We are building a graph execution environment for thinking.*
+† *Traversal queries with LIMIT scale to ~20M edges; full-scan aggregations are practical up to ~1M edges.*
+
+### v0.3.9 — Performance Release
 
-### v0.3.8 — Full TCK Compliance
+v0.3.9 delivers substantial performance improvements over v0.3.8: LALR(1) linear-time parsing, O(1) property equality index, LIMIT short-circuit for traversal and UNWIND, bulk ingestion API, SQLite PRAGMA tuning, and `elementId()`. TCK compliance is maintained at **3,885/3,885 (100%)**.
 
-As of v0.3.8, GraphForge passes **all 3,885 openCypher TCK scenarios** with zero failures and zero expected failures. This is the first embedded Python graph database to achieve complete openCypher TCK compliance.
+See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
 
 ---
 
@@ -282,9 +286,6 @@ load_dataset(db, "snap-ego-facebook")   # Facebook ego networks (SNAP)
 load_dataset(db, "ldbc-snb-sf0.1")      # Social network benchmark (LDBC)
 load_dataset(db, "netrepo-karate")      # Karate club (NetworkRepository)
 
-# Load from URL directly
-load_dataset(db, "https://nrvis.com/download/data/labeled/karate.zip")
-
 # Browse available datasets
 for ds in list_datasets(source="snap")[:3]:
     print(f"{ds.name}: {ds.nodes:,} nodes, {ds.edges:,} edges")
@@ -300,7 +301,7 @@ results = db.execute("""
 **Available sources:**
 - **SNAP** (Stanford): 95 social, web, email, citation, and collaboration networks
 - **LDBC**: 10 social network benchmark datasets with temporal data
-- **NetworkRepository**: 10 pre-registered + thousands via direct URL
+- **NetworkRepository**: 10 pre-registered datasets
 
 ---
 
@@ -329,13 +330,13 @@ GraphForge is built in four independent layers:
 
 ```
 ┌─────────────────────────────────────────────────┐
-│  Parser         cypher.lark + parser.py          │  Cypher → AST
+│  Parser         cypher.lark + parser.py         │  Cypher → AST
 ├─────────────────────────────────────────────────┤
-│  Planner        planner.py + operators.py        │  AST → Logical plan
+│  Planner        planner.py + operators.py       │  AST → Logical plan
 ├─────────────────────────────────────────────────┤
-│  Executor       executor.py + evaluator.py       │  Plan → Results
+│  Executor       executor.py + evaluator.py      │  Plan → Results
 ├─────────────────────────────────────────────────┤
-│  Storage        memory.py + sqlite_backend.py    │  In-memory + SQLite
+│  Storage        memory.py + sqlite_backend.py   │  In-memory + SQLite
 └─────────────────────────────────────────────────┘
 ```
 
@@ -367,8 +368,9 @@ make coverage
 | Version | Focus | Status |
 |---------|-------|--------|
 | v0.3.8 | Full TCK compliance (3,885/3,885) | **Released** |
-| v0.3.9 | Performance: LALR parser, property indexes, SQLite tuning | Planned |
-| v0.4.0 | Analytics: NetworkX/igraph integration, SNA algorithms | Planned |
+| v0.3.9 | Performance: LALR parser, property indexes, bulk ingest, SQLite tuning, LIMIT short-circuit | **Released** |
+| v0.3.10 | Analytics integration: NetworkX/igraph export, parse/plan cache | Planned |
+| v0.4.0 | Native SNA algorithms: PageRank, betweenness, WCC, shortest path via `CALL gf.algo.*` | Planned |
 | v1.0 | Production-ready: thread safety, large graph support | Future |
 
 See [CHANGELOG.md](CHANGELOG.md) for full release history.