graphforge 0.3.6__tar.gz → 0.3.8__tar.gz

{graphforge-0.3.6 → graphforge-0.3.8}/.github/workflows/changelog-check.yml

@@ -5,6 +5,10 @@ on:
     branches: [main]
     types: [opened, synchronize, reopened, labeled, unlabeled]
 
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   check-changelog:
     name: Verify CHANGELOG Updated

graphforge-0.3.8/.github/workflows/test.yml

@@ -0,0 +1,416 @@
+name: Test Suite
+
+on:
+  push:
+    branches: ["main", "develop"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download SNAP ego-facebook dataset
+        run: |
+          mkdir -p ~/.graphforge/datasets
+          curl -L -o ~/.graphforge/datasets/snap-ego-facebook.txt.gz https://snap.stanford.edu/data/facebook_combined.txt.gz
+        shell: bash
+
+      - name: Run unit tests
+        run: uv run pytest tests/unit -n auto --junitxml=test-results-unit.xml
+
+      - name: Run integration tests
+        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
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: test-results-unit.xml,test-results-integration.xml
+          flags: ${{ matrix.os }}-py${{ matrix.python-version }}
+          report_type: test_results
+          fail_ci_if_error: false
+
+  lint:
+    name: Lint and Format Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Check code formatting
+        run: uv run ruff format --check .
+
+      - name: Lint code
+        run: uv run ruff check .
+
+  type-check:
+    name: Type Checking (mypy)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run mypy type checker
+        run: uv run mypy src/graphforge --strict-optional --show-error-codes
+
+  security:
+    name: Security Scanning
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run bandit security scanner
+        run: uv run bandit -c pyproject.toml -r src/
+
+  tck-regression:
+    name: TCK Shard ${{ matrix.group }}/4
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        group: [1, 2, 3, 4]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Restore test durations cache
+        uses: actions/cache/restore@v4
+        with:
+          path: .test_durations
+          key: tck-durations-${{ github.ref }}
+          restore-keys: tck-durations-
+
+      - name: Run TCK shard ${{ matrix.group }}/4
+        id: tck_tests
+        continue-on-error: true
+        run: |
+          uv run pytest tests/tck/ -n auto \
+            --splits 4 --group ${{ matrix.group }} \
+            --splitting-algorithm duration_based_chunks \
+            --store-durations --durations-path=.test_durations_${{ matrix.group }} \
+            --junitxml=test-results-tck-${{ matrix.group }}.xml
+
+      - name: Upload shard results artifact
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: tck-shard-${{ matrix.group }}
+          path: |
+            test-results-tck-${{ matrix.group }}.xml
+            .test_durations_${{ matrix.group }}
+
+  tck-report:
+    name: TCK OpenCypher Compliance
+    runs-on: ubuntu-latest
+    needs: tck-regression
+    if: always()
+    permissions:
+      contents: read
+      actions: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: tck-shard-*
+          merge-multiple: true
+          path: tck-results/
+
+      - name: Merge JUnit XML results
+        run: |
+          uv run python3 -c "
+          import glob, sys
+          from xml.etree import ElementTree as ET
+
+          files = sorted(glob.glob('tck-results/test-results-tck-*.xml'))
+          if not files:
+              print('No shard result files found')
+              sys.exit(1)
+
+          root = ET.parse(files[0]).getroot()
+          suite = root if root.tag == 'testsuite' else root.find('testsuite')
+
+          for f in files[1:]:
+              tree = ET.parse(f).getroot()
+              src = tree if tree.tag == 'testsuite' else tree.find('testsuite')
+              for tc in src.findall('testcase'):
+                  suite.append(tc)
+
+          tests = len(suite.findall('testcase'))
+          failures = len(suite.findall('.//failure'))
+          errors = len(suite.findall('.//error'))
+          suite.set('tests', str(tests))
+          suite.set('failures', str(failures))
+          suite.set('errors', str(errors))
+
+          ET.ElementTree(root).write('test-results-tck.xml', xml_declaration=True, encoding='utf-8')
+          print(f'Merged {len(files)} shards: {tests} tests, {failures} failures')
+          "
+
+      - name: Merge test durations for future balancing
+        run: |
+          uv run python3 -c "
+          import glob, json
+          files = glob.glob('tck-results/.test_durations_*')
+          merged = {}
+          for f in files:
+              with open(f) as fh:
+                  merged.update(json.load(fh))
+          with open('.test_durations', 'w') as fh:
+              json.dump(merged, fh)
+          print(f'Merged durations for {len(merged)} tests from {len(files)} shards')
+          " || echo "No duration files found, skipping merge"
+
+      - name: Save test durations cache
+        uses: actions/cache/save@v4
+        if: always()
+        with:
+          path: .test_durations
+          key: tck-durations-${{ github.ref }}-${{ github.run_id }}
+
+      - name: Report TCK compliance metrics
+        if: always()
+        run: uv run python3 scripts/tck_metrics.py test-results-tck.xml
+
+      - name: Report TCK performance metrics
+        if: always()
+        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
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: test-results-tck.xml
+          flags: tck-compliance
+          report_type: test_results
+          fail_ci_if_error: false
+
+      - name: Upload merged TCK results artifact
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: tck-test-results
+          path: test-results-tck.xml
+
+  coverage-shard:
+    name: Coverage Shard ${{ matrix.group }}/4
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        group: [1, 2, 3, 4]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download SNAP ego-facebook dataset
+        run: |
+          mkdir -p ~/.graphforge/datasets
+          curl -L -o ~/.graphforge/datasets/snap-ego-facebook.txt.gz https://snap.stanford.edu/data/facebook_combined.txt.gz
+        shell: bash
+
+      - name: Run tests with coverage (shard ${{ matrix.group }}/4)
+        run: |
+          uv run pytest tests/unit tests/integration \
+            --splits 4 --group ${{ matrix.group }} \
+            --splitting-algorithm duration_based_chunks \
+            -n auto \
+            -m "not snap" \
+            --cov=src --cov-branch \
+            --cov-report=xml:coverage-${{ matrix.group }}.xml \
+            --junitxml=test-results-cov-${{ matrix.group }}.xml
+
+      - name: Upload coverage shard artifact
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-shard-${{ matrix.group }}
+          path: |
+            coverage-${{ matrix.group }}.xml
+            test-results-cov-${{ matrix.group }}.xml
+
+  coverage:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    needs: coverage-shard
+    if: always()
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Download all coverage shards
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-shard-*
+          merge-multiple: true
+          path: cov-results/
+
+      - name: Merge coverage reports
+        run: |
+          uv run python3 -c "
+          import glob, sys
+          from xml.etree import ElementTree as ET
+
+          files = sorted(glob.glob('cov-results/coverage-*.xml'))
+          if not files:
+              print('No coverage files found')
+              sys.exit(1)
+
+          base = ET.parse(files[0])
+          base_root = base.getroot()
+          base_packages = base_root.find('packages')
+
+          for f in files[1:]:
+              tree = ET.parse(f).getroot()
+              for pkg in tree.findall('.//package'):
+                  base_packages.append(pkg)
+
+          base.write('coverage.xml', xml_declaration=True, encoding='utf-8')
+          print(f'Merged {len(files)} coverage shards')
+          "
+
+      - 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"
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: full-coverage
+          name: codecov-full
+          fail_ci_if_error: false
+
+      - name: Upload test results to Codecov
+        uses: codecov/codecov-action@v5
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: cov-results/test-results-cov-*.xml
+          flags: full-suite
+          report_type: test_results
+          fail_ci_if_error: false
+
+      - name: Upload coverage artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

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

@@ -5,6 +5,80 @@ 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).
 
