fix: handle grave-escaped property names properly BED-8967

[seanjSO]

Description

Resolves: BED-8967

Type of Change

• Chore (a change that does not modify the application functionality)
• Bug fix (a change that fixes an issue)
• New feature / enhancement (a change that adds new functionality)
• Refactor (no behaviour change)
• Test coverage
• Build / CI / tooling
• Documentation

Testing

• Unit tests added / updated
• Integration tests added / updated
• Full test suite run (make test_all with CONNECTION_STRING set)

Screenshots (if appropriate):

Driver Impact

• PostgreSQL driver (drivers/pg)
• Neo4j driver (drivers/neo4j)

Checklist

• Code is formatted
• All existing tests pass
• go.mod / go.sum are up to date if dependencies changed

Summary by CodeRabbit

• Bug Fixes

  • Improved handling of property names containing hyphens, spaces, backticks, empty values, reserved words, and Unicode characters.
  • Preserved property names correctly when reading, filtering, updating, or removing node and relationship properties.
  • Ensured generated Cypher queries consistently escape special property names.
  • Added validation and clear errors for empty property names.

• Tests

  • Added coverage across parsing, formatting, query building, PostgreSQL translation, and end-to-end property-key operations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1bf7c403-0d2b-4dce-b097-030d0aba6ac5

📥 Commits

Reviewing files that changed from the base of the PR and between d0e5cfc and d18c2d1.

📒 Files selected for processing (4)

• cypher/frontend/property_key_test.go
• cypher/models/cypher/format/format_test.go
• cypher/models/cypher/property_key_test.go
• cypher/models/pgsql/test/translation_cases/nodes.sql

🚧 Files skipped from review as they are similar to previous changes (4)

• cypher/models/cypher/format/format_test.go
• cypher/models/pgsql/test/translation_cases/nodes.sql
• cypher/models/cypher/property_key_test.go
• cypher/frontend/property_key_test.go

---

Walkthrough

Property keys are stored in raw form after parsing and escaped when Cypher is emitted. New utilities provide Unicode-aware validation, escaping, and unescaping. Parser, formatter, PostgreSQL translation, query-builder, and integration tests cover special-character keys.

Changes

Property key normalization and formatting

Layer / File(s)	Summary
Property-key contract cypher/models/cypher/property_key.go, cypher/models/cypher/property_key_test.go, cypher/models/cypher/model.go	Adds validation, escaping, unescaping, tests, and raw-symbol documentation for property keys.
Parser key normalization cypher/frontend/...	Stores unescaped keys in property lookups and map literals. Parser tests cover escaped, empty, punctuation, and Unicode keys.
Cypher key formatting cypher/models/cypher/format/*, query/builder_test.go, query/v2/query_test.go	Escapes map literal keys and property lookup symbols during Cypher output.
Query validation and downstream coverage query/v2/*, cypher/models/pgsql/*, integration/testdata/*	Validates property keys in query construction and PostgreSQL translation. Tests cover reads, filters, assignments, removals, and relationship access.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CypherParser
  participant PropertyKeyUtilities
  participant CypherAST
  participant CypherFormatter
  participant PostgreSQLTranslator
  CypherParser->>PropertyKeyUtilities: Unescape and validate parsed key
  PropertyKeyUtilities->>CypherAST: Store raw property key
  CypherAST->>CypherFormatter: Provide raw property key
  CypherFormatter->>PropertyKeyUtilities: Validate and escape key
  PropertyKeyUtilities-->>CypherFormatter: Return Cypher-safe key
  CypherAST->>PostgreSQLTranslator: Provide normalized property key
  PostgreSQLTranslator-->>CypherAST: Return translated property predicate

Loading

Possibly related PRs

• SpecterOps/DAWGS#75: Introduced the query/v2 property-key handling that this change extends with raw-name validation.

Suggested labels: bug

Suggested reviewers: urangel

Poem

A rabbit stores each key with care,
Then adds backticks when needed there.
Empty names stop at the gate,
Unicode keys pass validation straight.
Tests hop through every special case.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.76% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the fix for grave-escaped property names and includes the related issue identifier.
Description check	✅ Passed	The description follows the template, identifies BED-8967, records testing and driver impact, and includes the relevant checklist status.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch seanj/BED-8967-backtick-accessors

---

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

[urangel]

Lots of good tests!