tests: tag targettable xfails (#3)

* tests: tag targettable xfails

* tools: add porting backlog report

* test: add placeholder gfql plans for return ordering/skip

* test: add placeholder gfql plans for orderby/limit cases

* test: auto-placehold target extension xfails

* test: generate clause plans for target xfails

* test: generate expr-aware plans for target xfails

* test: extend target expr coverage for map/type conversion

* docs: add changelog

* docs: align changelog template

* docs: add develop guide and release entry

Author: lmeyerov

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to the tck-gfql project are documented in this file. The PyGraphistry client and other Graphistry components are tracked in the main [Graphistry major release history documentation](https://graphistry.zendesk.com/hc/en-us/articles/360033184174-Enterprise-Release-List-Downloads).
+
+The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and all breaking changes are explictly noted here.
+
+## [Development]
+<!-- Do Not Erase This Section - Used for tracking unreleased changes -->
+
+### Added
+- None.
+
+### Changed
+- None.
+
+## [0.1.0 - 2026-01-03]
+
+### Added
+- **GFQL plans**: Auto-generate clause + expression plans for target extension xfail scenarios (table ops + expr DSL).
+- **GFQL plan DSL**: Added expression AST helpers (`col`, `lit`, `param`, `func`, `binary`, `unary`, `list`, `map`, `index`, `star`) for non-executable plan capture.
+- **Docs**: Documented generated xfail plans and plan helpers in `tests/cypher_tck/README.md`.
+
+### Changed
+- **GFQL plan generation**: Expanded target expr coverage to include map and type conversion buckets.

DEVELOP.md

@@ -0,0 +1,48 @@
+# Development Setup
+
+See also [CONTRIBUTING.md](CONTRIBUTING.md) (if/when added) and the project README.
+
+This repo focuses on the openCypher TCK conformance harness for GFQL and uses
+the local `plans/` clone of the TCK repo for reference (not vendored).
+
+## Local Tests
+
+```bash
+pytest tests/cypher_tck -xvs
+TEST_CUDF=1 pytest tests/cypher_tck -xvs
+```
+
+When running from a sibling `pygraphistry` checkout, set:
+
+```bash
+PYTHONPATH=/path/to/pygraphistry python -m tests.cypher_tck.porting_backlog
+```
+
+## CI
+
+GitHub Actions runs the suite on PRs. See `.github/workflows`.
+
+## Publish: Merge, Tag, & Release
+
+1. Update `CHANGELOG.md` in your PR branch
+   - Move changes from `## [Development]` into a dated release section (e.g., `## [0.1.0 - YYYY-MM-DD]`).
+   - Keep `## [Development]` with empty headings.
+
+2. Merge the PR to `main` (via GitHub UI or `gh pr merge`).
+
+3. Switch to `main` and pull the merged changes:
+   ```bash
+   git checkout main
+   git pull
+   ```
+
+4. Tag the repository with the new version number (semantic versioning):
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+5. Create a GitHub Release with notes from the changelog:
+   ```bash
+   gh release create vX.Y.Z --title "vX.Y.Z" --notes "See CHANGELOG.md for details."
+   ```

tests/cypher_tck/GAP_ANALYSIS.md

@@ -9,6 +9,8 @@ translation guidelines.
 - If a scenario is marked skip/xfail, add or reference a gap entry below.
 - Keep the entry short, with a clear root cause and a proposed path forward.
 - Update the entry when the gap is partially or fully addressed.
+- Targettable capability tags (e.g., `target-table-ops`, `target-expr-dsl`) are
+  auto-applied to xfail scenarios by feature path for tracking near-term work.
 
 ## Entry format
 - **ID**: Short identifier (G1, G2, ...)

tests/cypher_tck/README.md

@@ -21,15 +21,28 @@ optional cuDF runs when enabled.
   - `engine='cudf'` (only when `TEST_CUDF=1` and cudf is available)
 - Record unsupported scenarios with explicit xfail/skip reasons and capability tags.
 - Preserve traceability to the original Cypher query and expected results.
+  - Capability tags include `target-table-ops`, `target-expr-dsl`, `defer-quantifier`,
+    `defer-path-enum`, `defer-unwind`, `defer-union`.
 
 ## Running
 ```bash
 pytest tests/cypher_tck -xvs
 TEST_CUDF=1 pytest tests/cypher_tck -xvs
 ```
 
+## Porting backlog
+```bash
+PYGRAPHISTRY_PATH=/path/to/pygraphistry python -m tests.cypher_tck.porting_backlog
+python -m tests.cypher_tck.porting_backlog
+BACKLOG_LIMIT=20 python -m tests.cypher_tck.porting_backlog
+```
+
 ## Notes
 - The TCK repo is not vendored; use the local clone under `plans/`.
 - Each translated scenario should include a reference back to the TCK path,
   the original Cypher, and the expected rows or aggregates.
+- For xfail scenarios, `gfql` may contain a non-executable plan built with
+  `tests.cypher_tck.gfql_plan` to document the intended translation. When a
+  target-table-ops or target-expr-dsl scenario lacks a manual plan, a minimal
+  clause-based plan is generated from the Cypher text at load time.
 - Track feature gaps and workarounds in `tests/cypher_tck/GAP_ANALYSIS.md`.

tests/cypher_tck/gfql_plan.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class PlanStep:
+    op: str
+    args: Dict[str, Any]
+
+
+@dataclass(frozen=True)
+class Expr:
+    op: str
+    args: Dict[str, Any]
+
+
+def step(op: str, **kwargs: Any) -> PlanStep:
+    return PlanStep(op=op, args=kwargs)
+
+
+def expr(op: str, **kwargs: Any) -> Expr:
+    return Expr(op=op, args=kwargs)
+
+
+def col(name: str) -> Expr:
+    return expr("col", name=name)
+
+
+def lit(value: Any) -> Expr:
+    return expr("lit", value=value)
+
+
+def param(name: str) -> Expr:
+    return expr("param", name=name)
+
+
+def func(name: str, args: Iterable[Any]) -> Expr:
+    return expr("func", name=name, args=tuple(args))
+
+
+def unary(op: str, value: Any) -> Expr:
+    return expr("unary", op=op, value=value)
+
+
+def binary(op: str, left: Any, right: Any) -> Expr:
+    return expr("binary", op=op, left=left, right=right)
+
+
+def list_(items: Iterable[Any]) -> Expr:
+    return expr("list", items=tuple(items))
+
+
+def map_(items: Iterable[Tuple[str, Any]]) -> Expr:
+    return expr("map", items=tuple(items))
+
+
+def index(base: Any, key: Any) -> Expr:
+    return expr("index", base=base, key=key)
+
+
+def star() -> Expr:
+    return expr("star")
+
+
+def raw(text: str) -> Expr:
+    return expr("raw", text=text)
+
+
+def distinct_expr(value: Any) -> Expr:
+    return expr("distinct", value=value)
+
+
+def plan(*steps: PlanStep) -> Tuple[PlanStep, ...]:
+    return steps
+
+
+def match(*chain: Any) -> PlanStep:
+    return step("match", chain=chain)
+
+
+def rows(table: str, source: Optional[str] = None) -> PlanStep:
+    args: Dict[str, Any] = {"table": table}
+    if source is not None:
+        args["source"] = source
+    return step("rows", **args)
+
+
+def select(items: Iterable[Tuple[str, Any]]) -> PlanStep:
+    return step("select", items=tuple(items))
+
+
+def order_by(keys: Iterable[Tuple[str, Any]]) -> PlanStep:
+    return step("order_by", keys=tuple(keys))
+
+
+def skip(value: Any) -> PlanStep:
+    return step("skip", value=value)
+
+
+def limit(value: Any) -> PlanStep:
+    return step("limit", value=value)
+
+
+def distinct() -> PlanStep:
+    return step("distinct")
+
+
+def group_by(keys: Iterable[Any]) -> PlanStep:
+    return step("group_by", keys=tuple(keys))

tests/cypher_tck/porting_backlog.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import os
+import sys
+from collections import Counter
+from typing import Iterable, List
+
+from tests.cypher_tck.models import Scenario
+
+_PYGRAPHISTRY_PATH = os.environ.get("PYGRAPHISTRY_PATH")
+if _PYGRAPHISTRY_PATH and _PYGRAPHISTRY_PATH not in sys.path:
+    sys.path.insert(0, _PYGRAPHISTRY_PATH)
+
+try:
+    from tests.cypher_tck.scenarios import SCENARIOS
+except ModuleNotFoundError as exc:  # pragma: no cover - import-time guard
+    if exc.name == "graphistry":
+        raise SystemExit(
+            "graphistry is required to import scenario modules. "
+            "Set PYGRAPHISTRY_PATH=/path/to/pygraphistry or install graphistry."
+        ) from exc
+    raise
+
+
+TARGET_TAGS = (
+    "target-table-ops",
+    "target-expr-dsl",
+)
+
+DEFER_TAGS = (
+    "defer-quantifier",
+    "defer-path-enum",
+    "defer-expr-advanced",
+    "defer-unwind",
+    "defer-union",
+)
+
+
+def _filter_target(scenarios: Iterable[Scenario], tag: str) -> List[Scenario]:
+    return [
+        scenario
+        for scenario in scenarios
+        if scenario.status == "xfail"
+        and scenario.gfql is None
+        and tag in scenario.tags
+    ]
+
+
+def _print_bucket(title: str, scenarios: List[Scenario], limit: int) -> None:
+    print(f"{title}: {len(scenarios)}")
+    for scenario in scenarios[:limit]:
+        print(f"- {scenario.key} | {scenario.feature_path} | {scenario.scenario}")
+    if len(scenarios) > limit:
+        print(f"- ... {len(scenarios) - limit} more")
+
+
+def main() -> None:
+    limit = int(os.environ.get("BACKLOG_LIMIT", "40"))
+    scenarios = list(SCENARIOS)
+
+    print("GFQL porting backlog (xfail + gfql missing)")
+    print("Target tags:", ", ".join(TARGET_TAGS))
+    print("Defer tags:", ", ".join(DEFER_TAGS))
+    print()
+
+    tag_counts = Counter()
+    for scenario in scenarios:
+        if scenario.status != "xfail" or scenario.gfql is not None:
+            continue
+        tag_counts.update(scenario.tags)
+
+    print("Top tag counts (xfail + gfql missing):")
+    for tag, count in tag_counts.most_common(12):
+        print(f"- {tag}: {count}")
+    print()
+
+    for tag in TARGET_TAGS:
+        tagged = _filter_target(scenarios, tag)
+        tagged.sort(key=lambda s: (s.feature_path, s.key))
+        _print_bucket(f"Backlog for {tag}", tagged, limit)
+        print()
+
+
+if __name__ == "__main__":
+    main()