feat(tck): coverage matrix + rust_status tracking with CI enforcement

[DecisionNerd]

Summary

Stands up the instrument that tracks openCypher TCK conformance toward the #609 100%-of-corpus
bar — enforced by the existing BDD — Rust CI gate (no new CI job).

Closes #608. Part of M17.

What

• tests/tck/coverage_matrix.json — per-feature rust_status (passing|skip) + written-scenario
  counts over the vendored openCypher 2024.3 corpus: 220 features; 1,615 authored Scenario/Outline blocks expanding to 3,880 runnable
  scenarios (the gate denominator); 6 passing (Literals1) today.
• crates/gf-api/tests/tck_coverage.rs — asserts the matrix stays in sync with the @skip-rust
  tags and covers every feature exactly once. With the BDD suite's fail_on_skipped, this gives the
  invariant rust_status == "passing" ⟹ the feature runs and passes.
• docs/reference/tck-compliance.md — rewritten for the Rust v0.5 core: the 3,880-scenario corpus
  denominator, the supported-subset / documented-xfail definition, the revived regression-floor
  policy, and how to un-skip a tier. Replaces the stale v0.3.9 Python report.

Validation

cargo test -p gf-api --test tck_coverage green; cargo fmt --all -- --check clean. Data + test +
docs only — no engine changes.

Effect

