Files

T

anhtnm1andClaude Opus 5 bbc09f628a feat(R01): architecture foundation, offline fakes and characterization net

EPIC R01 (Team Duy) - safety net before the parallel refactor starts.

R01-T01 docs/architecture/ADR-001-layered-architecture.md
  4-tier boundaries, allowed dependency directions, invariants I1-I6 and
  the strangler-fig migration strategy.
R01-T02 tests/fakes/{fake_provider,fake_tool_executor}.py
  Scripted, offline Provider and extra-tool executor doubles.
R01-T03 scripts/check_imports.py
  AST-based Clean Architecture Guard (CASAN Check 3). Also covers relative
  imports and function-local imports; ASCII-only output for cp932 consoles.
R01-T04 tests/characterization/test_run_cowork.py
  13 snapshot tests pinning run_cowork's current observable contract before
  EPIC R04 moves its orchestration into application/.
R01-T05 docs/architecture/dormant-code.md
  Import-graph scan: 43 unimported modules verified down to 6 genuinely
  dormant items (~1887 LOC); the rest run via subprocess/CLI entry points.

tests/conftest.py binds `cowork_local` to THIS checkout by absolute path -
previously sys.path discovery could import a sibling checkout and the suite
would silently test the wrong code.

Suite: 104 passed, 1.08s (2 pre-existing failures in test_config_security.py
remain - config.py still ships a hardcoded default password, EPIC R02/Team Nam).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-21 10:05:50 +09:00

5.9 KiB

Raw Blame History

Dormant / Dead Code Inventory (R01-T05)

Task: R01-T05 — Phân loại và cô lập mã nguồn cũ
Owner: 🔵 Team Duy
Ngày quét: 2026-08-21
Phạm vi quét: toàn bộ *.py production (loại trừ tests/, assets/, docs/, .git/)

1. Mục đích

Trước khi 3 team refactor song song, cần biết file nào thật sự đang chạy. Refactor một module đã chết là lãng phí; xoá nhầm một module chỉ được gọi động là gây sự cố runtime. Tài liệu này phân loại từng ứng viên, kèm bằng chứng và hành động đề xuất.

2. Phương pháp

Quét AST toàn repo, dựng đồ thị import, tìm module không có module nào khác import. Kết quả thô: 43 module. Sau đó xác minh thủ công từng ứng viên, vì phân tích tĩnh không thấy 3 kiểu tham chiếu:

Kiểu tham chiếu ẩn	Ví dụ thật trong repo
Chạy như subprocess	`state.py:285` gọi `python -m cowork_local.mcp_servers.ms365_server`
Entry point của gói	`__main__.py` (chạy bằng `python -m cowork_local`)
Script chạy tay	`tools/check_.py`, `scripts/.py`

⚠️ Kết luận quan trọng: 43 module "không ai import" KHÔNG đồng nghĩa 43 module chết. Sau xác minh, chỉ còn 6 hạng mục (~1.887 dòng) là dormant thật.

3. Phân loại kết quả

🟥 A. DORMANT THẬT — không có đường nào chạy tới (ứng viên xoá)

Module	LOC	Bằng chứng	Rủi ro khi xoá	Hành động
`ui/accounts_tab.py`	700	Chỉ xuất hiện trong comment của `i18n.py:92`; không widget nào khởi tạo `AccountsTab`	Thấp — panel Monitoring → Accounts hiện không có đường vào	Cô lập, chờ xác nhận PO rồi xoá
`ui/flow_dialog.py`	596	Chỉ được nhắc trong docstring `ui/agent_manager_tab.py:4` và comment `i18n.py:2124`	Trung bình — Flow Manager có thể là tính năng tạm ẩn	Hỏi PO trước, chưa xoá
`security/` (cả package)	296	`prompt_validator`, `action_validator`, `attachment_validator`, `audit_logger`, `command_risk_classifier` — không file nào ngoài package tự import. Chức năng trùng `core/agent_security.py` + `core/security_rules.py` (đang chạy thật)	Trung bình — dễ nhầm đây là lớp bảo mật đang hoạt động	⚠️ Ưu tiên cao: xoá hoặc hợp nhất trong R09 (Team Nam)
`core/codebase_memory_ui.py`	123	Không nơi nào import; `core/codebase_memory.py` (bản không-UI) mới là bản đang dùng	Thấp	Xoá
`core/graph_server.py`	115	Docstring nói phục vụ build không có QtWebEngine, nhưng không có call site nào; `ui/structure_graph_view.py` không gọi	Trung bình — có thể là fallback cho bản .exe chưa nối dây	Xác minh với bản đóng gói PyInstaller trước khi xoá
`ui/mcp_servers_dialog.py`	57	Không import; MCP settings hiện nằm trong `ui/settings_dialog.py`	Thấp	Xoá