+## [Unreleased]
+
+## [0.3.8] - 2026-05-02
+
+### Fixed - TCK Feature Completeness (3885/3885 passing)
+- **Nanosecond precision in temporal types** — `CypherDateTime` and `CypherTime` now store a `_ns_residue` (0–999) for sub-microsecond precision; `_components` tuple extended to 8 elements with nanoseconds; construction, accessors, arithmetic, comparison, and serialization all updated (#224)
+- **Statement clock caching** — `now()`, `datetime()`, `date()`, `time()` (without arguments) now return consistent values within a single query by caching the start time via `time.time_ns()` (#224)
+- **Extreme year support** — dates/datetimes outside Python's 1–9999 range now handled via `_WideDate` / `_WideDateTime` classes; durations too large for `timedelta` use `_BigDuration`; Julian Day Number arithmetic for cross-extreme-year duration computation (#224)
+- **IANA timezone name preservation** — `CypherDateTime` stores the IANA zone name (e.g. `Europe/Stockholm`) separately; `.timezone` accessor returns the zone name rather than the numeric offset; `utcoffset()` now receives a concrete datetime for DST-aware lookup (#224)
+- **Aggregate detection in QuantifierExpression** — `ALL(ok IN collect(...) WHERE ok)` patterns now correctly detected as aggregate-containing; planner emits `Aggregate` instead of `Project` (#224)
+- **OPTIONAL MATCH multi-WHERE placement** — multiple `WHERE` clauses no longer overwrite each other; multi-hop OPTIONAL MATCH WHERE is emitted after all hops so all variables are bound (#224)
+- **`coalesce()` type inference** — return type is inferred from argument types so `MATCH (x)` after `WITH coalesce(a, b) AS x` accepts node-typed variables (#224)
+- **Non-deterministic aggregate arguments** — `count(rand())` and similar expressions now raise `AmbiguousAggregationExpression` per the openCypher spec (#224)
+- **Temporal accessor for extreme-year datetimes** — `year`, `month`, `day`, `hour`, `minute`, `second` accessors work on `_WideDateTime`-backed `CypherDateTime` values (#224)
+- **All 23 xfail markers removed** — previously marked as expected failures; all were fixable (#224)
+
+### Added
+- **75-test unit coverage for extreme temporal classes** — `tests/unit/types/test_extreme_temporal_values.py` covers `_WideDate`, `_WideDateTime`, `_BigDuration`, extreme-year construction/accessors, IANA timezone preservation, and large duration handling
+
+### Fixed
+- **WITH clause WHERE filtering and variable scoping** (#362) — `WITH n WHERE n.age > 30` now correctly filters post-projection; chained WITH propagates bindings properly
+- **Triadic OPTIONAL MATCH semantics** (#302 partial) — `OPTIONAL MATCH (a)-[r]->(b)` with pre-bound `b` now correctly filters to only edges reaching that specific destination (LEFT JOIN semantics)
+- **Relationship type disjunction without colon prefix** (#363) — `[:KNOWS|FOLLOWS]` (pipe without colon on subsequent types) now parses correctly
+- **Multi-CREATE variable scoping** (#364 partial) — variables created in one CREATE clause are now visible in subsequent CREATE clauses within the same query
+
+### Performance
+- **O(n²) → O(1) graph statistics updates** (#366) — `_update_statistics_after_add_edge` no longer scans all edges on every insert; replaced with incremental `_unique_sources_by_type` tracking. Eliminated 2,000+ Pydantic `model_copy()` calls per 1,000-node graph by switching to mutable counters with lazy `GraphStatistics` construction
+- **Parser fast path for long CREATE sequences** (#366) — queries with many consecutive CREATE clauses (e.g. the TCK movie graph with 971 CREATEs) are pre-split into batches of 5 before Earley parsing, reducing wall-clock time from 27 minutes to ~26 seconds. See docs/development/parser-performance-analysis.md for full analysis and the LALR(1) migration plan (issue #365)
+
+### CI
+- **TCK sharding across 4 parallel runners** — TCK tests now split using `pytest-split` with duration-based balancing (~4x faster CI)
+- **Coverage sharding** — coverage collection also split across 4 shards and merged in report job
+- **Python 3.14 experimental matrix** — added as non-blocking `continue-on-error` entries
+- **TCK performance reporting** — new `scripts/tck_perf_report.py` runs after each TCK run, reporting tests over 5s and tracking use-case tests (movie graph, school graph) for performance regression detection
+
+### TCK Coverage
+- **3,885 / 3,885 passing (100%)** — first release with zero TCK failures and zero expected failures
+
+## [0.3.7] - 2026-04-07
+
+### Added - Functions
+- **Math functions: e, pi, exp, log, log10, trig, degrees, radians, timestamp** (#326) — full set of mathematical and trigonometric functions per openCypher spec
+- **`startNode()` and `endNode()` graph functions** (#318) — extract the start/end node from a relationship
+- **`properties()` and `keys()` graph functions** (#316) — inspect node/relationship property maps and key sets
+- **List concatenation `+` operator** (#315) — `[1,2] + [3,4]` → `[1,2,3,4]`
+- **Map subscript access `m['key']`** (#314) — dynamic map property lookup
+- **Exponent float notation and leading-dot floats** (#311) — `1.5e3`, `.5` now parsed correctly
+
+### Fixed - Sorting & Aggregation
+- **ORDER BY mixed-type sort ordering** (#320) — values of different Cypher types now sort in the correct openCypher type hierarchy order
+- **Aggregation in composite expressions and ORDER BY** (#329) — `count(n) + 1`, `ORDER BY count(n)` and similar patterns now evaluate correctly
+- **Validate ORDER BY aggregation expressions at compile time** (#331) — non-aggregated variables in aggregating ORDER BY now raise a clear error
+- **Detect non-projected ORDER BY aggregates at compile time** (#332) — aggregates in ORDER BY that aren't in the projection are caught early
+
+### Fixed - Expression Evaluation
+- **Operator precedence, null propagation, and type coercion** (#321) — `NOT`, `AND`, `OR` precedence; null propagation in arithmetic; integer/float coercion edge cases
+- **Type conversion TypeError/null per openCypher spec** (#327) — `toInteger()`, `toFloat()`, `toString()` now return `null` on unconvertible input per spec
+- **List equality with null uses three-valued logic** (#330) — `[1, null] = [1, null]` now correctly returns `null`
+- **NaN handling in comparisons, arithmetic, and sort** (#323) — NaN propagation and sort position per openCypher spec
+- **SKIP/LIMIT accept expression values** (#319) — `SKIP toInteger(n.offset)` and similar dynamic skip/limit values now work
+
+### Fixed - Parser & Clause Gaps
+- **WITH keyword position gaps** (#310) — `WITH` is now accepted after `SET`, `REMOVE`, `DELETE`, and in chained multi-part queries
+- **ASCENDING/DESCENDING keywords** (#312) — `ORDER BY n.name ASCENDING` / `DESCENDING` now parse correctly; removed stale xfail markers (#325)
+- **`NodeRef`/`EdgeRef` comparison methods** (#313) — nodes and relationships are now sortable and comparable by identity
+
+### Fixed - Graph Semantics
+- **Relationship uniqueness in MATCH patterns** (#333) — runtime enforcement that the same physical edge cannot fill two relationship variables in one MATCH pattern; extended to anonymous multi-hop rels and path-variable (`ExpandMultiHop`) patterns
+- **Temporal select-into constructors** (#334) — cross-type temporal projection (`date({date: other})`, `localdatetime({datetime: dt})`, etc.) with component overrides; null propagation, hour-overflow normalization, and timezone conversion all correct
+
+### TCK Coverage
+- **3,235 / 3,885 passing (83.3%)** (up from ~2,507 at v0.3.6) — +728 net new passing scenarios
+- Theme: ORDER BY correctness, aggregation, operator precedence, graph semantics, temporal completeness
+
 ## [0.3.6] - 2026-02-28
 
 ### Fixed - TCK Harness Correctness