The TCK passing rate is now tracked + CI-enforced: a feature can't be marked passing without actually
running, can't run without passing, and can't silently regress to skip. Today: 6 / 3,880; the
matrix grows as tiers (#598–#601) and the feature cluster land.

🤖 Generated with Claude Code

Note

Add TCK coverage matrix with CI enforcement for Rust status tracking

• Adds coverage_matrix.json, a generated JSON file mapping each openCypher TCK feature file to its rust_status (skip or passing) and expanded scenario count.
• Adds tck_coverage.rs, a CI test that validates the matrix stays in sync with vendored .feature files — failing if any feature is missing, extra, has a mismatched scenario count, or has a rust_status inconsistent with its @skip-rust tag.
• Adds tck-compliance.md describing the TCK corpus, the 100% gate definition, current status, and instructions for regenerating the matrix.
• Risk: any change to vendored TCK feature files or their @skip-rust tags will break CI until the coverage matrix is regenerated and committed.

^{Macroscope summarized e34d1cb.}

Summary by CodeRabbit

• Tests
  • Added a TCK coverage validation that checks the coverage matrix stays in sync with the vendored feature files.
  • Validates rust_status based on presence of the @skip-rust tag and recalculates expected scenario counts from the feature text.
  • Ensures the coverage matrix contains no missing or extra feature entries.

[coderabbitai]

Walkthrough

Adds tests/tck/coverage_matrix.json populated with the full openCypher TCK 2024.3 corpus (~891 lines), marking one feature as passing and all others as skip. Adds a Rust test in crates/gf-api/tests/tck_coverage.rs that discovers .feature files, extracts @skip-rust tags and scenario counts, and asserts the JSON matrix is consistent with those values.

Changes

TCK Coverage Matrix and Validation Test

Layer / File(s)	Summary
Test infrastructure and helper functions crates/gf-api/tests/tck_coverage.rs	Provides crate documentation of the rust_status ↔ @skip-rust invariant, workspace_root() for canonical path resolution, expanded_scenarios() for counting runnable scenarios per feature (1 per Scenario, 1 per data row in Scenario Outline/Examples blocks), and collect_features() for recursive .feature discovery with tag detection and normalized relative-path keys.
Matrix validation test crates/gf-api/tests/tck_coverage.rs	Adds coverage_matrix_matches_feature_tags test that orchestrates feature discovery, loads/parses coverage_matrix.json, verifies the feature keys match exactly, and asserts rust_status alignment and scenario count correctness for each entry.
Coverage matrix data tests/tck/coverage_matrix.json	Populates the full openCypher 2024.3 TCK coverage matrix with _meta (corpus counts, tagging conventions) and a complete features map with per-entry rust_status and scenarios; Literals1.feature is marked passing, all other ~150 features are marked skip.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• tck: rust_status tracking in BDD runner and CI enforcement #608 — This PR directly implements the core exit criteria: coverage_matrix.json with rust_status for all feature groups and a CI-enforced regression-floor test that fails if a previously-passing scenario is skipped.
• Milestone 17 gate: TCK threshold met, fuzzing clean, provenance rules stable #609 — The matrix validation test added here is listed as a Milestone 17 gate exit criterion ("TCK coverage_matrix.json rust_status field CI-enforced (#608)").
• tck: MATCH/WHERE/RETURN core subset passing on Rust core #598 — Updates to rust_status from "skip" → "passing" as MATCH/WHERE/RETURN features are implemented will directly exercise and validate this test and matrix.

Possibly related PRs

• DecisionNerd/graphforge#887: Un-skips Literals1.feature by removing @skip-rust, which directly determines the passing entry this PR's validation test enforces against coverage_matrix.json.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: establishing a TCK coverage matrix with Rust status tracking and CI enforcement.
Linked Issues check	✅ Passed	The PR fully addresses issue #608's requirements: coverage_matrix.json tracks all features with rust_status, tck_coverage.rs validates consistency and scenario counts, and both data and test are included.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to establishing TCK coverage tracking: a validation test, the matrix data file, and documentation updates. No unrelated modifications present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The PR description comprehensively addresses the pull request template with clear summaries, issue references, validation details, and context about TCK compliance tracking and CI enforcement.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/608-tck-coverage-matrix

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

crates/gf-api/tests/tck_coverage.rs (1)

70-106: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Also validate _meta aggregate fields to prevent silent drift.

The test verifies per-feature entries, but it does not assert _meta.feature_files, _meta.scenarios_written, and _meta.scenarios_passing against derived totals. Adding these checks keeps the summary metadata trustworthy.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/gf-api/tests/tck_coverage.rs` around lines 70 - 106, The test
currently validates individual feature entries but does not assert the aggregate
metadata fields in the _meta object (feature_files, scenarios_written, and
scenarios_passing) against the derived totals from the actual feature files.
After the existing validation loop that checks per-feature entries, add
assertions that verify _meta.feature_files equals the count of keys in actual,
_meta.scenarios_written equals the sum of all scenario counts across actual
entries, and _meta.scenarios_passing equals the sum of scenario counts only for
entries where skipped is false. This prevents the summary metadata from drifting
silently.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/gf-api/tests/tck_coverage.rs`:
- Around line 34-37: The substring matching in the closure of the `any()` method
call is too permissive and will match partial tags like `@skip-rust-foo` instead
of just the exact `@skip-rust` tag. Replace the `contains("skip-rust")` check
with exact tag matching by verifying that `@skip-rust` appears as a complete
word boundary (either followed by whitespace or at the end of the string) rather
than as a substring. This ensures only the exact `@skip-rust` tag triggers the
skip condition.

---

Nitpick comments:
In `@crates/gf-api/tests/tck_coverage.rs`:
- Around line 70-106: The test currently validates individual feature entries
but does not assert the aggregate metadata fields in the _meta object
(feature_files, scenarios_written, and scenarios_passing) against the derived
totals from the actual feature files. After the existing validation loop that
checks per-feature entries, add assertions that verify _meta.feature_files
equals the count of keys in actual, _meta.scenarios_written equals the sum of
all scenario counts across actual entries, and _meta.scenarios_passing equals
the sum of scenario counts only for entries where skipped is false. This
prevents the summary metadata from drifting silently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 69334aca-40c1-40c1-95ad-822ebaf90f18

📥 Commits

Reviewing files that changed from the base of the PR and between 9d615e7 and f55798f.

⛔ Files ignored due to path filters (1)

• docs/reference/tck-compliance.md is excluded by !**/*.md, !**/docs/**

📒 Files selected for processing (2)

• crates/gf-api/tests/tck_coverage.rs
• tests/tck/coverage_matrix.json