fix(cypher): preserve legacy clients and classify parser errors (HG-19)

[imbajin]

Purpose of the PR

HG-19 follow-up to #3241, within #3242. The proposed top-level errors field makes existing Java clients reject even successful Cypher responses. Move the metadata into status.attributes.errors while preserving the existing envelope, status and message. Recognize actual translation-1.0.4 parser failures as HugeGraph.Cypher.SyntaxError and remove the unavailable parameter-binding hint/code.

This branch preserves Nguyen Quang Minh's original commit ed8344d19ab303a46cb4e9fdb67340815c37e1c4 as its parent. Depends on #3241: the PR targets Apache master because the source PR is in another contributor's fork; until #3241 lands, GitHub includes its original commit in this comparison. The repair-only diff is ed8344d19ab303a46cb4e9fdb67340815c37e1c4..HEAD. Please coordinate integration of both PRs; this does not supersede or overwrite the original contribution.

Main Changes

• Keep only requestId, status and result at the top level. Put the existing structured error list in the client-compatible attributes map on failure.
• Classify invalid input, unknown functions and statement-count errors; limit the variable hint to actual undefined-variable messages, and keep undefined index labels in execution errors.
• Add real-parser/envelope unit tests, exact API code/hint assertions and a standalone actual-Java-Client compatibility test without introducing a Server-to-Client dependency cycle.
• Document request limits, response schema, complete codes/hints and reproducible client checks in docs/cypher-api.md.

Verifying these changes

• Need tests and can be verified as follows:
  • Java 11.0.29 / Maven 3.9.11: full mvn clean compile -Dmaven.javadoc.skip=true passes; mvn editorconfig:format and git diff --check pass.
  • mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test -Dtest=CypherErrorTest -Dsurefire.failIfNoSpecifiedTests=false: 8 tests, 0 failures/errors/skips. Original head: 6 of the 8 regression tests fail.
  • Standalone CypherClientCompatibilityTest using real RestResult.readObject(Response.class): 4/4 pass with each locally available Client 1.7.0 and development 1.8.0 jar. Original head fails both current-success and current-failure deserialization for each jar; legacy fixtures and the top-level-errors negative control pass. Commands are in the API doc.
  • Actual parser probes cover malformed MATCH, misspelled RETURN, multiple statements, unknown date(), and undefined variables. Unbound $name still translates to Cypher null.

Limitations: live CypherApiTest and Hubble UI were not run; Hubble's QueryService.executeCypher -> Client CypherManager -> CypherAPI -> RestResult path was traced at Toolchain 3b385c3d2f1c04f7fa4b4534b4b1ec220627bfb5. No cluster, live-data or matching-RC acceptance was performed. Independent repair verification remains with the originating reviewer through HG-17.

Does this PR potentially affect the following parts?

• Dependencies
• Modify configurations
• The public API
• Other affects
• Nope

Documentation Status

• Doc - TODO: repository documentation is complete; paired website alignment remains with its author before coordinated publication.
• Doc - Done
• Doc - No Need

Repository: docs/cypher-api.md. Paired website: apache/hugegraph-doc#499 at 6f52040de2b7613690fb6cc50aafd6aa7af031a2, left untouched. The optional bound-query fork hugegraph#238 and TinkerPop migration are outside this repair.

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 41.60%. Comparing base (2f827d6) to head (a2ac2be).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
...apache/hugegraph/api/cypher/CypherErrorMapper.java	52.63%	3 Missing and 6 partials ⚠️
...a/org/apache/hugegraph/api/cypher/CypherModel.java	88.88%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3259      +/-   ##
============================================
+ Coverage     41.40%   41.60%   +0.20%     
+ Complexity     7337     7315      -22     
============================================
  Files           802      794       -8     
  Lines         69792    69135     -657     
  Branches       9312     9267      -45     
============================================
- Hits          28897    28767     -130     
+ Misses        37604    37083     -521     
+ Partials       3291     3285       -6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.