Tổng: ~1.887 dòng (≈ 3,4% codebase).

🟨 B. KHÔNG CHẾT — chạy qua đường ẩn (giữ nguyên)

Module	Vì sao phân tích tĩnh báo nhầm
`__main__.py`	Entry point `python -m cowork_local`
`mcp_servers/ms365_server.py`	Chạy như tiến trình con — `state.py:285`
`core/routing/__init__.py`	Được import qua đường dẫn con (`from .routing.service import RoutingService`), heuristic theo tên lá không thấy
`tools/check_*.py` (34 file, 6.608 dòng)	Bộ smoke-test UI chạy tay: `python tools/check_nav.py`. Là dev tooling, không phải code chết
`scripts/bootstrap_gitea_repo.py`, `scripts/check_imports.py`	Script CLI chạy tay / chạy trong CI

🟩 C. CODE SỐNG NHƯNG "ĐÓNG BĂNG" — đụng vào phải cẩn thận

Module	LOC	Ghi chú cho người refactor
`core/chat_agent.py::run_cowork`	580	Đang có characterization test (`tests/characterization/test_run_cowork.py`, R01-T04). Mọi thay đổi hành vi phải làm cùng lúc với cập nhật snapshot
`providers/base.py`	401	Là contract chung của mọi provider; đổi chữ ký = vỡ cả 3 team. Đã có contract test (R03-T01)
`core/routing/*`	2.263	Đã có 79 test đang xanh. R03 bọc chứ không viết lại: `application/model_routing/` gọi xuống đây

4. Quy tắc xử lý (bắt buộc)

Không xoá trong cùng PR với refactor. Xoá code chết là một commit riêng, để git revert được độc lập khi có sự cố.
Cô lập trước, xoá sau. Đánh dấu module bằng docstring cảnh báo, chạy 1 vòng release; không ai báo lỗi mới xoá.
Hạng mục 🟥 A cần một người xác nhận (PO hoặc chủ tính năng) trước khi xoá — trừ khi rõ ràng là bản trùng lặp (codebase_memory_ui, mcp_servers_dialog).
Không refactor code trong nhóm 🟥 A. Nếu một file trong danh sách này >400 dòng, nó không tính vào CASAN Check 2 — vì đường đi đúng là xoá, không phải tách nhỏ.

5. Việc cần bàn giao

Hạng mục	Team nhận	EPIC
`security/` trùng lặp với `core/agent_security.py`	🟣 Nam	R09
`ui/accounts_tab.py`, `ui/flow_dialog.py`, `ui/mcp_servers_dialog.py`	🟣 Nam (sở hữu `presentation/shell/`, `settings/`)	R08
`core/graph_server.py`, `core/codebase_memory_ui.py`	🟢 Hoa (sở hữu `presentation/graph/`)	R06

6. Cách chạy lại lần quét này

python scripts/check_imports.py       # ranh giới kiến trúc (R01-T03)
# Bản quét đồ thị import dùng cho tài liệu này sẽ được đóng gói thành
# scripts/find_dormant.py trong R10-T02 (Testing & Governance tooling).

5.9 KiB Raw Blame History