This is an automated email from the ASF dual-hosted git repository. imbajin pushed a commit to branch goal-scan in repository https://gitbox.apache.org/repos/asf/hugegraph-ai.git
commit 46e7199c58adf1e90fe1c571b107c05812450461 Author: imbajin <[email protected]> AuthorDate: Sun May 31 11:27:04 2026 +0800 docs(code-scan): record core module audit - add P0-P5 issue ledger for llm and client modules - mark ineffective core test coverage with FIXME comments - complete code-scan checkpoints and final report - preserve behavior by limiting source edits to comments chore: ignore local PR review artifacts - add a narrow ignore rule for .workflow/pr*-review outputs - keep tracked workflow ledgers visible to git - verify generated pr68-review files are ignored --- .gitignore | 3 + .workflow/code-scan/checkpoints/00-setup.md | 4 +- .../code-scan/checkpoints/01-client-transport.md | 11 +- .../checkpoints/02-client-api-structure.md | 13 +- .../code-scan/checkpoints/03-llm-api-config.md | 13 +- .../code-scan/checkpoints/04-llm-flow-operator.md | 11 +- .../code-scan/checkpoints/05-llm-index-model.md | 14 +- .workflow/code-scan/checkpoints/06-test-quality.md | 12 +- .workflow/code-scan/checkpoints/07-synthesis.md | 17 +- .workflow/code-scan/code-scan-state.json | 88 +++- .../code-scan/reports/final-code-scan-report.md | 83 ++++ .workflow/code-scan/reports/issues.md | 462 ++++++++++++++++++++- .workflow/code-scan/reports/module-map.md | 16 +- .workflow/code-scan/reports/test-quality-ledger.md | 49 ++- docs/plans/2026-05-31-hugegraph-ai-code-scan.md | 42 +- hugegraph-llm/src/hugegraph_llm/api/admin_api.py | 2 + hugegraph-llm/src/tests/api/test_rag_api.py | 7 + hugegraph-llm/src/tests/config/test_config.py | 3 + .../src/tests/config/test_prompt_config.py | 5 + .../src/tests/indices/test_faiss_vector_index.py | 3 + .../tests/integration/test_graph_rag_pipeline.py | 3 + .../src/tests/integration/test_kg_construction.py | 3 + .../src/tests/integration/test_rag_pipeline.py | 3 + .../src/tests/models/llms/test_openai_client.py | 3 + .../hugegraph_op/test_commit_to_hugegraph.py | 3 + .../test_commit_to_hugegraph_load_into_graph.py | 3 + .../operators/index_op/test_vector_index_query.py | 3 + .../llm_op/test_property_graph_extract.py | 3 + .../src/tests/api/test_auth_routing.py | 3 + .../src/tests/api/test_graph.py | 5 + .../src/tests/api/test_gremlin.py | 5 + .../src/tests/api/test_schema.py | 3 + 32 files changed, 829 insertions(+), 69 deletions(-) diff --git a/.gitignore b/.gitignore index 1822afb7..72ea8f2a 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,9 @@ *.pkl out/production/ +# Local PR review scratch artifacts +.workflow/pr*-review/ + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] diff --git a/.workflow/code-scan/checkpoints/00-setup.md b/.workflow/code-scan/checkpoints/00-setup.md index 42a19dd2..563eda77 100644 --- a/.workflow/code-scan/checkpoints/00-setup.md +++ b/.workflow/code-scan/checkpoints/00-setup.md @@ -31,8 +31,8 @@ It does not implement logic/design fixes during the scan. It records them as fin - T0.1 guidance read: done - T0.2 prior quality docs read: done - T0.3 code-scan ledger: done -- T0.4 setup commit: pending +- T0.4 setup commit: done (`860b2a49`) ## Next Checkpoint -Dispatch client and LLM scan lanes after committing the setup slice. +Setup is complete. Client, LLM, and synthesis checkpoints record the completed scan lanes. diff --git a/.workflow/code-scan/checkpoints/01-client-transport.md b/.workflow/code-scan/checkpoints/01-client-transport.md index 8f2833a6..fa47eafe 100644 --- a/.workflow/code-scan/checkpoints/01-client-transport.md +++ b/.workflow/code-scan/checkpoints/01-client-transport.md @@ -1,6 +1,6 @@ # T1 Client Transport Checkpoint -Status: pending +Status: completed ## Scope @@ -11,8 +11,13 @@ Status: pending ## Findings -Pending. +- `CS-002`: request/error logging can leak auth secrets. +- `CS-003`: leading-slash routes drop configured URL path prefixes. +- `CS-004`: successful response parse failures are swallowed as `{}`. +- `CS-005`: graphspace support depends on one fragile constructor-time probe. +- `CS-027`: each lazy manager owns an independent session with no unified close. ## Test-quality Notes -Pending. +- Added `FIXME:` in `test_auth_routing.py` because the dummy session mirrors + production resolver behavior instead of exercising `HGraphSession.resolve()`. diff --git a/.workflow/code-scan/checkpoints/02-client-api-structure.md b/.workflow/code-scan/checkpoints/02-client-api-structure.md index b565e30a..d52b2be7 100644 --- a/.workflow/code-scan/checkpoints/02-client-api-structure.md +++ b/.workflow/code-scan/checkpoints/02-client-api-structure.md @@ -1,6 +1,6 @@ # T1 Client API and Structure Checkpoint -Status: pending +Status: completed ## Scope @@ -10,8 +10,15 @@ Status: pending ## Findings -Pending. +- `CS-006`: graph query APIs concatenate query strings without URL encoding. +- `CS-007`: `PropertyKey` builder exposes `calc*()` / `userdata()` but `create()` + drops them. +- `CS-008`: Gremlin API rewrites all failures as `NotFoundError`. +- `CS-018`: `IndexLabel.by()` loses multi-field order through `set`. +- `CS-019`: `getVertexByCondition()` accepts `page` but drops next-page token. ## Test-quality Notes -Pending. +- Added `FIXME:` comments in `test_graph.py`, `test_schema.py`, and + `test_gremlin.py`. +- Recorded false-green and shared-state client tests as `CS-034` and `CS-035`. diff --git a/.workflow/code-scan/checkpoints/03-llm-api-config.md b/.workflow/code-scan/checkpoints/03-llm-api-config.md index 2848d20b..03a99325 100644 --- a/.workflow/code-scan/checkpoints/03-llm-api-config.md +++ b/.workflow/code-scan/checkpoints/03-llm-api-config.md @@ -1,6 +1,6 @@ # T2 LLM API and Config Checkpoint -Status: pending +Status: completed ## Scope @@ -12,8 +12,15 @@ Status: pending ## Findings -Pending. +- `CS-001`: `/logs` can read arbitrary files through path traversal. +- `CS-009`: config endpoints collapse failures into `Missing Value`. +- `CS-010`: GraphRAG/Text2Gremlin API failures become generic 500s. +- `CS-011`: `client_config` partial requests overwrite global graph settings. +- `CS-012`: unsupported provider types are written into global settings first. +- `CS-020`: runtime prompt YAML and prompt tests have drifted. +- `CS-021`: `.env` sync bypasses Pydantic typing and import has side effects. ## Test-quality Notes -Pending. +- Added `FIXME:` comments in `admin_api.py`, `test_rag_api.py`, + `test_prompt_config.py`, and `test_config.py`. diff --git a/.workflow/code-scan/checkpoints/04-llm-flow-operator.md b/.workflow/code-scan/checkpoints/04-llm-flow-operator.md index 74b6f062..fb28e3a2 100644 --- a/.workflow/code-scan/checkpoints/04-llm-flow-operator.md +++ b/.workflow/code-scan/checkpoints/04-llm-flow-operator.md @@ -1,6 +1,6 @@ # T2 LLM Flow and Operator Checkpoint -Status: pending +Status: completed ## Scope @@ -13,8 +13,13 @@ Status: pending ## Findings -Pending. +- `CS-013`: property graph extraction stringifies values that importer rejects. +- `CS-014`: graph/vector dependency failures are treated as empty retrieval. +- `CS-022`: legacy triples output cannot feed current importer shape. +- `CS-023`: vector recall parameters are lost across flow/node/operator boundary. +- `CS-028`: Text2Gremlin always makes two LLM calls regardless of requested output. ## Test-quality Notes -Pending. +- Added `FIXME:` comments in property graph, commit-to-graph, vector query, + GraphRAG/RAG/KG integration, and API tests. diff --git a/.workflow/code-scan/checkpoints/05-llm-index-model.md b/.workflow/code-scan/checkpoints/05-llm-index-model.md index 5ff56c22..86c83abc 100644 --- a/.workflow/code-scan/checkpoints/05-llm-index-model.md +++ b/.workflow/code-scan/checkpoints/05-llm-index-model.md @@ -1,6 +1,6 @@ # T2 LLM Index and Model Checkpoint -Status: pending +Status: completed ## Scope @@ -12,8 +12,16 @@ Status: pending ## Findings -Pending. +- `CS-015`: LiteLLM embedding factory crashes for advertised config. +- `CS-016`: OpenAI wrapper returns provider failures as normal model text. +- `CS-017`: embedding dimension probing hides provider failures. +- `CS-024`: LiteLLM sync streaming violates `BaseLLM` contract. +- `CS-025`: `dis_threshold` has incompatible backend semantics. +- `CS-026`: graph backup can report success with empty `schema.json`. +- `CS-029`: `get_embeddings_parallel()` launches all batches concurrently. ## Test-quality Notes -Pending. +- Added `FIXME:` comments in OpenAI and Faiss tests. +- Recorded missing tests for embedding factories, LiteLLM streaming, + backend thresholds, and bounded embedding concurrency. diff --git a/.workflow/code-scan/checkpoints/06-test-quality.md b/.workflow/code-scan/checkpoints/06-test-quality.md index 2857885f..4ba2c35c 100644 --- a/.workflow/code-scan/checkpoints/06-test-quality.md +++ b/.workflow/code-scan/checkpoints/06-test-quality.md @@ -1,6 +1,6 @@ # T3 Test-quality Checkpoint -Status: pending +Status: completed ## Scope @@ -9,8 +9,14 @@ Status: pending ## FIXME Candidates -Pending. +Applied required `FIXME:` comments to 17 affected files. See +`reports/test-quality-ledger.md`. ## Ineffective Test Patterns -Pending. +- Fake integration tests define local replacements for production flows. +- Core graph import tests patch away branchy behavior. +- Client error tests assert only inside `except` blocks. +- Some integration tests share dirty graph state. +- External/provider smoke tests print without assertions. +- Selected HugeGraph tests can still runtime-skip from shared fixtures. diff --git a/.workflow/code-scan/checkpoints/07-synthesis.md b/.workflow/code-scan/checkpoints/07-synthesis.md index 1de61fa6..badd1db6 100644 --- a/.workflow/code-scan/checkpoints/07-synthesis.md +++ b/.workflow/code-scan/checkpoints/07-synthesis.md @@ -1,15 +1,24 @@ # T3 Synthesis Checkpoint -Status: pending +Status: completed ## Cross-module Contract Review -Pending. +`hugegraph-llm` depends on `pyhugegraph` to preserve error and response +contracts. The scan found several cross-module risks: + +- Gremlin failures are retyped as `NotFoundError`. +- Malformed successful responses can become `{}`. +- URL-prefix routing can target the wrong path. +- Graphspace support can be disabled by transient constructor-time probes. ## Deduplication Notes -Pending. +- L4/L6 fake integration findings were merged into `CS-030`. +- L2/L6 client shared-state findings were merged into `CS-035`. +- L3/L4 API/flow error-swallowing findings stayed separate because they occur + at different contracts. ## Final Report Status -Pending. +Created `reports/final-code-scan-report.md`. diff --git a/.workflow/code-scan/code-scan-state.json b/.workflow/code-scan/code-scan-state.json index b94e4343..1bc21dbc 100644 --- a/.workflow/code-scan/code-scan-state.json +++ b/.workflow/code-scan/code-scan-state.json @@ -1,8 +1,10 @@ { - "current_task": "T0", + "current_task": "complete", "repo_sha_start": "d16db33c5509647afccae588c46c0b0767adbb76", + "setup_commit": "860b2a49", "branch": "goal-test", "started_at_utc": "2026-05-31T03:13:05Z", + "completed_at_utc": "2026-05-31T05:05:00Z", "modules": [ "hugegraph-llm", "hugegraph-python-client" @@ -19,17 +21,39 @@ "tasks_completed": [ "T0.1", "T0.2", - "T0.3" + "T0.3", + "T0.4", + "T1.1", + "T1.2", + "T1.3", + "T2.1", + "T2.2", + "T2.3", + "T2.4", + "T3.1", + "T3.2", + "T3.3", + "T3.4" + ], + "checkpoints_completed": [ + "00-setup", + "01-client-transport", + "02-client-api-structure", + "03-llm-api-config", + "04-llm-flow-operator", + "05-llm-index-model", + "06-test-quality", + "07-synthesis" ], - "checkpoints_completed": [], "issue_counts": { - "P0": 0, - "P1": 0, - "P2": 0, - "P3": 0, - "P4": 0, + "P0": 1, + "P1": 16, + "P2": 9, + "P3": 3, + "P4": 8, "P5": 0 }, + "issue_total": 37, "files_touched": [ "docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md", "docs/plans/2026-05-31-hugegraph-ai-code-scan.md", @@ -45,16 +69,56 @@ ".workflow/code-scan/checkpoints/07-synthesis.md", ".workflow/code-scan/reports/issues.md", ".workflow/code-scan/reports/module-map.md", - ".workflow/code-scan/reports/test-quality-ledger.md" + ".workflow/code-scan/reports/test-quality-ledger.md", + ".workflow/code-scan/reports/final-code-scan-report.md", + "hugegraph-llm/src/hugegraph_llm/api/admin_api.py", + "hugegraph-llm/src/tests/api/test_rag_api.py", + "hugegraph-llm/src/tests/config/test_config.py", + "hugegraph-llm/src/tests/config/test_prompt_config.py", + "hugegraph-llm/src/tests/indices/test_faiss_vector_index.py", + "hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py", + "hugegraph-llm/src/tests/integration/test_kg_construction.py", + "hugegraph-llm/src/tests/integration/test_rag_pipeline.py", + "hugegraph-llm/src/tests/models/llms/test_openai_client.py", + "hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py", + "hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py", + "hugegraph-llm/src/tests/operators/index_op/test_vector_index_query.py", + "hugegraph-llm/src/tests/operators/llm_op/test_property_graph_extract.py", + "hugegraph-python-client/src/tests/api/test_auth_routing.py", + "hugegraph-python-client/src/tests/api/test_graph.py", + "hugegraph-python-client/src/tests/api/test_gremlin.py", + "hugegraph-python-client/src/tests/api/test_schema.py" ], "style_only_fixes": [], - "fixme_comments_added": [], + "fixme_comments_added": [ + "hugegraph-llm/src/hugegraph_llm/api/admin_api.py", + "hugegraph-llm/src/tests/api/test_rag_api.py", + "hugegraph-llm/src/tests/config/test_config.py", + "hugegraph-llm/src/tests/config/test_prompt_config.py", + "hugegraph-llm/src/tests/indices/test_faiss_vector_index.py", + "hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py", + "hugegraph-llm/src/tests/integration/test_kg_construction.py", + "hugegraph-llm/src/tests/integration/test_rag_pipeline.py", + "hugegraph-llm/src/tests/models/llms/test_openai_client.py", + "hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py", + "hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py", + "hugegraph-llm/src/tests/operators/index_op/test_vector_index_query.py", + "hugegraph-llm/src/tests/operators/llm_op/test_property_graph_extract.py", + "hugegraph-python-client/src/tests/api/test_auth_routing.py", + "hugegraph-python-client/src/tests/api/test_graph.py", + "hugegraph-python-client/src/tests/api/test_gremlin.py", + "hugegraph-python-client/src/tests/api/test_schema.py" + ], "commands_run": [ "sed -n '1,240p' AGENTS.md", "sed -n '1,240p' hugegraph-llm/AGENTS.md", "sed -n '1,260p' rules/README.md", "sed -n '1,260p' docs/specs/2026-05-31-hugegraph-ai-quality-program-design.md", - "sed -n '1,320p' docs/plans/2026-05-31-hugegraph-ai-quality-program.md" + "sed -n '1,320p' docs/plans/2026-05-31-hugegraph-ai-quality-program.md", + "rg -n \"pyhugegraph|PyHugeClient|gremlin|schema|graph\" hugegraph-llm/src hugegraph-python-client/src", + "git diff --check", + "uv run ruff check <edited-python-files>", + "git status --short" ], - "next_recommended_action": "Commit setup slice, then dispatch parallel scan lanes" + "next_recommended_action": "Fix CS-001 first, then address the client error-contract cluster and graph import contract drift." } diff --git a/.workflow/code-scan/reports/final-code-scan-report.md b/.workflow/code-scan/reports/final-code-scan-report.md new file mode 100644 index 00000000..e87d508b --- /dev/null +++ b/.workflow/code-scan/reports/final-code-scan-report.md @@ -0,0 +1,83 @@ +# Final Code Scan Report + +Date: 2026-05-31 +Scope: `hugegraph-llm`, `hugegraph-python-client` + +## Summary + +The scan completed all planned lanes. The highest-risk result is one P0 security issue in the `hugegraph-llm` admin log API. The broader pattern is that core boundary failures are often hidden: client transport errors are retyped, provider failures are returned as normal text, graph/vector dependency failures can be converted to empty results, and several integration tests use local stand-ins rather than production flows. + +No behavior-changing source fixes were made. Only scan documents and `FIXME:` comments were added. + +## Scope Covered + +- `hugegraph-python-client/src/pyhugegraph/` +- `hugegraph-python-client/src/tests/` +- `hugegraph-llm/src/hugegraph_llm/` +- `hugegraph-llm/src/tests/` +- Cross-module usage of `pyhugegraph` from `hugegraph-llm` + +## Issue Distribution by Priority + +| Priority | Count | Theme | +|---|---:|---| +| P0 | 1 | Admin log path traversal / weak default admin controls | +| P1 | 16 | Incorrect error contracts, config/global-state corruption, graph import correctness, provider factory failures | +| P2 | 9 | Contract drift, prompt/config side effects, vector backend semantics, backup correctness | +| P3 | 3 | Resource lifecycle and performance/cost risks | +| P4 | 8 | Ineffective tests, fake integration coverage, weak assertions, skipped/print-only tests | +| P5 | 0 | No minor style-only issues recorded | + +## Top P0-P2 Findings + +1. `CS-001`: `/logs` can read arbitrary files through path traversal. +2. `CS-002`: Client request/error logs can leak auth secrets. +3. `CS-004`: `ResponseValidation` can turn a broken `2xx` payload into `{}`. +4. `CS-008`: Gremlin failures are all rewritten as `NotFoundError`. +5. `CS-011`: Per-request `client_config` overwrites process-global graph settings. +6. `CS-013`: KG extraction stringifies values that the importer rejects, then can report success. +7. `CS-014`: Graph/vector dependency failures are treated as empty retrieval. +8. `CS-015`: LiteLLM embedding factory crashes for an advertised config branch. +9. `CS-020`: Runtime YAML prompts and prompt contract tests have drifted. +10. `CS-023`: Vector recall parameters are lost between flow/node/operator boundaries. + +## Test-quality and FIXME Summary + +The required `FIXME:` markers were added near the affected test or boundary code. Key clusters: + +- API contract gaps: `/logs`, `/rag`, `/rag/graph`, `/config/*`. +- Client contract gaps: auth routing, URL encoding, Gremlin error semantics, schema builder payloads. +- Flow/import gaps: `PropertyGraphExtract -> Commit2Graph`, graph/vector dependency failure propagation. +- Provider/backend gaps: OpenAI error propagation, LiteLLM construction/streaming, vector backend threshold semantics. +- Fake integration gaps: GraphRAG/RAG/KG tests that define local replacement classes. + +See `reports/test-quality-ledger.md` for the full list. + +## Cross-module Contract Risks + +`hugegraph-llm` assumes `pyhugegraph` failures are meaningful and typed, but the client currently collapses several of them: + +- Gremlin errors become `NotFoundError`. +- Response parse failures can become `{}`. +- URL-prefix routing can target the wrong path. +- Graphspace support can be disabled by a transient constructor-time probe. + +Those client behaviors directly affect `hugegraph-llm` graph import, GraphRAG, Text2Gremlin execution, and backup utilities. + +## Style-only Fixes Applied + +None. + +## Verification Commands + +- `git diff --check`: passed. +- `uv run ruff check <edited-python-files>`: passed for all Python files touched by `FIXME:` comments. +- `git status --short`: reviewed before final staging; unrelated `.workflow/pr68-review/` remains untracked and was left untouched. + +## Recommended Next Fix Plan + +1. Fix `CS-001` immediately: lock down `/logs` path handling and default admin credentials. +2. Fix the client error-contract cluster: `CS-002`, `CS-004`, `CS-008`. +3. Fix graph import correctness: `CS-013`, then add the missing round-trip tests. +4. Fix global config mutation and provider validation: `CS-011`, `CS-012`. +5. Replace fake integration tests with production-flow smoke coverage before broader refactors. diff --git a/.workflow/code-scan/reports/issues.md b/.workflow/code-scan/reports/issues.md index d7fd2958..aa0e7f6f 100644 --- a/.workflow/code-scan/reports/issues.md +++ b/.workflow/code-scan/reports/issues.md @@ -2,14 +2,470 @@ Issue IDs use `CS-NNN`. Priorities are P0 highest through P5 lowest. +## Issue Distribution + +| Priority | Count | +|---|---:| +| P0 | 1 | +| P1 | 16 | +| P2 | 9 | +| P3 | 3 | +| P4 | 8 | +| P5 | 0 | + ## Open Issues -Pending scan results. +### CS-001: `/logs` can read arbitrary files through path traversal + +- Priority: P0 +- Module: `hugegraph-llm` +- Layer: API / config / security +- Paths: `hugegraph-llm/src/hugegraph_llm/api/admin_api.py:33`, `hugegraph-llm/src/hugegraph_llm/api/admin_api.py:40`, `hugegraph-llm/src/hugegraph_llm/config/admin_config.py:26`, `hugegraph-llm/src/hugegraph_llm/demo/rag_demo/admin_block.py:27`, `hugegraph-llm/src/hugegraph_llm/demo/rag_demo/app.py:164` +- Status: open +- Evidence: `log_file` is accepted from request input and joined with `logs` without basename normalization or allowlist. The injected `log_stream()` opens that path directly. Default auth is disabled and default tokens are predictable. +- Impact: A caller with the default or known admin token can request paths outside `logs/`, exposing any readable file from the service process. +- Recommendation: Accept only server-side enum names for logs, reject absolute and traversal paths, require explicit secrets, and do not expose admin routes when auth is disabled. +- Test note: Added a `FIXME:` in `admin_api.py` for the missing path traversal contract test. + +### CS-002: Client request/error logs can leak auth secrets + +- Priority: P1 +- Module: `hugegraph-python-client` +- Layer: transport / auth +- Paths: `hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py:145`, `hugegraph-python-client/src/pyhugegraph/utils/util.py:120`, `hugegraph-python-client/src/pyhugegraph/api/auth.py:43`, `hugegraph-python-client/src/pyhugegraph/api/auth.py:68` +- Status: open +- Evidence: `HGraphSession.request()` logs raw `kwargs`, and `ResponseValidation` logs raw `response.request.body` on HTTP errors. Auth user create/modify requests serialize `user_password` into the request body. +- Impact: Passwords can enter debug/error logs during auth failures or debug tracing. +- Recommendation: Redact sensitive request fields before logging, including password-like keys and auth headers. +- Test note: Added a `FIXME:` in `test_auth_routing.py` for auth request body/redaction coverage. + +### CS-003: Absolute API paths drop configured URL path prefixes + +- Priority: P1 +- Module: `hugegraph-python-client` +- Layer: transport / routing +- Paths: `hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py:100`, `hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py:120`, `hugegraph-python-client/src/pyhugegraph/api/auth.py:37`, `hugegraph-python-client/src/pyhugegraph/api/auth.py:84` +- Status: open +- Evidence: `HGraphSession.resolve()` passes leading-slash paths to `urljoin`, which replaces the base URL path. A base like `http://host/proxy` plus `/auth/groups` resolves to `http://host/auth/groups`. +- Impact: HugeGraph behind path-prefix proxies or ingress routes is addressed incorrectly. +- Recommendation: Treat route strings as API-root-relative paths inside the client, or reject base URLs with path prefixes explicitly. +- Test note: Added a `FIXME:` in `test_auth_routing.py` because current dummy routing duplicates the production resolver and misses this. + +### CS-004: Successful response parse failures are swallowed as empty success + +- Priority: P1 +- Module: `hugegraph-python-client` +- Layer: transport / response validation +- Paths: `hugegraph-python-client/src/pyhugegraph/utils/util.py:85`, `hugegraph-python-client/src/pyhugegraph/utils/util.py:136` +- Status: open +- Evidence: `ResponseValidation.__call__()` catches broad `Exception` after successful HTTP parsing and returns the default `{}`. A `200 OK` response with malformed JSON becomes an empty dict. +- Impact: Protocol drift or corrupt responses are indistinguishable from legitimate empty results. +- Recommendation: Raise a typed parse/protocol exception on successful-response parse errors. +- Test note: Existing response validation tests do not cover `2xx` malformed JSON. + +### CS-005: Graphspace support depends on one fragile constructor-time probe + +- Priority: P1 +- Module: `hugegraph-python-client` +- Layer: transport / routing +- Paths: `hugegraph-python-client/src/pyhugegraph/utils/huge_config.py:44`, `hugegraph-python-client/src/pyhugegraph/utils/huge_config.py:73`, `hugegraph-python-client/src/pyhugegraph/utils/huge_router.py:139` +- Status: open +- Evidence: `HGraphConfig.__post_init__()` probes `/versions` with a fixed `0.5s` timeout. Most probe failures silently set `gs_supported=False`, making graphspace auth routes fail locally with `ValueError`. +- Impact: HugeGraph 1.7+ auth behavior becomes sensitive to a single transient version probe. +- Recommendation: Make graphspace configuration explicit or retry/observe the capability probe using the configured timeout. +- Test note: Current routing tests do not cover probe failure and graphspace fallback behavior. + +### CS-006: Graph query APIs build query strings without URL encoding + +- Priority: P1 +- Module: `hugegraph-python-client` +- Layer: client-api +- Paths: `hugegraph-python-client/src/pyhugegraph/api/graph.py:68`, `hugegraph-python-client/src/pyhugegraph/api/graph.py:73`, `hugegraph-python-client/src/pyhugegraph/api/graph.py:173`, `hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py:144` +- Status: open +- Evidence: `getVertexByPage()`, `getVertexByCondition()`, and `getEdgeByPage()` concatenate labels and JSON properties directly into the URL. +- Impact: Property values containing `&`, `?`, `#`, `=`, or spaces can corrupt filters and query different data. +- Recommendation: Use `params=` or `urllib.parse.urlencode()` for all query parameters. +- Test note: Added a `FIXME:` in `test_graph.py` for pagination/filter contract coverage. + +### CS-007: `PropertyKey` builder drops advertised `calc*()` and `userdata()` + +- Priority: P1 +- Module: `hugegraph-python-client` +- Layer: schema +- Paths: `hugegraph-python-client/src/pyhugegraph/api/schema_manage/property_key.py:96`, `hugegraph-python-client/src/pyhugegraph/api/schema_manage/property_key.py:117`, `hugegraph-python-client/src/pyhugegraph/api/schema_manage/property_key.py:135`, `hugegraph-python-client/src/pyhugegraph/api/schema_manage/property_key.py:144` +- Status: open +- Evidence: Builder methods set aggregate/userdata state, but `create()` serializes only name, data type, and cardinality. +- Impact: Callers believe they created aggregate/userdata property keys, but the server never receives those fields. +- Recommendation: Include these fields in the create payload or remove/disable unsupported mutators. +- Test note: Added a `FIXME:` in `test_schema.py`. + +### CS-008: Gremlin API rewrites all failures as `NotFoundError` + +- Priority: P1 +- Module: `hugegraph-python-client` +- Layer: gremlin / error contract +- Paths: `hugegraph-python-client/src/pyhugegraph/api/gremlin.py:48`, `hugegraph-python-client/src/pyhugegraph/api/gremlin.py:54`, `hugegraph-python-client/src/tests/api/test_gremlin.py:99` +- Status: open +- Evidence: `GremlinManager.exec()` catches every exception and raises `NotFoundError`. +- Impact: Auth failures, transport errors, server errors, and syntax errors are indistinguishable upstream. +- Recommendation: Preserve typed lower-level exceptions; map only known Gremlin business errors. +- Test note: Added a `FIXME:` in `test_gremlin.py`. + +### CS-009: Config endpoints collapse all failures into `Missing Value` + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: API +- Paths: `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:155`, `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:198`, `hugegraph-llm/src/hugegraph_llm/api/exceptions/rag_exceptions.py:33` +- Status: open +- Evidence: `/config/graph`, `/config/llm`, `/config/embedding`, and `/config/rerank` construct `RAGResponse(status_code=res, message="Missing Value")` for all non-success cases. +- Impact: Connection, auth, unsupported provider, and validation failures become the same client-visible message. +- Recommendation: Return structured failure details from config application and map them to accurate HTTP details. +- Test note: Added a `FIXME:` in `test_rag_api.py`. + +### CS-010: GraphRAG/Text2Gremlin API failures are flattened into generic 500s + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: API / test-quality +- Paths: `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:145`, `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:224`, `hugegraph-llm/src/tests/api/test_rag_api.py:164` +- Status: open +- Evidence: Broad `Exception` handlers return one generic detail string; the test suite asserts this behavior for `text2gremlin`. +- Impact: Provider, graph, schema, prompt, and internal errors cannot be distinguished by API callers. +- Recommendation: Preserve stable response shape but expose actionable failure categories. +- Test note: Added a `FIXME:` in `test_rag_api.py`. + +### CS-011: `client_config` partial requests overwrite global graph config + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: API / models / config +- Paths: `hugegraph-llm/src/hugegraph_llm/api/models/rag_requests.py:27`, `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:92` +- Status: open +- Evidence: `GraphConfigRequest` has concrete defaults and `set_graph_config()` writes every field to global `huge_settings` whenever `client_config` exists. +- Impact: A request intended to override one field can clear credentials, graph name, or graphspace for the whole process. +- Recommendation: Make nested fields optional and update only explicitly provided values, or keep request config out of global settings. +- Test note: Added a `FIXME:` in `test_rag_api.py`. + +### CS-012: Unsupported provider types are written into global settings before validation + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: API / models / config +- Paths: `hugegraph-llm/src/hugegraph_llm/api/models/rag_requests.py:106`, `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:163`, `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:188`, `hugegraph-llm/src/hugegraph_llm/config/llm_config.py:29` +- Status: open +- Evidence: Request models use bare `str` for `llm_type` and `reranker_type`; handlers write values to global settings before branch validation. +- Impact: One bad request can poison process-global provider state for subsequent requests. +- Recommendation: Validate provider types with `Literal`/Enum before mutating global config. +- Test note: Added a `FIXME:` in `test_rag_api.py`. + +### CS-013: Property graph extraction stringifies values that importer rejects + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: LLM operator / graph import +- Paths: `hugegraph-llm/src/hugegraph_llm/operators/llm_op/property_graph_extract.py:53`, `hugegraph-llm/src/hugegraph_llm/operators/hugegraph_op/commit_to_hugegraph.py:134`, `hugegraph-llm/src/hugegraph_llm/flows/import_graph_data.py:65` +- Status: open +- Evidence: `filter_item()` converts non-string properties to strings, while `Commit2Graph` enforces schema Python types and skips mismatches. Edge writes can continue and the flow reports success. +- Impact: KG import can partially fail while the UI reports success. +- Recommendation: Preserve schema-typed values or add a schema-aware normalization layer; aggregate and surface import failures. +- Test note: Added `FIXME:` comments in property graph and commit tests. + +### CS-014: Graph/vector dependency failures are treated as empty retrieval + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: nodes / operators +- Paths: `hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/gremlin_execute.py:50`, `hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py:152`, `hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py:423`, `hugegraph-llm/src/hugegraph_llm/nodes/index_node/vector_query_node.py:58` +- Status: open +- Evidence: HugeGraph and vector exceptions are converted to strings, empty lists, or original context. +- Impact: Answer synthesis can proceed as if retrieval found no evidence, producing misleading answers. +- Recommendation: Add structured failure fields and fail fast by default; allow fallback only via explicit mode. +- Test note: Covered by `FIXME:` comments in integration and vector-query tests. + +### CS-015: LiteLLM embedding factory crashes for supported config + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: model provider +- Paths: `hugegraph-llm/src/hugegraph_llm/models/embeddings/init_embedding.py:44`, `hugegraph-llm/src/hugegraph_llm/models/embeddings/litellm.py:30`, `hugegraph-llm/src/hugegraph_llm/config/llm_config.py:32` +- Status: open +- Evidence: `get_embedding()` supports `embedding_type == "litellm"` but constructs `LiteLLMEmbedding` without required `embedding_dimension`. +- Impact: Config-driven LiteLLM embedding initialization fails before retrieval/indexing starts. +- Recommendation: Align factory and class constructor contracts. +- Test note: Added provider factory gap to the test-quality ledger. + +### CS-016: OpenAI wrapper returns provider failures as ordinary model text + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: LLM provider +- Paths: `hugegraph-llm/src/hugegraph_llm/models/llms/openai.py:78`, `hugegraph-llm/src/hugegraph_llm/models/llms/openai.py:116`, `hugegraph-llm/src/hugegraph_llm/models/llms/openai.py:168`, `hugegraph-llm/src/hugegraph_llm/models/llms/openai.py:209`, `hugegraph-llm/src/tests/models/llms/test_openai_client.py:254` +- Status: open +- Evidence: Bad request/auth exceptions are returned or yielded as `"Error: ..."` strings. +- Impact: Flows can treat provider outages as valid LLM output. +- Recommendation: Raise typed provider exceptions and map them at API/flow boundaries. +- Test note: Added a `FIXME:` in `test_openai_client.py`. + +### CS-017: Embedding dimension probing hides real provider failures + +- Priority: P1 +- Module: `hugegraph-llm` +- Layer: embedding provider / vector index +- Paths: `hugegraph-llm/src/hugegraph_llm/models/embeddings/init_embedding.py:68`, `hugegraph-llm/src/hugegraph_llm/models/embeddings/init_embedding.py:82`, `hugegraph-llm/src/hugegraph_llm/models/embeddings/init_embedding.py:98` +- Status: open +- Evidence: Provider probe exceptions are broadly caught and fallback dimensions are silently retained. +- Impact: Auth/network/provider errors can create or reuse vector stores with wrong dimensions. +- Recommendation: Surface probe failures unless a dimension was explicitly configured and validated. +- Test note: No current factory tests cover probe failure. + +### CS-018: `IndexLabel.by()` loses compound-index field order + +- Priority: P2 +- Module: `hugegraph-python-client` +- Layer: schema +- Paths: `hugegraph-python-client/src/pyhugegraph/api/schema_manage/index_label.py:42`, `hugegraph-python-client/src/pyhugegraph/api/schema_manage/index_label.py:47`, `hugegraph-python-client/src/pyhugegraph/api/schema_manage/index_label.py:90` +- Status: open +- Evidence: Fields are stored in a `set`, then converted back to `list`. +- Impact: Compound index field order and duplicate handling become non-deterministic. +- Recommendation: Store ordered input, with explicit ordered de-duplication if needed. +- Test note: Added a `FIXME:` in `test_schema.py`. + +### CS-019: `getVertexByCondition()` accepts `page` but drops next-page token + +- Priority: P2 +- Module: `hugegraph-python-client` +- Layer: client-api +- Paths: `hugegraph-python-client/src/pyhugegraph/api/graph.py:86`, `hugegraph-python-client/src/pyhugegraph/api/graph.py:95`, `hugegraph-python-client/src/pyhugegraph/api/graph.py:100` +- Status: open +- Evidence: Method takes `page` and sends it, but returns only `list[VertexData]`; sibling `getVertexByPage()` returns `(items, next_page)`. +- Impact: Callers cannot page through condition queries. +- Recommendation: Return `(items, next_page)` or remove the `page` parameter. +- Test note: No multi-page condition query test exists. + +### CS-020: Runtime prompt YAML and prompt tests have drifted + +- Priority: P2 +- Module: `hugegraph-llm` +- Layer: config / prompt +- Paths: `hugegraph-llm/src/hugegraph_llm/config/models/base_prompt_config.py:55`, `hugegraph-llm/src/hugegraph_llm/config/prompt_config.py:267`, `hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml:51`, `hugegraph-llm/src/hugegraph_llm/api/models/rag_requests.py:61` +- Status: open +- Evidence: Runtime prompts load from YAML, but tests focus on class constants and fixture examples. Request model defaults also freeze prompt strings at import time. +- Impact: Passing prompt tests do not prove runtime prompt contracts or language-specific YAML behavior. +- Recommendation: Validate runtime-loaded YAML prompt schema/version and resolve defaults at request handling time. +- Test note: Added `FIXME:` comments in prompt tests. + +### CS-021: `.env` sync bypasses Pydantic typing and import has side effects + +- Priority: P2 +- Module: `hugegraph-llm` +- Layer: config +- Paths: `hugegraph-llm/src/hugegraph_llm/config/models/base_config.py:95`, `hugegraph-llm/src/hugegraph_llm/config/models/base_config.py:125`, `hugegraph-llm/src/hugegraph_llm/config/__init__.py:29` +- Status: open +- Evidence: `_sync_env_to_object()` writes raw strings with `setattr`; config import can mutate `os.environ` and create/sync `.env`. +- Impact: Typed fields can become strings and imports are not side-effect free. +- Recommendation: Rebuild/validate settings through Pydantic and move disk/env mutation to explicit initialization. +- Test note: Added a `FIXME:` in `test_config.py`. + +### CS-022: Legacy triples output cannot feed current importer shape + +- Priority: P2 +- Module: `hugegraph-llm` +- Layer: LLM operator / graph import +- Paths: `hugegraph-llm/src/hugegraph_llm/operators/llm_op/info_extract.py:94`, `hugegraph-llm/src/hugegraph_llm/operators/hugegraph_op/commit_to_hugegraph.py:171` +- Status: open +- Evidence: Triples extraction emits `start/end/type`; importer expects `outV/inV/label`. +- Impact: A supported-looking KG extraction mode cannot be imported without an undocumented adapter. +- Recommendation: Add a formal adapter or explicitly deprecate/directly reject this path. +- Test note: No bridge contract test exists. + +### CS-023: Vector recall parameters are lost across flow/node/operator boundaries + +- Priority: P2 +- Module: `hugegraph-llm` +- Layer: flow / node / operator +- Paths: `hugegraph-llm/src/hugegraph_llm/flows/rag_flow_vector_only.py:55`, `hugegraph-llm/src/hugegraph_llm/flows/rag_flow_graph_vector.py:64`, `hugegraph-llm/src/hugegraph_llm/nodes/index_node/vector_query_node.py:42`, `hugegraph-llm/src/hugegraph_llm/operators/index_op/vector_index_query.py:33` +- Status: open +- Evidence: Flows record `topk_return_results` and `vector_dis_threshold`, but node/operator default to `max_items=3` and hard-coded `dis_threshold=2`. +- Impact: API/flow config does not control actual vector retrieval. +- Recommendation: Thread the parameters through one explicit contract and test the flow boundary. +- Test note: Added a `FIXME:` in `test_vector_index_query.py`. + +### CS-024: LiteLLM sync streaming violates `BaseLLM` streaming contract + +- Priority: P2 +- Module: `hugegraph-llm` +- Layer: LLM provider +- Paths: `hugegraph-llm/src/hugegraph_llm/models/llms/base.py:42`, `hugegraph-llm/src/hugegraph_llm/models/llms/litellm.py:111` +- Status: open +- Evidence: Base contract is generator-of-strings, but LiteLLM sync streaming accumulates and returns a plain string while callback payloads differ. +- Impact: Provider swaps can silently break streaming consumers. +- Recommendation: Yield normalized token strings incrementally. +- Test note: No provider streaming contract test exists. + +### CS-025: One `dis_threshold` abstraction has incompatible backend semantics + +- Priority: P2 +- Module: `hugegraph-llm` +- Layer: vector index +- Paths: `hugegraph-llm/src/hugegraph_llm/indices/vector_index/base.py:59`, `hugegraph-llm/src/hugegraph_llm/indices/vector_index/faiss_vector_store.py:76`, `hugegraph-llm/src/hugegraph_llm/indices/vector_index/milvus_vector_store.py:156`, `hugegraph-llm/src/hugegraph_llm/indices/vector_index/qdrant_vector_store.py:57` +- Status: open +- Evidence: Faiss/Milvus use raw L2 distance; Qdrant uses cosine similarity converted to `1 - score`. +- Impact: Same config returns different accept/reject behavior per backend. +- Recommendation: Normalize scoring at the boundary or expose backend-specific threshold types. +- Test note: Added a `FIXME:` in Faiss vector index tests. + +### CS-026: Graph backup can report success with empty `schema.json` + +- Priority: P2 +- Module: `hugegraph-llm` +- Layer: utility / backup +- Paths: `hugegraph-llm/src/hugegraph_llm/utils/hugegraph_utils.py:112`, `hugegraph-llm/src/hugegraph_llm/utils/hugegraph_utils.py:147` +- Status: open +- Evidence: `backup_data()` opens `schema.json`, but `write_backup_file()` writes only a `.groovy` sibling when the payload contains `"schema"`. +- Impact: Backup output can be incomplete while returning success. +- Recommendation: Write both expected artifacts or name the groovy-only artifact accurately. +- Test note: No focused backup artifact test exists. + +### CS-027: `PyHugeClient` creates independent sessions per manager + +- Priority: P3 +- Module: `hugegraph-python-client` +- Layer: transport / lifecycle +- Paths: `hugegraph-python-client/src/pyhugegraph/client.py:40`, `hugegraph-python-client/src/pyhugegraph/client.py:61`, `hugegraph-python-client/src/pyhugegraph/api/common.py:51` +- Status: open +- Evidence: `manager_builder` constructs a new `HGraphSession` for each lazily created manager and `PyHugeClient` has no unified `close()`. +- Impact: Long-lived clients can retain multiple sessions/adapters and leak resources. +- Recommendation: Share one session per client and expose `close()` / context manager support. +- Test note: No lifecycle test exists. + +### CS-028: Text2Gremlin always makes two LLM calls regardless of requested outputs + +- Priority: P3 +- Module: `hugegraph-llm` +- Layer: flow / LLM operator / performance +- Paths: `hugegraph-llm/src/hugegraph_llm/flows/text2gremlin.py:50`, `hugegraph-llm/src/hugegraph_llm/operators/llm_op/gremlin_generate.py:69`, `hugegraph-llm/src/hugegraph_llm/flows/text2gremlin.py:107` +- Status: open +- Evidence: `requested_outputs` filters returned fields, but `GremlinGenerateSynthesize` always calls raw and initialized prompts. +- Impact: Unnecessary latency and token cost for callers requesting only one Gremlin output. +- Recommendation: Let requested outputs drive the execution plan. +- Test note: No call-count/cost contract test exists. + +### CS-029: `get_embeddings_parallel()` launches all batches concurrently + +- Priority: P3 +- Module: `hugegraph-llm` +- Layer: embedding utility / performance +- Paths: `hugegraph-llm/src/hugegraph_llm/utils/embedding_utils.py:36`, `hugegraph-llm/src/hugegraph_llm/utils/embedding_utils.py:53` +- Status: open +- Evidence: The docstring claims semaphore-based concurrency, but implementation creates one task per batch and gathers them all. +- Impact: Large indexing jobs can burst into many provider calls and hit rate/memory/socket limits. +- Recommendation: Add real bounded concurrency with configurable worker count. +- Test note: No peak-concurrency test exists. + +### CS-030: Integration tests reimplement production flows locally + +- Priority: P4 +- Module: `hugegraph-llm` +- Layer: test-quality +- Paths: `hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py:39`, `hugegraph-llm/src/tests/integration/test_rag_pipeline.py:33`, `hugegraph-llm/src/tests/integration/test_kg_construction.py:46` +- Status: open +- Evidence: Tests define local `RAGPipeline`, local document/vector/LLM classes, and local `KGConstructor`. +- Impact: Green integration tests do not validate production flow wiring. +- Recommendation: Use production flows/nodes/operators with deterministic fake LLM/vector/HugeGraph boundaries. +- Test note: Added `FIXME:` comments in all three files. + +### CS-031: Commit2Graph tests mock away core branch behavior + +- Priority: P4 +- Module: `hugegraph-llm` +- Layer: test-quality +- Paths: `hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py:117`, `hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py:72` +- Status: open +- Evidence: Tests patch `init_schema_if_need`, `load_into_graph`, `_handle_graph_creation`, or `_create_property` while claiming to cover graph loading behavior. +- Impact: Core import failure modes are not tested. +- Recommendation: Add contract tests that exercise real branch logic with a test service or focused fake client. +- Test note: Added `FIXME:` comments in commit tests. + +### CS-032: Main `/rag` and `/rag/graph` success contracts are untested + +- Priority: P4 +- Module: `hugegraph-llm` +- Layer: test-quality +- Paths: `hugegraph-llm/src/tests/api/test_rag_api.py:47`, `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:59`, `hugegraph-llm/src/hugegraph_llm/api/rag_api.py:126` +- Status: open +- Evidence: API tests cover config endpoints, one validation error, and one `text2gremlin` failure, not success response shaping. +- Impact: Response filtering and graph recall shape can drift unnoticed. +- Recommendation: Add happy-path HTTP contract tests. +- Test note: Added a `FIXME:` in `test_rag_api.py`. + +### CS-033: Shared HugeGraph fixtures still runtime-skip selected integration tests + +- Priority: P4 +- Module: cross-module +- Layer: test-quality +- Paths: `hugegraph-llm/src/tests/fixtures/hugegraph_service.py:71`, `hugegraph-python-client/src/tests/fixtures/hugegraph_service.py:71`, `docs/quality/test-taxonomy.md:31` +- Status: open +- Evidence: Fixture calls `pytest.skip()` when service is absent and `HUGEGRAPH_REQUIRED` is false, conflicting with the selected Layer B semantics. +- Impact: Selected integration tests can silently disappear. +- Recommendation: Prefer explicit deselection or required-service failure semantics for selected integration gates. +- Test note: Recorded in test-quality ledger. + +### CS-034: Client error tests are false-green + +- Priority: P4 +- Module: `hugegraph-python-client` +- Layer: test-quality +- Paths: `hugegraph-python-client/src/tests/api/test_graph.py:87`, `hugegraph-python-client/src/tests/api/test_graph.py:143`, `hugegraph-python-client/src/tests/api/test_task.py:52`, `hugegraph-python-client/src/tests/api/test_auth.py:85` +- Status: open +- Evidence: Several tests assert only inside `except` blocks and do not fail when no exception is raised. +- Impact: Error-surfacing regressions can pass. +- Recommendation: Use `pytest.raises` / `assertRaises`. +- Test note: Recorded in test-quality ledger. + +### CS-035: Client graph/gremlin integration tests share dirty graph state + +- Priority: P4 +- Module: `hugegraph-python-client` +- Layer: test-quality +- Paths: `hugegraph-python-client/src/tests/api/test_graph.py:33`, `hugegraph-python-client/src/tests/api/test_gremlin.py:58`, `hugegraph-python-client/src/tests/client_utils.py:104` +- Status: open +- Evidence: Tests insert fixed primary-key data and rely on class-level or previous-test cleanup. +- Impact: Assertions become order-dependent and flaky. +- Recommendation: Clear/reseed per test or move to function-scoped isolated fixtures. +- Test note: Added `FIXME:` comments in graph and gremlin tests. + +### CS-036: `GraphsManager.clear_graph_all_data()` version branch lacks direct coverage + +- Priority: P4 +- Module: `hugegraph-python-client` +- Layer: test-quality +- Paths: `hugegraph-python-client/src/pyhugegraph/api/graphs.py:38`, `hugegraph-python-client/src/tests/api/test_graphs.py:50` +- Status: open +- Evidence: The implementation switches between destructive DELETE and graphspace-aware PUT, but tests only perform weak unrelated smoke assertions. +- Impact: Destructive clear semantics can drift without focused coverage. +- Recommendation: Add routing contract tests for legacy and graphspace paths. +- Test note: Recorded in test-quality ledger. + +### CS-037: Provider/backend tests miss contract drift + +- Priority: P4 +- Module: `hugegraph-llm` +- Layer: test-quality +- Paths: `hugegraph-llm/src/tests/models/embeddings/test_ollama_embedding.py:35`, `hugegraph-llm/src/tests/models/llms/test_ollama_client.py:29`, `hugegraph-llm/src/tests/indices/test_faiss_vector_index.py:42` +- Status: open +- Evidence: Some opt-in external tests print without assertions, and vector backend coverage is Faiss-only. +- Impact: LiteLLM factory, provider streaming, Qdrant/Milvus threshold semantics, and bounded embedding concurrency are not protected. +- Recommendation: Add deterministic provider/backend contract tests using fakes/mocks. +- Test note: Added a `FIXME:` in Faiss tests and recorded provider gaps. ## Fixed Style-only Issues -Pending scan results. +None. No style-only source fixes were needed during this scan. ## Deferred or Duplicate Issues -Pending scan results. +- L6 duplicate of CS-030: GraphRAG/RAG/KG test-local fake integration coverage. +- L6 duplicate of CS-031: Commit2Graph helper patching masks real import behavior. +- L2 duplicate of CS-035: client graph/gremlin shared state flakiness. +- L4 duplicate of CS-014: GraphRAG dependency failures hidden by empty/fallback results. diff --git a/.workflow/code-scan/reports/module-map.md b/.workflow/code-scan/reports/module-map.md index 7b0f7685..d7513efe 100644 --- a/.workflow/code-scan/reports/module-map.md +++ b/.workflow/code-scan/reports/module-map.md @@ -4,21 +4,21 @@ | Layer | Paths | Status | Notes | |---|---|---|---| -| Transport/auth/routing | `src/pyhugegraph/client.py`, `src/pyhugegraph/utils/`, `src/pyhugegraph/api/auth.py`, `src/pyhugegraph/api/common.py` | pending | L1 | -| API and structure | `src/pyhugegraph/api/`, `src/pyhugegraph/structure/` | pending | L2 | -| Tests | `src/tests/` | pending | L6 | +| Transport/auth/routing | `src/pyhugegraph/client.py`, `src/pyhugegraph/utils/`, `src/pyhugegraph/api/auth.py`, `src/pyhugegraph/api/common.py` | completed | L1 | +| API and structure | `src/pyhugegraph/api/`, `src/pyhugegraph/structure/` | completed | L2 | +| Tests | `src/tests/` | completed | L6 | ## hugegraph-llm | Layer | Paths | Status | Notes | |---|---|---|---| -| API/config/prompt | `src/hugegraph_llm/api/`, `src/hugegraph_llm/config/`, `src/hugegraph_llm/resources/` | pending | L3 | -| Flows/nodes/operators | `src/hugegraph_llm/flows/`, `src/hugegraph_llm/nodes/`, `src/hugegraph_llm/operators/`, `src/hugegraph_llm/state/` | pending | L4 | -| Indices/models/utils | `src/hugegraph_llm/indices/`, `src/hugegraph_llm/models/`, `src/hugegraph_llm/utils/` | pending | L5 | -| Tests | `src/tests/` | pending | L6 | +| API/config/prompt | `src/hugegraph_llm/api/`, `src/hugegraph_llm/config/`, `src/hugegraph_llm/resources/` | completed | L3 | +| Flows/nodes/operators | `src/hugegraph_llm/flows/`, `src/hugegraph_llm/nodes/`, `src/hugegraph_llm/operators/`, `src/hugegraph_llm/state/` | completed | L4 | +| Indices/models/utils | `src/hugegraph_llm/indices/`, `src/hugegraph_llm/models/`, `src/hugegraph_llm/utils/` | completed | L5 | +| Tests | `src/tests/` | completed | L6 | ## Cross-module | Boundary | Status | Notes | |---|---|---| -| `hugegraph-llm` callers of `pyhugegraph` | pending | L7 | +| `hugegraph-llm` callers of `pyhugegraph` | completed | L7 | diff --git a/.workflow/code-scan/reports/test-quality-ledger.md b/.workflow/code-scan/reports/test-quality-ledger.md index 821c8741..06019be5 100644 --- a/.workflow/code-scan/reports/test-quality-ledger.md +++ b/.workflow/code-scan/reports/test-quality-ledger.md @@ -2,16 +2,57 @@ ## Required FIXME Comments -Pending scan results. +Added specific `FIXME:` comments in these files: + +- `hugegraph-llm/src/hugegraph_llm/api/admin_api.py` +- `hugegraph-llm/src/tests/api/test_rag_api.py` +- `hugegraph-llm/src/tests/config/test_config.py` +- `hugegraph-llm/src/tests/config/test_prompt_config.py` +- `hugegraph-llm/src/tests/models/llms/test_openai_client.py` +- `hugegraph-llm/src/tests/indices/test_faiss_vector_index.py` +- `hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py` +- `hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py` +- `hugegraph-llm/src/tests/operators/llm_op/test_property_graph_extract.py` +- `hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py` +- `hugegraph-llm/src/tests/integration/test_rag_pipeline.py` +- `hugegraph-llm/src/tests/integration/test_kg_construction.py` +- `hugegraph-llm/src/tests/operators/index_op/test_vector_index_query.py` +- `hugegraph-python-client/src/tests/api/test_auth_routing.py` +- `hugegraph-python-client/src/tests/api/test_graph.py` +- `hugegraph-python-client/src/tests/api/test_schema.py` +- `hugegraph-python-client/src/tests/api/test_gremlin.py` ## Weak or Ineffective Tests -Pending scan results. +| ID | Paths | Weakness | +|---|---|---| +| TQ-001 | `test_graph_rag_pipeline.py`, `test_rag_pipeline.py`, `test_kg_construction.py` | Local stand-ins replace production flows/classes. | +| TQ-002 | `test_commit_to_hugegraph.py`, `test_commit_to_hugegraph_load_into_graph.py` | Helper patching bypasses branchy graph import logic. | +| TQ-003 | `test_rag_api.py` | Missing `/rag` and `/rag/graph` happy-path response-shaping tests. | +| TQ-004 | `test_graph.py`, `test_gremlin.py` | Shared graph state and fixed primary keys make tests order-dependent. | +| TQ-005 | `test_graph.py`, `test_task.py`, `test_auth.py` | Error assertions inside `except` blocks can pass when no exception occurs. | +| TQ-006 | `test_ollama_embedding.py`, `test_ollama_client.py` | Print-only external checks have no assertions. | +| TQ-007 | `test_faiss_vector_index.py` | Backend abstraction has only Faiss coverage. | ## Missing Coverage Around Core Functions -Pending scan results. +- `admin_http_api` log path validation. +- `HGraphSession.resolve()` with base URL path prefixes. +- `ResponseValidation` success-response malformed JSON. +- `GremlinManager.exec()` typed error propagation. +- `GraphManager` query filter URL encoding. +- `PropertyKey` advanced builder payload. +- `IndexLabel` multi-field order. +- `Commit2Graph.load_into_graph()` partial-failure behavior. +- `PropertyGraphExtract -> Commit2Graph` typed round trip. +- `GraphQueryNode` and `VectorQueryNode` dependency failure propagation. +- `VectorQueryNode` top-k and threshold parameter pass-through. +- `LiteLLMEmbedding` factory construction. +- OpenAI/LiteLLM provider failure and streaming contracts. +- `get_embeddings_parallel()` peak concurrency. +- `write_backup_file()` backup artifact contents. ## Tests Reviewed and Accepted -Pending scan results. +- `hugegraph-python-client/src/tests/api/test_response_validation.py` was run by L2 and passed: `uv run pytest hugegraph-python-client/src/tests/api/test_response_validation.py -q`. +- L5 ran a targeted models/indices test set and reported `52 passed, 3 skipped`. diff --git a/docs/plans/2026-05-31-hugegraph-ai-code-scan.md b/docs/plans/2026-05-31-hugegraph-ai-code-scan.md index 7a5be169..2824a7f5 100644 --- a/docs/plans/2026-05-31-hugegraph-ai-code-scan.md +++ b/docs/plans/2026-05-31-hugegraph-ai-code-scan.md @@ -57,12 +57,12 @@ Allowed source/test edits: ## Global Execution Rules -- [ ] Do not edit behavior-changing production logic. -- [ ] Record every logic/design/performance issue in `.workflow/code-scan/reports/issues.md`. -- [ ] Update `.workflow/code-scan/code-scan-state.json` after each coherent scan slice. -- [ ] Update the matching checkpoint after each lane. -- [ ] Add `FIXME:` comments for missing/ineffective core tests where required by the spec. -- [ ] Commit after setup and after each coherent large sub-slice. +- [x] Do not edit behavior-changing production logic. +- [x] Record every logic/design/performance issue in `.workflow/code-scan/reports/issues.md`. +- [x] Update `.workflow/code-scan/code-scan-state.json` after each coherent scan slice. +- [x] Update the matching checkpoint after each lane. +- [x] Add `FIXME:` comments for missing/ineffective core tests where required by the spec. +- [x] Commit after setup and after each coherent large sub-slice. ## T0: Setup and Scan Ledger @@ -101,7 +101,7 @@ Result: reused document style, restartable ledger structure, strict boundary wor Create `.workflow/code-scan/` artifacts and initialize state with current branch, SHA, scan lanes, and empty issue counters. -- [ ] **Step T0.4: Commit setup slice** +- [x] **Step T0.4: Commit setup slice** Commands: @@ -112,6 +112,8 @@ git commit -m "docs(code-scan): add core module audit plan" -m "- define scoped - capture lane-based execution checkpoints" ``` +Result: committed as `860b2a49 docs(code-scan): add core module audit plan`. + ## T1: Parallel Client Scan **Files:** @@ -121,7 +123,7 @@ git commit -m "docs(code-scan): add core module audit plan" -m "- define scoped - Update: `.workflow/code-scan/reports/module-map.md` - Possible FIXME comments: `hugegraph-python-client/src/tests/**/*.py` -- [ ] **Step T1.1: Scan transport/auth/routing** +- [x] **Step T1.1: Scan transport/auth/routing** Review: @@ -134,7 +136,7 @@ hugegraph-python-client/src/pyhugegraph/api/common.py Focus: request construction, auth/session boundaries, URL routing, error propagation, timeout/retry behavior, exception semantics, and test coverage effectiveness. -- [ ] **Step T1.2: Scan graph/schema/gremlin APIs and structures** +- [x] **Step T1.2: Scan graph/schema/gremlin APIs and structures** Review: @@ -146,10 +148,12 @@ hugegraph-python-client/src/tests/api/ Focus: API route correctness, response envelope parsing, schema/graph/gremlin semantics, mutation safety, data model drift, and weak test assertions. -- [ ] **Step T1.3: Synthesize client findings** +- [x] **Step T1.3: Synthesize client findings** Deduplicate client issues, assign P0-P5, update both client checkpoints, and commit the client scan slice. +Result: client findings were synthesized into `CS-002` through `CS-009`, `CS-018`, `CS-019`, and `CS-027`, with test-quality gaps recorded in `CS-034` through `CS-036`. + ## T2: Parallel hugegraph-llm Scan **Files:** @@ -160,7 +164,7 @@ Deduplicate client issues, assign P0-P5, update both client checkpoints, and com - Update: `.workflow/code-scan/reports/module-map.md` - Possible FIXME comments: `hugegraph-llm/src/tests/**/*.py` -- [ ] **Step T2.1: Scan API/models/config/prompt layer** +- [x] **Step T2.1: Scan API/models/config/prompt layer** Review: @@ -174,7 +178,7 @@ hugegraph-llm/src/tests/config/ Focus: public request/response contracts, config precedence, prompt contract stability, error mapping, and test truthfulness. -- [ ] **Step T2.2: Scan flows/nodes/operators** +- [x] **Step T2.2: Scan flows/nodes/operators** Review: @@ -189,7 +193,7 @@ hugegraph-llm/src/tests/integration/ Focus: GraphRAG/KG/Text2Gremlin boundaries, mutable state, error propagation, external service handling, duplicated logic, and pipeline tests that mock away behavior. -- [ ] **Step T2.3: Scan indices/models/utils/performance** +- [x] **Step T2.3: Scan indices/models/utils/performance** Review: @@ -203,10 +207,12 @@ hugegraph-llm/src/tests/models/ Focus: provider wrapper semantics, vector store failure behavior, embedding/reranker assumptions, unbounded memory/network loops, and fallback correctness. -- [ ] **Step T2.4: Synthesize hugegraph-llm findings** +- [x] **Step T2.4: Synthesize hugegraph-llm findings** Deduplicate LLM issues, assign P0-P5, update all LLM checkpoints, and commit the LLM scan slice. +Result: LLM findings were synthesized into `CS-001`, `CS-010` through `CS-017`, `CS-020` through `CS-026`, `CS-028`, `CS-029`, and `CS-030` through `CS-033`/`CS-037`. + ## T3: Cross-module Contract and Test-quality Synthesis **Files:** @@ -216,15 +222,15 @@ Deduplicate LLM issues, assign P0-P5, update all LLM checkpoints, and commit the - Update: `.workflow/code-scan/reports/test-quality-ledger.md` - Update: `.workflow/code-scan/reports/final-code-scan-report.md` -- [ ] **Step T3.1: Cross-check pyhugegraph callers from hugegraph-llm** +- [x] **Step T3.1: Cross-check pyhugegraph callers from hugegraph-llm** Search and inspect all `pyhugegraph` imports/usages in `hugegraph-llm`, then verify caller assumptions against client response/data structures. -- [ ] **Step T3.2: Review all FIXME candidates** +- [x] **Step T3.2: Review all FIXME candidates** Confirm each required `FIXME:` is present, specific, and tied to core behavior. Remove or rewrite vague comments. -- [ ] **Step T3.3: Produce final report** +- [x] **Step T3.3: Produce final report** Write `.workflow/code-scan/reports/final-code-scan-report.md` with: @@ -240,7 +246,7 @@ Verification Commands Recommended Next Fix Plan ``` -- [ ] **Step T3.4: Verify and final commit** +- [x] **Step T3.4: Verify and final commit** Run the narrowest available verification for touched files. At minimum: diff --git a/hugegraph-llm/src/hugegraph_llm/api/admin_api.py b/hugegraph-llm/src/hugegraph_llm/api/admin_api.py index 016427f1..d71330b7 100644 --- a/hugegraph-llm/src/hugegraph_llm/api/admin_api.py +++ b/hugegraph-llm/src/hugegraph_llm/api/admin_api.py @@ -37,6 +37,8 @@ def admin_http_api(router: APIRouter, log_stream): message="Invalid admin_token", ) ) + # FIXME: add an API contract test that rejects path traversal and + # absolute log paths before this value reaches the log stream. log_path = os.path.join("logs", req.log_file) # Create a StreamingResponse that reads from the log stream generator diff --git a/hugegraph-llm/src/tests/api/test_rag_api.py b/hugegraph-llm/src/tests/api/test_rag_api.py index 336216fb..c06a52ff 100644 --- a/hugegraph-llm/src/tests/api/test_rag_api.py +++ b/hugegraph-llm/src/tests/api/test_rag_api.py @@ -25,6 +25,13 @@ from hugegraph_llm.api.rag_api import rag_http_api pytestmark = pytest.mark.contract +# FIXME: add negative-path tests for each /config/* endpoint that assert +# provider/auth/connection failures surface distinct error details. +# FIXME: add happy-path HTTP contract tests for /rag and /rag/graph response +# shaping, output-flag filtering, and request-scoped graph config behavior. +# FIXME: distinguish graph/provider dependency failures from programmer errors +# instead of asserting one generic unexpected-error response for all failures. + def _make_test_client(**overrides): callbacks = { diff --git a/hugegraph-llm/src/tests/config/test_config.py b/hugegraph-llm/src/tests/config/test_config.py index b5569a8f..e52d912a 100644 --- a/hugegraph-llm/src/tests/config/test_config.py +++ b/hugegraph-llm/src/tests/config/test_config.py @@ -23,6 +23,9 @@ import pytest pytestmark = pytest.mark.unit +# FIXME: add config tests proving .env sync preserves typed numeric/boolean +# fields and that imports do not create or mutate files implicitly. + class TestConfig(unittest.TestCase): def test_config(self): diff --git a/hugegraph-llm/src/tests/config/test_prompt_config.py b/hugegraph-llm/src/tests/config/test_prompt_config.py index c300a551..01d15910 100644 --- a/hugegraph-llm/src/tests/config/test_prompt_config.py +++ b/hugegraph-llm/src/tests/config/test_prompt_config.py @@ -27,6 +27,11 @@ from hugegraph_llm.operators.llm_op.property_graph_extract import PropertyGraphE pytestmark = pytest.mark.contract +# FIXME: add contract coverage for runtime-loaded config_prompt.yaml, not only +# PromptConfig class constants and prompt_examples.json fixtures. +# FIXME: verify omitted API prompt fields resolve the current PromptConfig +# object instead of import-time default prompt strings. + def _json_objects_after_marker(prompt, marker): start = prompt.index(marker) + len(marker) diff --git a/hugegraph-llm/src/tests/indices/test_faiss_vector_index.py b/hugegraph-llm/src/tests/indices/test_faiss_vector_index.py index 770a0c79..9ab03cfa 100644 --- a/hugegraph-llm/src/tests/indices/test_faiss_vector_index.py +++ b/hugegraph-llm/src/tests/indices/test_faiss_vector_index.py @@ -25,6 +25,9 @@ from pprint import pprint from hugegraph_llm.indices.vector_index.faiss_vector_store import FaissVectorIndex from hugegraph_llm.models.embeddings.ollama import OllamaEmbedding +# FIXME: add cross-backend vector-store contract tests for Qdrant/Milvus/Faiss +# threshold semantics instead of covering only the Faiss implementation. + class TestVectorIndex(unittest.TestCase): def setUp(self): diff --git a/hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py b/hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py index 243963c3..53e27055 100644 --- a/hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py +++ b/hugegraph-llm/src/tests/integration/test_graph_rag_pipeline.py @@ -23,6 +23,9 @@ from unittest.mock import MagicMock from tests.utils.mock import MockEmbedding +# FIXME: replace the local RAGPipeline stand-in with a smoke test that +# instantiates production GraphRAG flows and verifies real node wiring. + class BaseLLM: def generate(self, prompt, **kwargs): diff --git a/hugegraph-llm/src/tests/integration/test_kg_construction.py b/hugegraph-llm/src/tests/integration/test_kg_construction.py index daa7b191..857ca811 100644 --- a/hugegraph-llm/src/tests/integration/test_kg_construction.py +++ b/hugegraph-llm/src/tests/integration/test_kg_construction.py @@ -29,6 +29,9 @@ from src.tests.test_utils import ( with_mock_openai_client, ) +# FIXME: cover the production KG extraction/import path with deterministic LLM +# fakes instead of defining a test-local KGConstructor. + # Create mock classes to replace missing modules class OpenAILLM: diff --git a/hugegraph-llm/src/tests/integration/test_rag_pipeline.py b/hugegraph-llm/src/tests/integration/test_rag_pipeline.py index bb5e4364..59dd8f2b 100644 --- a/hugegraph-llm/src/tests/integration/test_rag_pipeline.py +++ b/hugegraph-llm/src/tests/integration/test_rag_pipeline.py @@ -28,6 +28,9 @@ from src.tests.test_utils import ( ) from tests.utils.mock import VectorIndex +# FIXME: stop gating this local-only test behind SKIP_EXTERNAL_SERVICES, or +# replace the local stand-ins with production loader/splitter/retrieval paths. + # 创建模拟类，替代缺失的模块 class Document: diff --git a/hugegraph-llm/src/tests/models/llms/test_openai_client.py b/hugegraph-llm/src/tests/models/llms/test_openai_client.py index cee6e9e0..b0793e83 100644 --- a/hugegraph-llm/src/tests/models/llms/test_openai_client.py +++ b/hugegraph-llm/src/tests/models/llms/test_openai_client.py @@ -25,6 +25,9 @@ from hugegraph_llm.models.llms.openai import OpenAIClient pytestmark = pytest.mark.contract +# FIXME: replace tests that accept provider errors as model text with sync, +# async, and streaming failure-propagation contract tests. + class TestOpenAIClient(unittest.TestCase): def setUp(self): diff --git a/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py b/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py index fbd9e3a5..6876b6e2 100644 --- a/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py +++ b/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph.py @@ -26,6 +26,9 @@ from hugegraph_llm.operators.hugegraph_op.commit_to_hugegraph import Commit2Grap pytestmark = [pytest.mark.unit] +# FIXME: add a contract test that exercises real load_into_graph failure +# branches instead of only asserting patched helper call counts. + class TestCommit2Graph(unittest.TestCase): def setUp(self): diff --git a/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py b/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py index 6605bec2..e9b6d803 100644 --- a/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py +++ b/hugegraph-llm/src/tests/operators/hugegraph_op/test_commit_to_hugegraph_load_into_graph.py @@ -26,6 +26,9 @@ from hugegraph_llm.operators.llm_op.property_graph_extract import PropertyGraphE pytestmark = [pytest.mark.unit] +# FIXME: cover the extract -> commit round trip and assert that vertex type +# failures stop edge writes and surface an explicit import failure. + class TestCommit2GraphLoadIntoGraph(unittest.TestCase): def setUp(self): diff --git a/hugegraph-llm/src/tests/operators/index_op/test_vector_index_query.py b/hugegraph-llm/src/tests/operators/index_op/test_vector_index_query.py index c9bd67b4..f52afdb7 100644 --- a/hugegraph-llm/src/tests/operators/index_op/test_vector_index_query.py +++ b/hugegraph-llm/src/tests/operators/index_op/test_vector_index_query.py @@ -22,6 +22,9 @@ from unittest.mock import MagicMock, patch from hugegraph_llm.operators.index_op.vector_index_query import VectorIndexQuery +# FIXME: add a flow-to-operator contract test proving topk and +# vector_dis_threshold are passed through instead of hard-coded. + class TestVectorIndexQuery(unittest.TestCase): def setUp(self): diff --git a/hugegraph-llm/src/tests/operators/llm_op/test_property_graph_extract.py b/hugegraph-llm/src/tests/operators/llm_op/test_property_graph_extract.py index 9a5b09f7..df27c868 100644 --- a/hugegraph-llm/src/tests/operators/llm_op/test_property_graph_extract.py +++ b/hugegraph-llm/src/tests/operators/llm_op/test_property_graph_extract.py @@ -34,6 +34,9 @@ from hugegraph_llm.operators.llm_op.property_graph_extract import ( pytestmark = pytest.mark.contract +# FIXME: add a property-graph extraction to Commit2Graph contract test that +# preserves schema-typed values instead of stringifying numeric/date fields. + class TestPropertyGraphExtract(unittest.TestCase): def setUp(self): diff --git a/hugegraph-python-client/src/tests/api/test_auth_routing.py b/hugegraph-python-client/src/tests/api/test_auth_routing.py index 1fcd5a3d..5ee0a40b 100644 --- a/hugegraph-python-client/src/tests/api/test_auth_routing.py +++ b/hugegraph-python-client/src/tests/api/test_auth_routing.py @@ -22,6 +22,9 @@ from pyhugegraph.api.auth import AuthManager pytestmark = pytest.mark.contract +# FIXME: cover real HGraphSession.resolve() with URL prefixes and auth request +# bodies; this DummySession duplicates production routing behavior. + class DummyCfg: def __init__(self, url, graphspace, gs_supported, graph_name): diff --git a/hugegraph-python-client/src/tests/api/test_graph.py b/hugegraph-python-client/src/tests/api/test_graph.py index 4c93fe58..1c402dcd 100644 --- a/hugegraph-python-client/src/tests/api/test_graph.py +++ b/hugegraph-python-client/src/tests/api/test_graph.py @@ -24,6 +24,9 @@ from ..client_utils import ClientUtils pytestmark = [pytest.mark.integration, pytest.mark.hugegraph] +# FIXME: isolate graph state per test case; current fixed primary-key fixtures +# and class-level cleanup make exact-count assertions order-dependent. + class TestGraphManager(unittest.TestCase): client = None @@ -74,6 +77,8 @@ class TestGraphManager(unittest.TestCase): def test_get_vertex_by_page(self): self.graph.addVertex("person", {"name": "Alice", "age": 20}) self.graph.addVertex("person", {"name": "Bob", "age": 23}) + # FIXME: destructure (items, next_page) and assert vertex contents; + # len(tuple) only proves the method returned two values. vertices = self.graph.getVertexByPage("person", 1) self.assertEqual(len(vertices), 2) diff --git a/hugegraph-python-client/src/tests/api/test_gremlin.py b/hugegraph-python-client/src/tests/api/test_gremlin.py index 1eb4a21d..9705caaa 100644 --- a/hugegraph-python-client/src/tests/api/test_gremlin.py +++ b/hugegraph-python-client/src/tests/api/test_gremlin.py @@ -26,6 +26,11 @@ from ..client_utils import ClientUtils pytestmark = [pytest.mark.integration, pytest.mark.hugegraph] +# FIXME: assert auth/transport/5xx failures keep their original exception +# types; current tests only exercise query errors mapped to NotFoundError. +# FIXME: clear graph state per test case; setUp() repopulates fixed primary-key +# fixtures and currently depends on prior tests to clean up. + class TestGremlin(unittest.TestCase): client = None diff --git a/hugegraph-python-client/src/tests/api/test_schema.py b/hugegraph-python-client/src/tests/api/test_schema.py index fa1343bb..5c5b2148 100644 --- a/hugegraph-python-client/src/tests/api/test_schema.py +++ b/hugegraph-python-client/src/tests/api/test_schema.py @@ -24,6 +24,9 @@ from ..client_utils import ClientUtils pytestmark = [pytest.mark.integration, pytest.mark.hugegraph] +# FIXME: add schema builder contract tests proving calc*/userdata survive +# property key create() and multi-field index labels preserve field order. + class TestSchemaManager(unittest.TestCase): client = None
