Merge remote-tracking branch 'upstream/main' into query-v2

# Conflicts:
#	.gitignore
#	README.md
#	cmd/benchmark/README.md
#	cmd/benchmark/main.go
#	cmd/benchmark/report_test.go
#	cmd/benchmark/runner.go

Author: zinic

.gitignore

@@ -9,3 +9,6 @@ integration/testdata/local/
 
 # Local benchmark comparison output
 .bench/
+
+# Local test and metric artifacts
+.coverage/

Makefile

@@ -12,6 +12,51 @@ BENCH_KIND ?= all
 
 # Main packages to test/build
 MAIN_PACKAGES := $(shell $(GO_CMD) list ./...)
+COVERPKG := $(shell $(GO_CMD) list ./... | grep -v '/cypher/parser$$' | tr '\n' ',' | sed 's/,$$//')
+
+# Metric configuration
+METRICS_DIR ?= .coverage
+COVERAGE_PROFILE ?= $(METRICS_DIR)/unit.out
+COVERAGE_FUNC_REPORT ?= $(METRICS_DIR)/coverage.txt
+CYCLO_REPORT ?= $(METRICS_DIR)/cyclomatic.txt
+CRAP_TEXT_REPORT ?= $(METRICS_DIR)/crap.txt
+CRAP_JSON_REPORT ?= $(METRICS_DIR)/crap.json
+QUALITY_TEXT_REPORT ?= $(METRICS_DIR)/quality.txt
+QUALITY_JSON_REPORT ?= $(METRICS_DIR)/quality.json
+METRICS_HTML_REPORT ?= $(METRICS_DIR)/metrics.html
+METRICS_IGNORE ?= (^|/)(testdata|vendor)/|_test\.go$$|^cypher/parser/
+CYCLO_TOP ?= 20
+CYCLO_OVER ?= 25
+CRAP_TOP ?= 20
+CRAP_OVER ?= 30
+METRICS_ENFORCE ?= 0
+BENCHMARK_REPORT ?=
+BENCHMARK_BASELINE ?=
+BENCHMARK_REGRESSION ?= 0.20
+FUZZ_REPORT ?=
+MUTATION_REPORT ?=
+BACKEND_RESULT_ARGS ?=
+BACKEND_PG_REPORT ?= $(METRICS_DIR)/integration-pg.json
+BACKEND_NEO4J_REPORT ?= $(METRICS_DIR)/integration-neo4j.json
+QUALITY_BENCHMARK_REPORT ?= $(METRICS_DIR)/benchmark.json
+QUALITY_BENCHMARK_MARKDOWN ?= $(METRICS_DIR)/benchmark.md
+
+QUALITY_INPUTS := $(BACKEND_RESULT_ARGS)
+ifneq ($(strip $(BENCHMARK_REPORT)),)
+QUALITY_INPUTS += -benchmark-report $(BENCHMARK_REPORT)
+endif
+ifneq ($(strip $(BENCHMARK_BASELINE)),)
+QUALITY_INPUTS += -benchmark-baseline $(BENCHMARK_BASELINE)
+endif
+ifneq ($(strip $(FUZZ_REPORT)),)
+QUALITY_INPUTS += -fuzz-report $(FUZZ_REPORT)
+endif
+ifneq ($(strip $(MUTATION_REPORT)),)
+QUALITY_INPUTS += -mutation-report $(MUTATION_REPORT)
+endif
+QUALITY_INPUTS += -benchmark-regression $(BENCHMARK_REGRESSION)
+
+.PHONY: default all build deps tidy lint format test test_all test_integration test_neo4j test_pg test_update complexity complexity_check crap crap_check quality quality_check quality_backend quality_bench metrics metrics_check generate clean help
 
 # Default target
 default: help
@@ -41,9 +86,11 @@ format:
 	@find ./ -name '*.go' -print0 | xargs -P 12 -0 -I '{}' goimports -w '{}'
 
 # Test targets
-test:
+test: $(METRICS_DIR)
 	@echo "Running tests..."
-	@$(GO_CMD) test -race -cover -count=1 -parallel=10 $(MAIN_PACKAGES)
+	@$(GO_CMD) test -race -covermode=atomic -coverprofile=$(COVERAGE_PROFILE) -coverpkg=$(COVERPKG) -count=1 -parallel=10 $(MAIN_PACKAGES)
+	@$(GO_CMD) tool cover -func=$(COVERAGE_PROFILE) > $(COVERAGE_FUNC_REPORT)
+	@echo "Coverage report written to $(COVERAGE_FUNC_REPORT)"
 
 test_all: test test_integration
 
