merge: kéo Delta epic-R04 (gồm cả R01 và R03) vào gamma/refactor

Nam chốt: không chờ Delta merge vào main, lấy sớm để va chạm nhỏ và sửa ngay, thay vì dồn một cục lúc cả hai cùng lên main. R04 chứa trọn R01 và R03 nên một lần merge là đủ cả ba: 96 file, +8260 dòng. Xung đột chỉ 5 file, đều là __init__.py add/add — hai team cùng dựng khung thư mục nên đụng docstring. Giữ docstring của Gamma (nói rõ ràng buộc "không import PySide6"), giữ mọi phần code của Delta. Riêng tests/fakes/__init__.py: bỏ hai dòng import háo hức của Delta (fake_provider, fake_tool_executor). fake_provider dùng `from providers.base import ...` — import tuyệt đối, chỉ chạy được khi cwd là gốc repo — nên nó làm đứt bài test "dùng fake mà không nạp config thật". Không ai import ở cấp package; test của Delta gọi thẳng module nên bỏ đi không ảnh hưởng họ. Đã ghi lý do vào docstring của gói. Delta cũng xoá preview-desktop và "requirements (cloud copy).txt". 430 test xanh sau merge. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 10:20:36 +09:00
parent ca7ea1479d 3665135c38
commit dcf2e8f995
97 changed files with 8275 additions and 235 deletions
@@ -0,0 +1,166 @@
+"""AST-based Static Analysis Guard for Clean Architecture Enforcement.
+
+Scans designated Python packages (such as `domain/` and `application/`) to ensure
+they remain 100% Pure Python and do not import presentation/GUI frameworks (PySide6, PyQt)
+or concrete application shells.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import io
+import sys
+from pathlib import Path
+from typing import List, NamedTuple, Set
+
+# Ensure UTF-8 output on standard console streams across diverse Windows locales (CP932, etc.)
+if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
+    try:
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+
+class ImportViolation(NamedTuple):
+    file_path: Path
+    line_number: int
+    imported_module: str
+    rule_description: str
+
+
+# Disallowed top-level package names in pure business/domain layers
+FORBIDDEN_MODULE_PREFIXES: Set[str] = {
+    "PySide6",
+    "PySide2",
+    "PyQt6",
+    "PyQt5",
+    "ui",
+    "app",
+}
+
+# Default directories that must strictly adhere to Clean Architecture
+DEFAULT_SCAN_DIRS: List[str] = [
+    "domain",
+    "application",
+]
+
+
+class ArchitectureImportVisitor(ast.NodeVisitor):
+    """AST visitor that checks all Import and ImportFrom statements against forbidden prefixes."""
+
+    def __init__(self, file_path: Path, forbidden: Set[str]) -> None:
+        self.file_path = file_path
+        self.forbidden = forbidden
+        self.violations: List[ImportViolation] = []
+
+    def visit_Import(self, node: ast.Import) -> None:
+        # Check direct `import x, y` statements
+        for alias in node.names:
+            root_module = alias.name.split(".")[0]
+            if root_module in self.forbidden:
+                self.violations.append(
+                    ImportViolation(
+                        file_path=self.file_path,
+                        line_number=node.lineno,
+                        imported_module=alias.name,
+                        rule_description=f"Direct import of GUI/shell module '{alias.name}' is prohibited.",
+                    )
+                )
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        # Check `from x import y` statements
+        if node.module:
+            root_module = node.module.split(".")[0]
+            if root_module in self.forbidden:
+                self.violations.append(
+                    ImportViolation(
+                        file_path=self.file_path,
+                        line_number=node.lineno,
+                        imported_module=node.module,
+                        rule_description=f"Import from GUI/shell module '{node.module}' is prohibited.",
+                    )
+                )
+        self.generic_visit(node)
+
+
+def scan_file(file_path: Path, forbidden: Set[str]) -> List[ImportViolation]:
+    """Parse a single Python file into AST and return all detected architecture import violations."""
+    try:
+        source_code = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(source_code, filename=str(file_path))
+    except (SyntaxError, UnicodeDecodeError) as exc:
+        print(f"[Syntax/Read Warning] Could not parse {file_path}: {exc}", file=sys.stderr)
+        return []
+
+    visitor = ArchitectureImportVisitor(file_path, forbidden)
+    visitor.visit(tree)
+    return visitor.violations
+
+
+def scan_directory(dir_path: Path, forbidden: Set[str]) -> List[ImportViolation]:
+    """Recursively scan all Python files in a directory."""
+    violations: List[ImportViolation] = []
+    if not dir_path.exists():
+        return violations
+
+    for py_file in dir_path.rglob("*.py"):
+        if py_file.is_file() and "__pycache__" not in py_file.parts:
+            violations.extend(scan_file(py_file, forbidden))
+
+    return violations
+
+
+def main() -> int:
+    """CLI entry point for CI/pre-commit quality gate checks."""
+    parser = argparse.ArgumentParser(
+        description="Clean Architecture Import Guard: Verifies zero GUI/Qt dependencies in domain/app layers."
+    )
+    parser.add_argument(
+        "--paths",
+        nargs="*",
+        default=DEFAULT_SCAN_DIRS,
+        help="Paths or directories to scan (defaults to 'domain' and 'application')",
+    )
+    parser.add_argument(
+        "--root",
+        default=".",
+        help="Root workspace directory",
+    )
+    args = parser.parse_args()
+
+    root_dir = Path(args.root).resolve()
+    all_violations: List[ImportViolation] = []
+
+    print(f"[Clean Arch Guard] Scanning root: {root_dir}")
+
+    for target in args.paths:
+        target_path = (root_dir / target).resolve()
+        if not target_path.exists():
+            # If the layer directory does not exist yet (during early migration), skip cleanly
+            print(f"[Clean Arch Guard] Directory '{target}' does not exist yet (skipped).")
+            continue
+
+        if target_path.is_file():
+            all_violations.extend(scan_file(target_path, FORBIDDEN_MODULE_PREFIXES))
+        else:
+            all_violations.extend(scan_directory(target_path, FORBIDDEN_MODULE_PREFIXES))
+
+    if all_violations:
+        print("\n[FAIL] CLEAN ARCHITECTURE VIOLATIONS DETECTED:")
+        print("=" * 70)
+        for v in all_violations:
+            rel_path = v.file_path.relative_to(root_dir) if v.file_path.is_relative_to(root_dir) else v.file_path
+            print(f"  • {rel_path}:{v.line_number} -> Forbidden import: '{v.imported_module}'")
+            print(f"    Reason: {v.rule_description}")
+        print("=" * 70)
+        print(f"Total Violations: {len(all_violations)}")
+        return 1
+
+    print("\n[PASS] CLEAN ARCHITECTURE CHECK: 0 forbidden imports detected.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())