graphforge 0.3.5__tar.gz → 0.3.6__tar.gz

{graphforge-0.3.5 → graphforge-0.3.6}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.6] - 2026-02-28
+
+### Fixed - TCK Harness Correctness
+- **Integer property comparison** (#252) — TCK harness was comparing integer properties as strings, causing ~423 false failures; now coerced correctly
+- **Map literal value coercion** (#261) — `_parse_map_literal` in conftest now coerces numeric string values, fixing ~30 false failures
+
+### Fixed - Temporal Correctness
+- **`date({})` / `datetime({})` / `time({})` map constructors** (#253, #268) — component validation, UTC defaults, and function-as-argument parsing
+- **`UnexpectedEOF` on duration/datetime literals** (#254) — parser now handles all ISO 8601 duration and datetime forms
+- **Timezone offset `+HH:MM` parsing** (#255) — `+HH:MM` and `-HH:MM` offsets now parsed correctly
+- **Date map constructor component validation** (#256) — out-of-range components raise `ValueError`
+- **`datetime(string)` defaults to UTC** (#276) — string datetimes without timezone now default to UTC per spec
+- **Map constructor omitted components default to 1** (#278) — `date({year: 2015})` → `2015-01-01`, not error
+- **`TRUNCATE` units: week, weekYear, quarter, decade, century, millennium** (#269) — all truncation units now return correct values
+- **Week-based and select-form datetime constructors** (#270) — `datetime({week: 30, ...})` and similar forms return correct values
+- **Duration serialization, comparison, multiplication, and fractional arithmetic** (#271) — full duration correctness including `duration.between()`
+- **`datetime(aDatetime)` type coercion** (#274) — coercing datetime subtypes no longer conflicts with `:E` label parser token
+- **Compact ISO 8601 date/datetime string formats** (#273) — ordinal (`YYYY-DDD`, `YYYYDDD`), week date (`YYYY-Www[-D]`), year-month (`YYYY-MM`, `YYYYMM`), and year-only (`YYYY`) all parsed correctly
+- **IANA timezone names** (#272) — `[Region/City]` suffix in datetime strings is parsed; IANA zone is authoritative over explicit offset; historical second-precision offsets (e.g. `+00:53:28`) handled correctly
+
+### TCK Coverage
+- **2,507 passing** (up from ~1,694 at v0.3.5) — +813 net new passing scenarios
+- Theme: all temporal TCK scenarios now pass; harness accuracy fully corrected
+
 ## [0.3.5] - 2026-02-19
 
 ### Added - Math Functions (#195, #196, #197)

{graphforge-0.3.5 → graphforge-0.3.6}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help lint format type-check security test pre-push clean test-tck test-tck-parallel
+.PHONY: help lint format type-check security test pre-push clean test-tck docstring-coverage test-network
 
 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}'
@@ -18,30 +18,31 @@ type-check:  ## Run mypy type checker
 security:  ## Run Bandit security scanner
 	uv run bandit -c pyproject.toml -r src/
 
-test:  ## Run all tests
-	uv run pytest tests/
+docstring-coverage:  ## Check docstring coverage (90% minimum)
+	uv run interrogate src/graphforge --fail-under 90 --quiet
 
-test-unit:  ## Run unit tests only
-	uv run pytest tests/unit -v
+test:  ## Run all tests in parallel (excludes snap/network downloads)
+	uv run pytest tests/ -n auto -m "not snap"
 
-test-integration:  ## Run integration tests only
-	uv run pytest tests/integration -v
+test-unit:  ## Run unit tests in parallel
+	uv run pytest tests/unit -n auto
 
-test-tck:  ## Run TCK compliance tests
-	uv run pytest tests/tck/ -v
+test-integration:  ## Run integration tests in parallel (excludes snap/network downloads)
+	uv run pytest tests/integration -n auto -m "not snap"
 
-test-tck-parallel:  ## Run TCK tests in parallel (requires pytest-xdist)
+test-network:  ## Run external network/download tests (snap datasets; requires internet)
+	uv run pytest tests/ -m "snap" -v
+
+test-tck:  ## Run TCK compliance tests in parallel
 	uv run pytest tests/tck/ -n auto -v
 
 coverage:  ## Run tests with coverage measurement
 	@echo "Running tests with coverage..."
-	uv run pytest tests/unit tests/integration \
+	uv run pytest tests/unit tests/integration -m "not snap" \
 		--cov=src \
 		--cov-branch \
 		--cov-report=term-missing \
-		--cov-report=xml \
-		--cov-report=html \
-		-n auto
+		--cov-report=xml
 
 test-analytics:  ## Run tests with analytics output (JUnit XML)
 	@echo "Running tests with analytics output..."
@@ -61,7 +62,9 @@ coverage-strict:  ## Strict 90% coverage check for new features
 		(echo "❌ Coverage below 90% - consider adding more tests" && exit 1)
 	@echo "✅ Coverage meets strict threshold"
 
-coverage-report:  ## Open HTML coverage report in browser
+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"
@@ -92,7 +95,7 @@ check-patch-coverage:  ## Validate patch coverage for changed files (90% thresho
 		echo "✅ Patch coverage meets 90% threshold"; \
 	fi
 
-pre-push: format-check lint type-check security coverage check-coverage check-patch-coverage  ## Run all pre-push checks (mirrors CI)
+pre-push: format-check lint type-check security docstring-coverage coverage check-coverage check-patch-coverage  ## Run all pre-push checks (mirrors CI)
 	@echo "✅ All pre-push checks passed!"
 
 clean:  ## Clean up cache files

{graphforge-0.3.5 → graphforge-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphforge
-Version: 0.3.5
+Version: 0.3.6
 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
@@ -98,25 +98,23 @@ Modern data science and ML workflows increasingly produce **graph-shaped data**
 > *We are not building a database for applications.*
 > *We are building a graph execution environment for thinking.*
 
-### Latest Release: v0.3.4
+### Latest Release: v0.3.6
 
-Version 0.3.4 completes operator and string function enhancements:
+Version 0.3.6 is a correctness release — all temporal TCK scenarios now pass and the TCK harness is fully accurate:
 
-- **String functions**: `toUpper()`, `toLower()` camelCase variants - Aliases for existing UPPER/LOWER functions
-- **Logical operators**: `XOR` - Exclusive OR with proper precedence (NOT > AND > XOR > OR) and NULL handling
-- **Arithmetic operators**: `^` (power/exponentiation) - Right-associative with full numeric support (negative and fractional exponents)
-- **List operations**: List slicing `[start..end]` and negative indexing `list[-1]` (already implemented, now documented)
-- **Comprehensive testing**: 79 new integration tests (18 string, 22 XOR, 39 power)
-- **Operator completion**: List operators 100% (5/5), Overall operators 94% (32/34, up from 88%)
-- **Function progress**: 56/72 functions (78%, up from 76%)
+- **Temporal correctness**: compact ISO 8601 formats, IANA timezone names, `TRUNCATE` units, duration arithmetic, map constructors — all fixed
+- **TCK harness**: integer/map literal coercion bugs fixed, eliminating ~450 false failures
+- **+813 net new passing TCK scenarios**: 2,507 passing (up from 1,694 at v0.3.5)
 
 **Previous Releases**:
+- **v0.3.5**: `sqrt()`, `rand()`, `pow()`, aggregation function fixes, 5 TCK step definitions (+129 scenarios)
+- **v0.3.4**: `toUpper()`/`toLower()` aliases, `XOR` operator, `^` power operator, list slicing docs
 - **v0.3.3**: Pattern comprehensions, CALL subqueries, Pattern predicates
 - **v0.3.2**: List operations (`filter()`, `extract()`, `reduce()`)
 - **v0.3.1**: Quantifier functions (`all()`, `any()`, `none()`, `single()`), `exists()`, `isEmpty()`
 - **v0.3.0**: OPTIONAL MATCH, UNION, List comprehensions, EXISTS/COUNT subqueries, Variable-length paths, 109+ datasets
 
-**TCK Coverage**: ~38% openCypher compatibility
+**TCK Coverage**: ~64% of collected scenarios passing (2,507 / 3,885)
 
 See [CHANGELOG.md](CHANGELOG.md) for complete release notes.
 
@@ -1415,7 +1413,9 @@ GraphForge implements a **practical subset of OpenCypher** focused on common gra
 
 **Functions:**
 - String: length, substring, toUpper/toLower (both camelCase and UPPERCASE variants), trim, reverse, split, replace, left, right, ltrim, rtrim
+- Math: abs, ceil, floor, round, sign, sqrt, rand, pow
 - Type conversion: toInteger, toFloat, toString, toBoolean
+- Aggregation: count, sum, avg, min, max, collect, percentileDisc, percentileCont, stDev, stDevP
 - Spatial: point, distance
 - Temporal: date, datetime, time, duration
 - Graph: id, labels, type
@@ -1460,6 +1460,7 @@ GraphForge tracks compliance using the openCypher Technology Compatibility Kit (
 | v0.1.4 | 1,277/7,722 | 16.5% |
 | v0.2.0 | ~1,900/7,722 | ~25% |
 | v0.3.0 | ~3,000/7,722 | ~39% |
+| v0.3.5 | 1,694/3,885 collected | ~44% collected |
 | v0.4.0 (target) | ~4,250/7,722 | ~55% |
 | v0.5.0 (target) | ~5,400/7,722 | ~70% |
 | v0.6.0 (target) | ~6,300/7,722 | ~82% |

{graphforge-0.3.5 → graphforge-0.3.6}/README.md

@@ -52,25 +52,23 @@ Modern data science and ML workflows increasingly produce **graph-shaped data**
 > *We are not building a database for applications.*
 > *We are building a graph execution environment for thinking.*
 
-### Latest Release: v0.3.4
+### Latest Release: v0.3.6
 
-Version 0.3.4 completes operator and string function enhancements:
+Version 0.3.6 is a correctness release — all temporal TCK scenarios now pass and the TCK harness is fully accurate:
 
-- **String functions**: `toUpper()`, `toLower()` camelCase variants - Aliases for existing UPPER/LOWER functions
-- **Logical operators**: `XOR` - Exclusive OR with proper precedence (NOT > AND > XOR > OR) and NULL handling
-- **Arithmetic operators**: `^` (power/exponentiation) - Right-associative with full numeric support (negative and fractional exponents)
-- **List operations**: List slicing `[start..end]` and negative indexing `list[-1]` (already implemented, now documented)
-- **Comprehensive testing**: 79 new integration tests (18 string, 22 XOR, 39 power)
-- **Operator completion**: List operators 100% (5/5), Overall operators 94% (32/34, up from 88%)
-- **Function progress**: 56/72 functions (78%, up from 76%)
+- **Temporal correctness**: compact ISO 8601 formats, IANA timezone names, `TRUNCATE` units, duration arithmetic, map constructors — all fixed
+- **TCK harness**: integer/map literal coercion bugs fixed, eliminating ~450 false failures
+- **+813 net new passing TCK scenarios**: 2,507 passing (up from 1,694 at v0.3.5)
 
 **Previous Releases**:
+- **v0.3.5**: `sqrt()`, `rand()`, `pow()`, aggregation function fixes, 5 TCK step definitions (+129 scenarios)
+- **v0.3.4**: `toUpper()`/`toLower()` aliases, `XOR` operator, `^` power operator, list slicing docs
 - **v0.3.3**: Pattern comprehensions, CALL subqueries, Pattern predicates
 - **v0.3.2**: List operations (`filter()`, `extract()`, `reduce()`)
 - **v0.3.1**: Quantifier functions (`all()`, `any()`, `none()`, `single()`), `exists()`, `isEmpty()`
 - **v0.3.0**: OPTIONAL MATCH, UNION, List comprehensions, EXISTS/COUNT subqueries, Variable-length paths, 109+ datasets
 
-**TCK Coverage**: ~38% openCypher compatibility
+**TCK Coverage**: ~64% of collected scenarios passing (2,507 / 3,885)
 
 See [CHANGELOG.md](CHANGELOG.md) for complete release notes.
 
@@ -1369,7 +1367,9 @@ GraphForge implements a **practical subset of OpenCypher** focused on common gra
 
 **Functions:**
 - String: length, substring, toUpper/toLower (both camelCase and UPPERCASE variants), trim, reverse, split, replace, left, right, ltrim, rtrim
+- Math: abs, ceil, floor, round, sign, sqrt, rand, pow
 - Type conversion: toInteger, toFloat, toString, toBoolean
+- Aggregation: count, sum, avg, min, max, collect, percentileDisc, percentileCont, stDev, stDevP
 - Spatial: point, distance
 - Temporal: date, datetime, time, duration
 - Graph: id, labels, type
@@ -1414,6 +1414,7 @@ GraphForge tracks compliance using the openCypher Technology Compatibility Kit (
 | v0.1.4 | 1,277/7,722 | 16.5% |
 | v0.2.0 | ~1,900/7,722 | ~25% |
 | v0.3.0 | ~3,000/7,722 | ~39% |
+| v0.3.5 | 1,694/3,885 collected | ~44% collected |
 | v0.4.0 (target) | ~4,250/7,722 | ~55% |
 | v0.5.0 (target) | ~5,400/7,722 | ~70% |
 | v0.6.0 (target) | ~6,300/7,722 | ~82% |

{graphforge-0.3.5 → graphforge-0.3.6}/docs/development/testing.md

@@ -624,6 +624,71 @@ pip install -e ".[dev]"
 
 ---
 
+## Known Issues & Investigated Solutions
+
+### pytest-xdist + pytest-cov deadlock on macOS / Python 3.13
+
+**Symptom:** `make pre-push` (or any `pytest -n auto --cov=...` invocation) hangs
+indefinitely at the very end of the test run. Progress reaches ~100% then freezes.
+CPU drops to 0%. Only `kill` escapes it.
+
+**Root cause:** `pytest-cov` collects coverage data from xdist workers via IPC
+(inter-process communication sockets). When workers finish and close their sockets,
+a coverage data-collection thread in the main process is still blocked on `read()`.
+The main thread waits for that lock → deadlock. Confirmed via `sample <PID>`:
+```
+main thread: lock_PyThread_acquire_lock → _PyMutex_LockTimed → _PySemaphore_Wait
+worker thread: read() (44020 calls pending)
+```
+Reproduced consistently on macOS (Darwin 25.x) + Python 3.13.7 + pytest-cov 7.0.0 +
+pytest-xdist 3.x. Not observed on Linux CI.
+
+**What does NOT work:**
+
+| Attempted fix | Result |
+|---|---|
+| `--cov-report=html` alone | Still deadlocks; HTML is slow but not the cause |
+| `[tool.coverage.run] parallel = true` + `-n auto` | No deadlock but **2× slower** (3:54 vs 1:30) — per-process `.coverage.PID` file I/O overwhelms the speedup from parallelism |
+| `concurrency = ["multiprocessing", "thread"]` + `parallel = true` | Same outcome as above; requires `coverage combine` step which adds no benefit |
+
+**Solution (current `Makefile`):** Run coverage serially (no `-n auto`) and exclude
+the two other causes of slowdown:
+
+```makefile
+coverage:
+    uv run pytest tests/unit tests/integration -m "not snap" \
+        --cov=src \
+        --cov-branch \
+        --cov-report=term-missing \
+        --cov-report=xml
+```
+
+Key flags:
+- **No `-n auto`** — eliminates the IPC deadlock entirely.
+- **`-m "not snap"`** — skips SNAP network-dataset tests (they download files, run
+  alphabetically last, and are already skipped in CI per their marker description).
+- **No `--cov-report=html`** — HTML generation over ~13 k lines of source is slow;
+  use `make coverage-report` on demand instead.
+
+**Timing (Apple Silicon, Python 3.13, ~3 450 tests):**
+
+| Approach | Wall time |
+|---|---|
+| `-n auto`, no coverage (baseline) | ~91 s |
+| `-n auto` + `--cov` (original, pre-fix) | ∞ (deadlock) |
+| `-n auto` + `--cov` + `parallel=true` | ~234 s |
+| Serial `--cov`, `-m "not snap"`, no HTML (current) | ~150 s |
+
+The serial run is only ~60 s slower than the parallel baseline because coverage
+overhead is modest (~38 s) and `parallel=true` file-I/O costs more than it saves.
+
+**If this is re-investigated in the future:** the deadlock is a known upstream issue
+between pytest-cov and pytest-xdist on Python 3.13's stricter GIL/semaphore
+behaviour. Check the [pytest-cov changelog](https://pytest-cov.readthedocs.io/) for
+a fix before attempting another workaround.
+
+---
+
 ## Success Metrics
 
 The testing infrastructure is successful when:

{graphforge-0.3.5 → graphforge-0.3.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphforge"
-version = "0.3.5"
+version = "0.3.6"
 description = "Composable graph tooling for analysis, construction, and refinement"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -270,4 +270,5 @@ dev = [
     "bandit[toml]>=1.7.0",
     "pre-commit>=3.6.0",
     "types-defusedxml>=0.7.0.20250822",
+    "interrogate>=1.7.0",
 ]

{graphforge-0.3.5 → graphforge-0.3.6}/src/graphforge/api.py

@@ -257,10 +257,20 @@ class GraphForge:
         # Validate query input
         QueryInput(query=query)
 
-        # Parse query
+        # Parse query (may return a single CypherQuery or a list for multi-statement scripts)
         ast = self.parser.parse(query)
 
-        # Check if this is a UNION query
+        # Multi-statement script: execute each query sequentially, return last result
+        if isinstance(ast, list):
+            results: list[dict] = []
+            for single_ast in ast:
+                results = self._execute_single_ast(single_ast)
+            return results
+
+        return self._execute_single_ast(ast)
+
+    def _execute_single_ast(self, ast: Any) -> list[dict]:
+        """Execute a single parsed AST and return results."""
         from graphforge.ast.query import UnionQuery
 
         if isinstance(ast, UnionQuery):
@@ -290,10 +300,7 @@ class GraphForge:
                 self.optimizer.update_statistics(self.graph.get_statistics())
                 operators = self.optimizer.optimize(operators)
 
-        # Execute
-        results = self.executor.execute(operators)
-
-        return results
+        return self.executor.execute(operators)
 
     def create_node(self, labels: list[str] | None = None, **properties: Any) -> NodeRef:
         """Create a node with labels and properties.

{graphforge-0.3.5 → graphforge-0.3.6}/src/graphforge/ast/expression.py

@@ -451,3 +451,19 @@ class QuantifierExpression(BaseModel):
         return v
 
     model_config = {"frozen": True, "arbitrary_types_allowed": True}
+
+
+class LabelPredicate(BaseModel):
+    """Label membership predicate expression.
+
+    Represents ``n:Person``, ``n:Person:Employee`` (all labels must match), etc.
+
+    Examples:
+        WHERE n:Person               -> LabelPredicate(variable="n", labels=["Person"])
+        WHERE n:Person:Employee      -> LabelPredicate(variable="n", labels=["Person", "Employee"])
+    """
+
+    variable: str = Field(..., min_length=1, description="Variable name to test")
+    labels: list[str] = Field(..., min_length=1, description="Labels that must all be present")
+
+    model_config = {"frozen": True}

{graphforge-0.3.5 → graphforge-0.3.6}/src/graphforge/ast/pattern.py

@@ -57,11 +57,12 @@ class NodePattern(BaseModel):
 
     @field_validator("labels")
     @classmethod
-    def validate_labels(cls, v: list[str]) -> list[str]:
+    def validate_labels(cls, v: list[list[str]]) -> list[list[str]]:
         """Validate label names."""
-        for label in v:
-            if not label or not label[0].isalpha():
-                raise ValueError(f"Label must start with a letter: {label}")
+        for label_group in v:
+            for label in label_group:
+                if not label or not label[0].isalpha():
+                    raise ValueError(f"Label must start with a letter: {label}")
         return v
 
     model_config = {"frozen": True, "arbitrary_types_allowed": True}