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 860b2a4923199d190c625641bdcabec1ecc72fd1 Author: imbajin <[email protected]> AuthorDate: Sun May 31 11:14:56 2026 +0800 docs(code-scan): add core module audit plan - define scoped P0-P5 code logic scan design - initialize restartable code-scan ledger - capture lane-based execution checkpoints --- .workflow/code-scan/README.md | 20 ++ .workflow/code-scan/checkpoints/00-setup.md | 38 +++ .../code-scan/checkpoints/01-client-transport.md | 18 ++ .../checkpoints/02-client-api-structure.md | 17 ++ .../code-scan/checkpoints/03-llm-api-config.md | 19 ++ .../code-scan/checkpoints/04-llm-flow-operator.md | 20 ++ .../code-scan/checkpoints/05-llm-index-model.md | 19 ++ .workflow/code-scan/checkpoints/06-test-quality.md | 16 ++ .workflow/code-scan/checkpoints/07-synthesis.md | 15 ++ .workflow/code-scan/code-scan-state.json | 60 +++++ .workflow/code-scan/reports/issues.md | 15 ++ .workflow/code-scan/reports/module-map.md | 24 ++ .workflow/code-scan/reports/test-quality-ledger.md | 17 ++ docs/plans/2026-05-31-hugegraph-ai-code-scan.md | 254 +++++++++++++++++++++ .../2026-05-31-hugegraph-ai-code-scan-design.md | 165 +++++++++++++ 15 files changed, 717 insertions(+) diff --git a/.workflow/code-scan/README.md b/.workflow/code-scan/README.md new file mode 100644 index 00000000..35211108 --- /dev/null +++ b/.workflow/code-scan/README.md @@ -0,0 +1,20 @@ +# Code Scan Ledger + +This directory tracks the 2026-05-31 code logic/design scan for: + +- `hugegraph-llm` +- `hugegraph-python-client` + +It is separate from `.workflow/quality-program/` because this scan records issues first and does not implement behavior-changing fixes. + +## Rules + +- Record logic/design/performance issues in `reports/issues.md`. +- Add `FIXME:` comments only for missing or ineffective tests around core behavior. +- Keep checkpoint files current after each scan lane. +- Commit after setup and after each coherent large sub-slice. + +## Primary References + +- `docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md` +- `docs/plans/2026-05-31-hugegraph-ai-code-scan.md` diff --git a/.workflow/code-scan/checkpoints/00-setup.md b/.workflow/code-scan/checkpoints/00-setup.md new file mode 100644 index 00000000..42a19dd2 --- /dev/null +++ b/.workflow/code-scan/checkpoints/00-setup.md @@ -0,0 +1,38 @@ +# T0 Setup Checkpoint + +## Repository State + +- CWD: `/Users/imbajin/github/graph/ai` +- Branch: `goal-test` +- Start SHA: `d16db33c5509647afccae588c46c0b0767adbb76` +- Existing unrelated untracked path observed before edits: `.workflow/pr68-review/` + +## Guidance Read + +- `AGENTS.md` +- `hugegraph-llm/AGENTS.md` +- `rules/README.md` +- `docs/specs/2026-05-31-hugegraph-ai-quality-program-design.md` +- `docs/plans/2026-05-31-hugegraph-ai-quality-program.md` + +## Boundary Decision + +This scan covers only: + +- `hugegraph-llm/src/hugegraph_llm/` +- `hugegraph-llm/src/tests/` +- `hugegraph-python-client/src/pyhugegraph/` +- `hugegraph-python-client/src/tests/` + +It does not implement logic/design fixes during the scan. It records them as findings. + +## Initial TODO Status + +- T0.1 guidance read: done +- T0.2 prior quality docs read: done +- T0.3 code-scan ledger: done +- T0.4 setup commit: pending + +## Next Checkpoint + +Dispatch client and LLM scan lanes after committing the setup slice. diff --git a/.workflow/code-scan/checkpoints/01-client-transport.md b/.workflow/code-scan/checkpoints/01-client-transport.md new file mode 100644 index 00000000..8f2833a6 --- /dev/null +++ b/.workflow/code-scan/checkpoints/01-client-transport.md @@ -0,0 +1,18 @@ +# T1 Client Transport Checkpoint + +Status: pending + +## Scope + +- `hugegraph-python-client/src/pyhugegraph/client.py` +- `hugegraph-python-client/src/pyhugegraph/utils/` +- `hugegraph-python-client/src/pyhugegraph/api/auth.py` +- `hugegraph-python-client/src/pyhugegraph/api/common.py` + +## Findings + +Pending. + +## Test-quality Notes + +Pending. diff --git a/.workflow/code-scan/checkpoints/02-client-api-structure.md b/.workflow/code-scan/checkpoints/02-client-api-structure.md new file mode 100644 index 00000000..b565e30a --- /dev/null +++ b/.workflow/code-scan/checkpoints/02-client-api-structure.md @@ -0,0 +1,17 @@ +# T1 Client API and Structure Checkpoint + +Status: pending + +## Scope + +- `hugegraph-python-client/src/pyhugegraph/api/` +- `hugegraph-python-client/src/pyhugegraph/structure/` +- `hugegraph-python-client/src/tests/api/` + +## Findings + +Pending. + +## Test-quality Notes + +Pending. diff --git a/.workflow/code-scan/checkpoints/03-llm-api-config.md b/.workflow/code-scan/checkpoints/03-llm-api-config.md new file mode 100644 index 00000000..2848d20b --- /dev/null +++ b/.workflow/code-scan/checkpoints/03-llm-api-config.md @@ -0,0 +1,19 @@ +# T2 LLM API and Config Checkpoint + +Status: pending + +## Scope + +- `hugegraph-llm/src/hugegraph_llm/api/` +- `hugegraph-llm/src/hugegraph_llm/config/` +- `hugegraph-llm/src/hugegraph_llm/resources/` +- `hugegraph-llm/src/tests/api/` +- `hugegraph-llm/src/tests/config/` + +## Findings + +Pending. + +## Test-quality Notes + +Pending. diff --git a/.workflow/code-scan/checkpoints/04-llm-flow-operator.md b/.workflow/code-scan/checkpoints/04-llm-flow-operator.md new file mode 100644 index 00000000..74b6f062 --- /dev/null +++ b/.workflow/code-scan/checkpoints/04-llm-flow-operator.md @@ -0,0 +1,20 @@ +# T2 LLM Flow and Operator Checkpoint + +Status: pending + +## Scope + +- `hugegraph-llm/src/hugegraph_llm/flows/` +- `hugegraph-llm/src/hugegraph_llm/nodes/` +- `hugegraph-llm/src/hugegraph_llm/operators/` +- `hugegraph-llm/src/hugegraph_llm/state/` +- `hugegraph-llm/src/tests/operators/` +- `hugegraph-llm/src/tests/integration/` + +## Findings + +Pending. + +## Test-quality Notes + +Pending. diff --git a/.workflow/code-scan/checkpoints/05-llm-index-model.md b/.workflow/code-scan/checkpoints/05-llm-index-model.md new file mode 100644 index 00000000..5ff56c22 --- /dev/null +++ b/.workflow/code-scan/checkpoints/05-llm-index-model.md @@ -0,0 +1,19 @@ +# T2 LLM Index and Model Checkpoint + +Status: pending + +## Scope + +- `hugegraph-llm/src/hugegraph_llm/indices/` +- `hugegraph-llm/src/hugegraph_llm/models/` +- `hugegraph-llm/src/hugegraph_llm/utils/` +- `hugegraph-llm/src/tests/indices/` +- `hugegraph-llm/src/tests/models/` + +## Findings + +Pending. + +## Test-quality Notes + +Pending. diff --git a/.workflow/code-scan/checkpoints/06-test-quality.md b/.workflow/code-scan/checkpoints/06-test-quality.md new file mode 100644 index 00000000..2857885f --- /dev/null +++ b/.workflow/code-scan/checkpoints/06-test-quality.md @@ -0,0 +1,16 @@ +# T3 Test-quality Checkpoint + +Status: pending + +## Scope + +- `hugegraph-llm/src/tests/` +- `hugegraph-python-client/src/tests/` + +## FIXME Candidates + +Pending. + +## Ineffective Test Patterns + +Pending. diff --git a/.workflow/code-scan/checkpoints/07-synthesis.md b/.workflow/code-scan/checkpoints/07-synthesis.md new file mode 100644 index 00000000..1de61fa6 --- /dev/null +++ b/.workflow/code-scan/checkpoints/07-synthesis.md @@ -0,0 +1,15 @@ +# T3 Synthesis Checkpoint + +Status: pending + +## Cross-module Contract Review + +Pending. + +## Deduplication Notes + +Pending. + +## Final Report Status + +Pending. diff --git a/.workflow/code-scan/code-scan-state.json b/.workflow/code-scan/code-scan-state.json new file mode 100644 index 00000000..b94e4343 --- /dev/null +++ b/.workflow/code-scan/code-scan-state.json @@ -0,0 +1,60 @@ +{ + "current_task": "T0", + "repo_sha_start": "d16db33c5509647afccae588c46c0b0767adbb76", + "branch": "goal-test", + "started_at_utc": "2026-05-31T03:13:05Z", + "modules": [ + "hugegraph-llm", + "hugegraph-python-client" + ], + "lanes": { + "L1": "client transport/auth/routing", + "L2": "client graph/schema/gremlin APIs and structures", + "L3": "llm API/models/config/prompt", + "L4": "llm flows/nodes/operators", + "L5": "llm indices/models/utils/performance", + "L6": "test effectiveness", + "L7": "cross-module synthesis" + }, + "tasks_completed": [ + "T0.1", + "T0.2", + "T0.3" + ], + "checkpoints_completed": [], + "issue_counts": { + "P0": 0, + "P1": 0, + "P2": 0, + "P3": 0, + "P4": 0, + "P5": 0 + }, + "files_touched": [ + "docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md", + "docs/plans/2026-05-31-hugegraph-ai-code-scan.md", + ".workflow/code-scan/README.md", + ".workflow/code-scan/code-scan-state.json", + ".workflow/code-scan/checkpoints/00-setup.md", + ".workflow/code-scan/checkpoints/01-client-transport.md", + ".workflow/code-scan/checkpoints/02-client-api-structure.md", + ".workflow/code-scan/checkpoints/03-llm-api-config.md", + ".workflow/code-scan/checkpoints/04-llm-flow-operator.md", + ".workflow/code-scan/checkpoints/05-llm-index-model.md", + ".workflow/code-scan/checkpoints/06-test-quality.md", + ".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" + ], + "style_only_fixes": [], + "fixme_comments_added": [], + "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" + ], + "next_recommended_action": "Commit setup slice, then dispatch parallel scan lanes" +} diff --git a/.workflow/code-scan/reports/issues.md b/.workflow/code-scan/reports/issues.md new file mode 100644 index 00000000..d7fd2958 --- /dev/null +++ b/.workflow/code-scan/reports/issues.md @@ -0,0 +1,15 @@ +# Code Scan Issues + +Issue IDs use `CS-NNN`. Priorities are P0 highest through P5 lowest. + +## Open Issues + +Pending scan results. + +## Fixed Style-only Issues + +Pending scan results. + +## Deferred or Duplicate Issues + +Pending scan results. diff --git a/.workflow/code-scan/reports/module-map.md b/.workflow/code-scan/reports/module-map.md new file mode 100644 index 00000000..7b0f7685 --- /dev/null +++ b/.workflow/code-scan/reports/module-map.md @@ -0,0 +1,24 @@ +# Module Scan Map + +## hugegraph-python-client + +| 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 | + +## 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 | + +## Cross-module + +| Boundary | Status | Notes | +|---|---|---| +| `hugegraph-llm` callers of `pyhugegraph` | pending | L7 | diff --git a/.workflow/code-scan/reports/test-quality-ledger.md b/.workflow/code-scan/reports/test-quality-ledger.md new file mode 100644 index 00000000..821c8741 --- /dev/null +++ b/.workflow/code-scan/reports/test-quality-ledger.md @@ -0,0 +1,17 @@ +# Test-quality Ledger + +## Required FIXME Comments + +Pending scan results. + +## Weak or Ineffective Tests + +Pending scan results. + +## Missing Coverage Around Core Functions + +Pending scan results. + +## Tests Reviewed and Accepted + +Pending scan results. diff --git a/docs/plans/2026-05-31-hugegraph-ai-code-scan.md b/docs/plans/2026-05-31-hugegraph-ai-code-scan.md new file mode 100644 index 00000000..7a5be169 --- /dev/null +++ b/docs/plans/2026-05-31-hugegraph-ai-code-scan.md @@ -0,0 +1,254 @@ +# HugeGraph AI Code Logic Scan Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: use parallel reviewer lanes for independent scan areas. Steps use checkbox (`- [ ]`) syntax for tracking. Behavior-changing edits are forbidden during this plan; record those as findings instead. + +**Goal:** Scan all code in `hugegraph-llm` and `hugegraph-python-client` for logic, design, maintainability, performance, and test-effectiveness problems, then produce a prioritized P0-P5 report. + +**Architecture:** Maintain a restartable `.workflow/code-scan/` ledger, dispatch independent reviewer lanes, synthesize overlapping findings, add `FIXME:` comments only for ineffective core test coverage, and commit coherent scan slices. + +**Tech Stack:** Python, uv workspace, pytest, ruff, pyhugegraph, hugegraph-llm, FastAPI, vector stores, LLM provider wrappers. + +--- + +## Source Spec + +Implement from: + +- `docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md` + +Reference only for style and boundary management: + +- `docs/specs/2026-05-31-hugegraph-ai-quality-program-design.md` +- `docs/plans/2026-05-31-hugegraph-ai-quality-program.md` +- `AGENTS.md` +- `hugegraph-llm/AGENTS.md` +- `rules/README.md` + +## File Structure + +Create or modify only these scan artifacts unless a style-only or FIXME-only edit is required: + +```text +docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md +docs/plans/2026-05-31-hugegraph-ai-code-scan.md +.workflow/code-scan/ + README.md + code-scan-state.json + checkpoints/ + 00-setup.md + 01-client-transport.md + 02-client-api-structure.md + 03-llm-api-config.md + 04-llm-flow-operator.md + 05-llm-index-model.md + 06-test-quality.md + 07-synthesis.md + reports/ + issues.md + module-map.md + test-quality-ledger.md + final-code-scan-report.md +``` + +Allowed source/test edits: + +- Style, typo, or comment corrections that cannot affect execution. +- `FIXME:` comments marking ineffective or missing core test coverage. + +## 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. + +## T0: Setup and Scan Ledger + +**Files:** +- Create: `.workflow/code-scan/README.md` +- Create: `.workflow/code-scan/code-scan-state.json` +- Create: `.workflow/code-scan/checkpoints/00-setup.md` +- Create: `.workflow/code-scan/reports/issues.md` +- Create: `.workflow/code-scan/reports/module-map.md` +- Create: `.workflow/code-scan/reports/test-quality-ledger.md` + +- [x] **Step T0.1: Read mandatory guidance** + +Commands: + +```bash +sed -n '1,240p' AGENTS.md +sed -n '1,240p' hugegraph-llm/AGENTS.md +sed -n '1,260p' rules/README.md +``` + +Result: root and module rules confirm the scan must stay scoped to `hugegraph-llm` and `hugegraph-python-client`, avoid lower-frequency modules, and preserve client/LLM contract boundaries. + +- [x] **Step T0.2: Read prior quality-program documents** + +Commands: + +```bash +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 +``` + +Result: reused document style, restartable ledger structure, strict boundary wording, and checkpoint discipline without adopting the test-refactor implementation details. + +- [x] **Step T0.3: Create code-scan ledger** + +Create `.workflow/code-scan/` artifacts and initialize state with current branch, SHA, scan lanes, and empty issue counters. + +- [ ] **Step T0.4: Commit setup slice** + +Commands: + +```bash +git add docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md docs/plans/2026-05-31-hugegraph-ai-code-scan.md .workflow/code-scan +git commit -m "docs(code-scan): add core module audit plan" -m "- define scoped P0-P5 code logic scan design +- initialize restartable code-scan ledger +- capture lane-based execution checkpoints" +``` + +## T1: Parallel Client Scan + +**Files:** +- Update: `.workflow/code-scan/checkpoints/01-client-transport.md` +- Update: `.workflow/code-scan/checkpoints/02-client-api-structure.md` +- Update: `.workflow/code-scan/reports/issues.md` +- Update: `.workflow/code-scan/reports/module-map.md` +- Possible FIXME comments: `hugegraph-python-client/src/tests/**/*.py` + +- [ ] **Step T1.1: Scan transport/auth/routing** + +Review: + +```text +hugegraph-python-client/src/pyhugegraph/client.py +hugegraph-python-client/src/pyhugegraph/utils/ +hugegraph-python-client/src/pyhugegraph/api/auth.py +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** + +Review: + +```text +hugegraph-python-client/src/pyhugegraph/api/ +hugegraph-python-client/src/pyhugegraph/structure/ +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** + +Deduplicate client issues, assign P0-P5, update both client checkpoints, and commit the client scan slice. + +## T2: Parallel hugegraph-llm Scan + +**Files:** +- Update: `.workflow/code-scan/checkpoints/03-llm-api-config.md` +- Update: `.workflow/code-scan/checkpoints/04-llm-flow-operator.md` +- Update: `.workflow/code-scan/checkpoints/05-llm-index-model.md` +- Update: `.workflow/code-scan/reports/issues.md` +- 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** + +Review: + +```text +hugegraph-llm/src/hugegraph_llm/api/ +hugegraph-llm/src/hugegraph_llm/config/ +hugegraph-llm/src/hugegraph_llm/resources/ +hugegraph-llm/src/tests/api/ +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** + +Review: + +```text +hugegraph-llm/src/hugegraph_llm/flows/ +hugegraph-llm/src/hugegraph_llm/nodes/ +hugegraph-llm/src/hugegraph_llm/operators/ +hugegraph-llm/src/hugegraph_llm/state/ +hugegraph-llm/src/tests/operators/ +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** + +Review: + +```text +hugegraph-llm/src/hugegraph_llm/indices/ +hugegraph-llm/src/hugegraph_llm/models/ +hugegraph-llm/src/hugegraph_llm/utils/ +hugegraph-llm/src/tests/indices/ +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** + +Deduplicate LLM issues, assign P0-P5, update all LLM checkpoints, and commit the LLM scan slice. + +## T3: Cross-module Contract and Test-quality Synthesis + +**Files:** +- Update: `.workflow/code-scan/checkpoints/06-test-quality.md` +- Update: `.workflow/code-scan/checkpoints/07-synthesis.md` +- Update: `.workflow/code-scan/reports/issues.md` +- 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** + +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** + +Confirm each required `FIXME:` is present, specific, and tied to core behavior. Remove or rewrite vague comments. + +- [ ] **Step T3.3: Produce final report** + +Write `.workflow/code-scan/reports/final-code-scan-report.md` with: + +```text +Summary +Scope Covered +Issue Distribution by Priority +Top P0-P2 Findings +Test-quality and FIXME Summary +Cross-module Contract Risks +Style-only Fixes Applied +Verification Commands +Recommended Next Fix Plan +``` + +- [ ] **Step T3.4: Verify and final commit** + +Run the narrowest available verification for touched files. At minimum: + +```bash +git diff --check +git status --short +``` + +If Python files were edited for `FIXME:` or style-only changes, also run targeted ruff checks for those files. + +Commit final scan artifacts and any allowed non-behavioral edits. diff --git a/docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md b/docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md new file mode 100644 index 00000000..1a8f49e0 --- /dev/null +++ b/docs/specs/2026-05-31-hugegraph-ai-code-scan-design.md @@ -0,0 +1,165 @@ +# HugeGraph AI Code Logic Scan Design + +Date: 2026-05-31 +Target repo: `apache/hugegraph-ai` +Target modules: `hugegraph-llm`, `hugegraph-python-client` +Execution plan: `docs/plans/2026-05-31-hugegraph-ai-code-scan.md` + +## Executive Summary + +This scan is a read-first code audit for the two core modules. It is not a refactor campaign and not a test-quality implementation pass. + +The goal is to inspect all production and test code in `hugegraph-llm` and `hugegraph-python-client`, record logic/design/maintainability/performance risks by layer, and produce a prioritized issue ledger from P0 to P5. Behavior-changing fixes are explicitly out of scope during the scan: they must be recorded with evidence and left for a later fix plan. Only non-behavioral style, typo, or comment issues may be fixed in place. + +The scan uses high parallelism because the two modules have separable risk surfaces: + +- `hugegraph-python-client` owns HTTP routing, auth, response envelopes, schema/graph/gremlin APIs, and data structure adapters. +- `hugegraph-llm` owns API contracts, runtime config, GraphRAG/KG/Text2Gremlin flows, nodes/operators, LLM/vector provider wrappers, and UI/demo glue. +- Cross-module compatibility is audited as its own lane: `hugegraph-llm` callers must remain consistent with the client contract. + +## Non-negotiable Invariants + +1. Do not change logic or design behavior while scanning. Record the issue, affected paths, evidence, impact, and recommended fix direction. +2. Style-only, typo-only, stale-comment-only, and formatting-local fixes may be edited in place if they cannot change runtime behavior. +3. If a core function lacks effective tests, or tests mock away the behavior under review, add a nearby `FIXME:` comment in the relevant test or production-adjacent test location. +4. Do not expand scope into `hugegraph-ml`, `vermeer-python-client`, generated artifacts, caches, logs, build outputs, or unrelated workflows. +5. Do not mix scan findings with the existing quality-program implementation ledger. This scan owns `.workflow/code-scan/`. +6. Every issue must have enough evidence for a maintainer to reproduce the reasoning without trusting the reviewer. +7. Commit after a completed setup slice and after each coherent large scan slice. + +## Priority Model + +| Priority | Meaning | Examples | +|---|---|---| +| P0 | Confirmed correctness, data loss, security, or crash risk on common/default paths. | Wrong REST route, auth leak, destructive graph mutation without guard, unavoidable runtime exception. | +| P1 | High-confidence logic/design flaw that can return wrong results, hide failures, or break a core workflow. | Swallowed HugeGraph/LLM errors, schema mismatch, bad Text2Gremlin extraction, non-deterministic graph import semantics. | +| P2 | Important maintainability or contract issue likely to cause regressions or integration pain. | Duplicated boundary logic, unclear API response contract, weak error mapping, hard-coded config that bypasses central config. | +| P3 | Performance, scalability, resilience, or edge-case risk with plausible production impact. | Unbounded memory use, repeated network calls, O(n^2) path over user data, missing timeout/retry boundary. | +| P4 | Test-quality gap, missing meaningful coverage, weak assertions, ineffective mocks, or fragile test setup. | Test only asserts a mock call, no regression test for parser boundary, silent external-service skip. | +| P5 | Minor style, naming, comment, documentation, or small elegance issue. | Typo, misleading comment, local readability cleanup. | + +Priority is impact-first. A test gap can be P1/P2 if it hides a known high-risk path, but ordinary missing coverage is P4. + +## Scan Boundaries + +### In Scope + +```text +hugegraph-python-client/src/pyhugegraph/ +hugegraph-python-client/src/tests/ +hugegraph-llm/src/hugegraph_llm/ +hugegraph-llm/src/tests/ +hugegraph-llm/pyproject.toml +hugegraph-python-client/pyproject.toml +root pyproject/workflows only when they affect these two modules +``` + +### Out of Scope + +```text +hugegraph-ml/ +vermeer-python-client/ +dist/, egg-info, .venv, .pytest_cache, .ruff_cache, logs, generated coverage artifacts +demo visual redesign, dependency upgrade campaigns, broad formatting rewrites +``` + +## Layered Audit Map + +```text +┌─────────────────────────────────────────────────────────────────┐ +│ Cross-module Contract Lane │ +│ hugegraph-llm callers ⇄ pyhugegraph client API/response shapes │ +└─────────────────────────────────────────────────────────────────┘ + ▲ ▲ + │ │ +┌──────┴─────────────────────────┐ ┌─────────┴────────────────────┐ +│ hugegraph-python-client │ │ hugegraph-llm │ +│ A. transport/auth/routing │ │ A. API/models/config │ +│ B. graph/schema/gremlin APIs │ │ B. flows/scheduler/state │ +│ C. data structures/responses │ │ C. nodes/operators │ +│ D. tests/fixtures │ │ D. indices/models/providers │ +│ │ │ E. demo glue/tests │ +└─────────────────────────────────┘ └──────────────────────────────┘ +``` + +## Parallel Review Lanes + +| Lane | Owner Focus | Primary Paths | Output | +|---|---|---|---| +| L1 | Client transport, auth, routing, request safety | `pyhugegraph/client.py`, `utils/`, `api/auth.py`, `api/common.py` | client transport issues | +| L2 | Client graph/schema/gremlin APIs and structure adapters | `pyhugegraph/api/`, `pyhugegraph/structure/` | client API/contract issues | +| L3 | LLM API, models, config, prompt contract | `hugegraph_llm/api/`, `config/`, `resources/`, tests | public contract issues | +| L4 | LLM graph boundary, flows, nodes, operators | `flows/`, `nodes/hugegraph_node/`, `operators/hugegraph_op/`, `operators/llm_op/` | core workflow issues | +| L5 | LLM indices, model wrappers, performance/resilience | `indices/`, `models/`, `utils/` | provider/vector/perf issues | +| L6 | Test effectiveness and fake/mock quality | both `src/tests/` trees | P4 ledger plus `FIXME:` edits | +| L7 | Cross-module compatibility synthesis | LLM callers plus client response contracts | deduplicated final priorities | + +The main thread coordinates scope, writes the documents, maintains the ledger, performs synthesis, and verifies every edit or commit. + +## Issue Record Schema + +Each issue in `.workflow/code-scan/reports/issues.md` must use this shape: + +```markdown +### CS-000: Short title + +- Priority: P0-P5 +- Module: `hugegraph-llm` | `hugegraph-python-client` | cross-module +- Layer: API | config | flow | node | operator | client-api | transport | structure | test-quality | performance +- Paths: `path.py:line`, `path_test.py:line` +- Status: open | fixed-style-only | deferred | duplicate +- Evidence: concrete code behavior and why it matters +- Impact: user-visible or maintainer-visible consequence +- Recommendation: fix direction without implementing behavior changes +- Test note: existing coverage status or missing effective coverage +``` + +## FIXME Marking Rule + +Add `FIXME:` comments only for meaningful test-quality gaps around core behavior. The comment must name the missing behavior, not just say "add tests". + +Good: + +```python +# FIXME: add a contract test that exercises malformed Gremlin responses from +# pyhugegraph instead of only asserting the mocked client method is called. +``` + +Bad: + +```python +# FIXME: add more tests +``` + +## Checkpoint Ledger + +The scan writes these restartable artifacts: + +```text +.workflow/code-scan/ + README.md + code-scan-state.json + checkpoints/ + 00-setup.md + 01-client-transport.md + 02-client-api-structure.md + 03-llm-api-config.md + 04-llm-flow-operator.md + 05-llm-index-model.md + 06-test-quality.md + 07-synthesis.md + reports/ + issues.md + module-map.md + test-quality-ledger.md + final-code-scan-report.md +``` + +## Definition of Done + +1. Every TODO in `docs/plans/2026-05-31-hugegraph-ai-code-scan.md` is checked. +2. All seven scan lanes have checkpoint notes. +3. `reports/issues.md` contains prioritized P0-P5 findings with evidence and deduplication. +4. Required `FIXME:` comments for ineffective/missing core tests are present. +5. Style-only fixes, if any, are verified with formatting/lint checks or narrower syntax checks. +6. The final report summarizes the issue distribution, highest-risk fixes to schedule next, and verification commands run.
