Add first-class Cypher query parameter support for read execution

[Copilot]

Cypher parameters ($name) were already represented in the AST but rejected at runtime, which prevented safe parameterized queries. This PR adds read-query parameter support across filtering and projection while preserving existing cypher(&str) APIs.

• API additions (source-compatible)

  • Added Parameters type alias (HashMap<String, CypherValue>) for named query parameters.
  • Added parameterized read methods:
    • cypher_params(&self, query, &parameters)
    • cypher_with_strategy_params(&self, query, strategy, &parameters)
  • Existing cypher(...) and cypher_with_strategy(...) remain unchanged and continue to work without parameters.
  • Added default implementations for the new parameterized methods on public traits (PetgraphCypher, PetgraphCypherRead) to keep downstream trait implementors source-compatible.

• Execution engine wiring

  • Threaded parameters through expression evaluation, WHERE evaluation, projection (RETURN), sort expression evaluation, and function argument evaluation.
  • Implemented Expression::Parameter resolution from the provided parameter map.

• Validation and error behavior

  • Added pre-execution parameter presence validation for reachable read-query clauses (MATCH/OPTIONAL MATCH WHERE, RETURN, UNWIND, ORDER BY).
  • Missing read parameters now produce a clear error:
    • CypherError::InvalidQuery("missing query parameter: $<name>")
  • Mutation queries (cypher_mut) now explicitly reject parameter usage with a clear error:
    • CypherError::Unsupported("query parameters are not supported in cypher_mut(): $<name>")

• Tests for acceptance criteria and compatibility

  • Added focused integration tests covering:
    • parameter use in WHERE
    • parameter use in RETURN
    • parameter use in function arguments
    • clear error on missing parameter
    • trait default-method backward compatibility for external implementors
    • explicit parameter rejection in cypher_mut

Example usage:

use petgraph_decypher::{Parameters, CypherValue, PetgraphCypher};

let mut params = Parameters::new();
params.insert("name".into(), CypherValue::String("Alice".into()));
params.insert("min_age".into(), CypherValue::Integer(30));

let rows = graph.cypher_params(
    "MATCH (p:Person) WHERE p.name = $name AND p.age >= $min_age RETURN p",
    &params,
)?;

[Copilot]

Pull request overview

Adds first-class support for named Cypher parameters ($name) in read query execution so callers can safely run parameterized MATCH/WHERE/RETURN queries without string interpolation, while keeping existing cypher(&str) entrypoints working.

Changes:

• Introduces a public Parameters alias and new parameterized read APIs (cypher_params, cypher_with_strategy_params).
• Threads parameters through expression evaluation (WHERE/projection/function args/ORDER BY) and adds pre-execution “missing parameter” validation.
• Adds integration tests covering parameter usage and missing-parameter error behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
src/query.rs	Adds Parameters, new parameterized read methods, pre-validation for missing params, and parameter-aware expression evaluation.
src/lib.rs	Re-exports Parameters from the crate root.
tests/query_tests.rs	Adds integration tests for parameters in WHERE/RETURN/function args and missing-parameter errors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sunsided]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied the review-thread fixes in commit 29f139b (with core compatibility/validation changes in d068436): added default trait method implementations to avoid breaking external implementors, narrowed read-parameter validation to reachable read clauses, and now explicitly reject parameters in cypher_mut() with a clear Unsupported error. Added regression tests for trait default compatibility and mutation parameter rejection.