@@ -76,6 +123,78 @@ test_update:
 	@cp -fv cypher/models/pgsql/test/updated_cases/* cypher/models/pgsql/test/translation_cases
 	@rm -rf cypher/models/pgsql/test/updated_cases
 
+# Metric targets
+$(METRICS_DIR):
+	@mkdir -p $(METRICS_DIR)
+
+complexity: $(METRICS_DIR)
+	@echo "Measuring cyclomatic complexity..."
+	@$(GO_CMD) tool gocyclo -top $(CYCLO_TOP) -ignore '$(METRICS_IGNORE)' . | tee $(CYCLO_REPORT)
+	@echo "Cyclomatic complexity report written to $(CYCLO_REPORT)"
+
+complexity_check: $(METRICS_DIR)
+	@echo "Checking cyclomatic complexity..."
+	@if [ "$(METRICS_ENFORCE)" = "1" ]; then \
+		$(GO_CMD) tool gocyclo -over $(CYCLO_OVER) -ignore '$(METRICS_IGNORE)' . | tee $(CYCLO_REPORT); \
+	else \
+		$(GO_CMD) tool gocyclo -top $(CYCLO_TOP) -ignore '$(METRICS_IGNORE)' . | tee $(CYCLO_REPORT); \
+		echo "METRICS_ENFORCE=0; cyclomatic complexity threshold $(CYCLO_OVER) is report-only."; \
+	fi
+
+crap: test
+	@echo "Calculating CRAP metrics..."
+	@$(GO_CMD) tool dawgs-metrics -source-root . -coverprofile $(COVERAGE_PROFILE) -ignore '$(METRICS_IGNORE)' -top $(CRAP_TOP) -over $(CRAP_OVER) -cyclo-over $(CYCLO_OVER) $(QUALITY_INPUTS) -text $(CRAP_TEXT_REPORT) -json $(CRAP_JSON_REPORT) -quality-text $(QUALITY_TEXT_REPORT) -quality-json $(QUALITY_JSON_REPORT) -html $(METRICS_HTML_REPORT)
+	@echo "CRAP and quality reports written to $(CRAP_TEXT_REPORT), $(CRAP_JSON_REPORT), $(QUALITY_TEXT_REPORT), $(QUALITY_JSON_REPORT), and $(METRICS_HTML_REPORT)"
+
+crap_check: test
+	@echo "Checking CRAP metrics..."
+	@if [ "$(METRICS_ENFORCE)" = "1" ]; then \
+		$(GO_CMD) tool dawgs-metrics -source-root . -coverprofile $(COVERAGE_PROFILE) -ignore '$(METRICS_IGNORE)' -top $(CRAP_TOP) -over $(CRAP_OVER) -cyclo-over $(CYCLO_OVER) $(QUALITY_INPUTS) -text $(CRAP_TEXT_REPORT) -json $(CRAP_JSON_REPORT) -quality-text $(QUALITY_TEXT_REPORT) -quality-json $(QUALITY_JSON_REPORT) -html $(METRICS_HTML_REPORT) -fail-over $(CRAP_OVER) -fail-quality; \
+	else \
+		$(GO_CMD) tool dawgs-metrics -source-root . -coverprofile $(COVERAGE_PROFILE) -ignore '$(METRICS_IGNORE)' -top $(CRAP_TOP) -over $(CRAP_OVER) -cyclo-over $(CYCLO_OVER) $(QUALITY_INPUTS) -text $(CRAP_TEXT_REPORT) -json $(CRAP_JSON_REPORT) -quality-text $(QUALITY_TEXT_REPORT) -quality-json $(QUALITY_JSON_REPORT) -html $(METRICS_HTML_REPORT); \
+		echo "METRICS_ENFORCE=0; CRAP threshold $(CRAP_OVER) is report-only."; \
+	fi
+
+quality: test
+	@echo "Calculating quality metrics..."
+	@$(GO_CMD) tool dawgs-metrics -source-root . -coverprofile $(COVERAGE_PROFILE) -ignore '$(METRICS_IGNORE)' -top $(CRAP_TOP) -over $(CRAP_OVER) -cyclo-over $(CYCLO_OVER) $(QUALITY_INPUTS) -quality-text $(QUALITY_TEXT_REPORT) -quality-json $(QUALITY_JSON_REPORT) -html $(METRICS_HTML_REPORT) -stdout=false
+	@echo "Quality reports written to $(QUALITY_TEXT_REPORT), $(QUALITY_JSON_REPORT), and $(METRICS_HTML_REPORT)"
+
+quality_check: test
+	@echo "Checking quality metrics..."
+	@if [ "$(METRICS_ENFORCE)" = "1" ]; then \
+		$(GO_CMD) tool dawgs-metrics -source-root . -coverprofile $(COVERAGE_PROFILE) -ignore '$(METRICS_IGNORE)' -top $(CRAP_TOP) -over $(CRAP_OVER) -cyclo-over $(CYCLO_OVER) $(QUALITY_INPUTS) -quality-text $(QUALITY_TEXT_REPORT) -quality-json $(QUALITY_JSON_REPORT) -html $(METRICS_HTML_REPORT) -stdout=false -fail-quality; \
+	else \
+		$(GO_CMD) tool dawgs-metrics -source-root . -coverprofile $(COVERAGE_PROFILE) -ignore '$(METRICS_IGNORE)' -top $(CRAP_TOP) -over $(CRAP_OVER) -cyclo-over $(CYCLO_OVER) $(QUALITY_INPUTS) -quality-text $(QUALITY_TEXT_REPORT) -quality-json $(QUALITY_JSON_REPORT) -html $(METRICS_HTML_REPORT) -stdout=false; \
+		echo "METRICS_ENFORCE=0; quality watch signals are report-only."; \
+	fi
+
+quality_backend: test
+	@echo "Running backend equivalence test captures..."
+	@if [ -z "$(PG_CONNECTION_STRING)" ] || [ -z "$(NEO4J_CONNECTION_STRING)" ]; then \
+		echo "PG_CONNECTION_STRING and NEO4J_CONNECTION_STRING are required."; \
+		exit 1; \
+	fi
+	@set +e; \
+	CONNECTION_STRING="$(PG_CONNECTION_STRING)" $(GO_CMD) test -json -tags 'manual_integration integration' -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES) > $(BACKEND_PG_REPORT); \
+	pg_status=$$?; \
+	CONNECTION_STRING="$(NEO4J_CONNECTION_STRING)" $(GO_CMD) test -json -tags 'manual_integration integration' -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES) > $(BACKEND_NEO4J_REPORT); \
+	neo4j_status=$$?; \
+	set -e; \
+	$(GO_CMD) tool dawgs-metrics -source-root . -coverprofile $(COVERAGE_PROFILE) -ignore '$(METRICS_IGNORE)' -top $(CRAP_TOP) -over $(CRAP_OVER) -cyclo-over $(CYCLO_OVER) -backend-result pg=$(BACKEND_PG_REPORT) -backend-result neo4j=$(BACKEND_NEO4J_REPORT) $(QUALITY_INPUTS) -quality-text $(QUALITY_TEXT_REPORT) -quality-json $(QUALITY_JSON_REPORT) -html $(METRICS_HTML_REPORT) -stdout=false; \
+	if [ $$pg_status -ne 0 ]; then exit $$pg_status; fi; \
+	if [ $$neo4j_status -ne 0 ]; then exit $$neo4j_status; fi
+
+quality_bench: $(METRICS_DIR)
+	@echo "Running benchmark capture..."
+	@$(GO_CMD) run ./cmd/benchmark -output $(QUALITY_BENCHMARK_MARKDOWN) -json-output $(QUALITY_BENCHMARK_REPORT)
+	@echo "Benchmark reports written to $(QUALITY_BENCHMARK_MARKDOWN) and $(QUALITY_BENCHMARK_REPORT)"
+
+metrics: complexity crap
+
+metrics_check: METRICS_ENFORCE = 1
+metrics_check: complexity_check crap_check
+
 # Utility targets
 generate:
 	@echo "Running code generation..."
@@ -87,6 +206,7 @@ clean:
 
 	@rm -rf cypher/analyzer/updated_cases/
 	@rm -rf cypher/models/pgsql/test/updated_cases
+	@rm -rf $(METRICS_DIR)
 
 help:
 	@echo "Available targets:"
@@ -114,6 +234,13 @@ help:
 	@echo "  test_neo4j  - Run Neo4j integration tests"
 	@echo "  test_pg     - Run PostgreSQL integration tests"
 	@echo "  test_update - Update test cases"
+	@echo "  complexity  - Report cyclomatic complexity"
+	@echo "  crap        - Report CRAP scores from unit test coverage"
+	@echo "  quality     - Report drift, equivalence, invariant, fuzz, mutation, and benchmark signals"
+	@echo "  quality_backend - Capture backend equivalence test results"
+	@echo "  quality_bench - Capture benchmark markdown and JSON reports"
+	@echo "  metrics     - Run cyclomatic complexity, CRAP, and quality reports"
+	@echo "  metrics_check - Enforce cyclomatic complexity, CRAP, and quality thresholds"
 	@echo ""
 	@echo "Utility:"
 	@echo "  clean       - Clean build artifacts"

README.md

@@ -84,3 +84,50 @@ numbers.
 The integration benchmark runner includes committed `base` and `traversal_shapes` datasets by default. The traversal
 shape suite checks expected result counts for chain, fanout, bounded cycle, disconnected, edge-kind-selective, and
 multi-path shortest-path scenarios before recording timings.
+
+### Test Metrics
+
+`make test` writes unit test coverage artifacts under `.coverage/`:
+
+```bash
+make test
+```
+
+The stable coverage profile is `.coverage/unit.out`, and the function coverage summary is `.coverage/coverage.txt`.
+
+Cyclomatic complexity, CRAP, and quality signal reports are available through dedicated metric targets:
+
+```bash
+make complexity
+make crap
+make quality
+make metrics
+```
+
+`make complexity` writes `.coverage/cyclomatic.txt`. `make crap` reruns unit tests for a fresh coverage profile, then
+writes `.coverage/crap.txt`, `.coverage/crap.json`, `.coverage/quality.txt`, `.coverage/quality.json`, and a standalone
+HTML report at `.coverage/metrics.html`. The quality section summarizes semantic drift, backend equivalence,
+integration/template invariants, fuzz health, mutation score, and benchmark drift. Signals that need external captures are
+reported as pending unless their input files are provided.
+Generated parser files, tests, vendor code, and testdata are excluded from these reports. The HTML report embeds its CSS
+and JavaScript directly in the document, so it can be opened without network access.
+
+Optional quality inputs can be supplied through Make variables:
+
+```bash
+make quality BACKEND_RESULT_ARGS="-backend-result pg=.coverage/integration-pg.json -backend-result neo4j=.coverage/integration-neo4j.json"
+make quality BENCHMARK_REPORT=.coverage/benchmark.json BENCHMARK_BASELINE=.coverage/benchmark-baseline.json
+make quality FUZZ_REPORT=.coverage/fuzz.json MUTATION_REPORT=.coverage/mutation.json
+```
+
+`make quality_backend` captures PostgreSQL and Neo4j integration results for backend equivalence comparison. It requires
+`PG_CONNECTION_STRING` and `NEO4J_CONNECTION_STRING`. `make quality_bench` writes benchmark markdown and JSON captures
+for later baseline comparison.
+
+Thresholds are report-only by default. To enforce the configured thresholds, run:
+
+```bash
+make metrics_check
+```
+
+The defaults can be adjusted with `CYCLO_TOP`, `CYCLO_OVER`, `CRAP_TOP`, `CRAP_OVER`, and `BENCHMARK_REGRESSION`.

cmd/benchmark/README.md

@@ -1,6 +1,6 @@
 # Benchmark
 
-Runs query scenarios against a real database and outputs a markdown timing table.
+Runs query scenarios against a real database and outputs markdown, JSON, or benchfmt timing data.
 
 ## Usage
 
@@ -25,6 +25,9 @@ go run ./cmd/benchmark -connection "..." -output report.md
 
 # Emit benchfmt for benchstat
 go run ./cmd/benchmark -connection "..." -format benchfmt -output report.bench
+
+# Save markdown and JSON for quality baseline comparison
+go run ./cmd/benchmark -connection "..." -output report.md -json-output report.json
 ```
 
 ## Flags
@@ -39,6 +42,7 @@ go run ./cmd/benchmark -connection "..." -format benchfmt -output report.bench
 | `-dataset-dir` | `integration/testdata` | Path to testdata directory |
 | `-format` | `markdown` | Output format (`markdown`, `json`, `benchfmt`) |
 | `-output` | stdout | Output file |
+| `-json-output` | | JSON output file for baseline comparison |
 
 Use `-format benchfmt` when comparing scenario timings with `benchstat`. Each timed scenario iteration is emitted as a
 separate `ns/op` sample so two benchmark runs can be compared directly.

cmd/benchmark/main.go

@@ -40,8 +40,9 @@ func main() {
 		driver       = flag.String("driver", "pg", "database driver (pg, neo4j)")
 		connStr      = flag.String("connection", "", "database connection string (or CONNECTION_STRING)")
 		iterations   = flag.Int("iterations", 10, "timed iterations per scenario")
-		output       = flag.String("output", "", "markdown output file (default: stdout)")
+		output       = flag.String("output", "", "output file (default: stdout)")
 		format       = flag.String("format", reportFormatMarkdown, "output format (markdown, json, benchfmt)")
+		jsonOutput   = flag.String("json-output", "", "JSON output file for baseline comparison")
 		datasetDir   = flag.String("dataset-dir", "integration/testdata", "path to testdata directory")
 		localDataset = flag.String("local-dataset", "", "additional local dataset (e.g. local/phantom)")
 		onlyDataset  = flag.String("dataset", "", "run only this dataset (e.g. diamond, local/phantom)")
@@ -161,26 +162,39 @@ func main() {
 		}
 	}
 
-	// Write report
-	var mdOut *os.File
+	// Write primary report.
+	var out *os.File
 	if *output != "" {
 		var err error
-		mdOut, err = os.Create(*output)
+		out, err = os.Create(*output)
 		if err != nil {
 			fatal("failed to create output: %v", err)
 		}
-		defer mdOut.Close()
+		defer out.Close()
 	} else {
-		mdOut = os.Stdout
+		out = os.Stdout
 	}
 
-	if err := writeReport(mdOut, report, *format); err != nil {
+	if err := writeReport(out, report, *format); err != nil {
 		fatal("failed to write report: %v", err)
 	}
 
 	if *output != "" {
 		fmt.Fprintf(os.Stderr, "wrote %s\n", *output)
 	}
+
+	if *jsonOutput != "" {
+		jsonOut, err := os.Create(*jsonOutput)
+		if err != nil {
+			fatal("failed to create JSON output: %v", err)
+		}
+		defer jsonOut.Close()
+
+		if err := writeJSON(jsonOut, report); err != nil {
+			fatal("failed to write JSON output: %v", err)
+		}
+		fmt.Fprintf(os.Stderr, "wrote %s\n", *jsonOutput)
+	}
 }
 
 func scanKinds(datasetDir string, datasets []string) (graph.Kinds, graph.Kinds) {

cmd/benchmark/report.go

@@ -34,11 +34,11 @@ const (
 
 // Report holds all benchmark results and metadata.
 type Report struct {
-	Driver     string
-	GitRef     string
-	Date       string
-	Iterations int
-	Results    []Result
+	Driver     string   `json:"driver"`
+	GitRef     string   `json:"git_ref"`
+	Date       string   `json:"date"`
+	Iterations int      `json:"iterations"`
+	Results    []Result `json:"results"`
 }
 
 func writeReport(w io.Writer, r Report, format string) error {

cmd/benchmark/report_test.go

@@ -36,8 +36,8 @@ func TestWriteJSON(t *testing.T) {
 
 	require.NoError(t, writeReport(&out, report, reportFormatJSON))
 
-	require.Contains(t, out.String(), `"Driver": "pg"`)
-	require.Contains(t, out.String(), `"Samples": [`)
+	require.Contains(t, out.String(), `"driver": "pg"`)
+	require.Contains(t, out.String(), `"samples": [`)
 	require.Contains(t, out.String(), `1000000`)
 }
 
@@ -96,3 +96,39 @@ func testReport() Report {
 		}},
 	}
 }
+
+func TestWriteJSONEmitsBaselineFriendlyReport(t *testing.T) {
+	report := Report{
+		Driver:     "pg",
+		GitRef:     "abc123",
+		Date:       "2026-05-14",
+		Iterations: 3,
+		Results: []Result{{
+			Section: "Traversal",
+			Dataset: "base",
+			Label:   "depth 1",
+			Stats: Stats{
+				Median: 10 * time.Millisecond,
+				P95:    20 * time.Millisecond,
+				Max:    30 * time.Millisecond,
+			},
+		}},
+	}
+
+	var output bytes.Buffer
+	if err := writeJSON(&output, report); err != nil {
+		t.Fatalf("write JSON: %v", err)
+	}
+
+	text := output.String()
+	for _, expected := range []string{
+		`"driver": "pg"`,
+		`"git_ref": "abc123"`,
+		`"median": 10000000`,
+		`"section": "Traversal"`,
+	} {
+		if !strings.Contains(text, expected) {
+			t.Fatalf("JSON report missing %q:\n%s", expected, text)
+		}
+	}
+}