@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/engine/project_topology.py

@@ -1,1920 +0,0 @@
-"""Project topology resolution and graph artifact generation (Phase 113, FR-113.2..FR-113.4).
-
-This module provides the core infrastructure for project-scope requirement execution:
-
-- **ProjectTopologyResolver** (TSK-113.2): Resolves participating repos from registry/state,
-  classifies repo types using ``RepoTypeClassifier``, and persists ``project-topology.json``.
-
-- **PerRepoStructureExtractor** (TSK-113.3): Bounded extraction of imports, client/integration
-  wiring, module manifests, and service entrypoints needed for cross-repo topology.
-
-- **DependencyGraphBuilder** (TSK-113.4): Normalizes extracted structure into
-  ``project-dependency-graph.json`` and ``project-cycle-report.json`` with edge provenance
-  and deterministic cycle/layering checks.
-
-Design Decision References:
-- DD-113.2: ``workflow-project`` owns authoritative project-scope execution.
-- DD-113.3: Registry/state topology is the participation authority.
-- DD-113.4: Project graph artifacts are deterministic and reusable.
-- DD-113.5: Deterministic graph checks outrank narrative inference.
-"""
-
-from __future__ import annotations
-
-import re
-from collections.abc import Iterator
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from enum import StrEnum
-from pathlib import Path
-from typing import Any, Literal
-
-from psycopg.rows import dict_row
-from pydantic import BaseModel, Field
-from structlog import get_logger
-
-from vds_audit_orchestrator.engine.repo_type_classifier import RepoType, RepoTypeClassifier
-
-__all__ = [
-    "CycleFinding",
-    "DependencyEdge",
-    "DependencyGraphBuilder",
-    "EdgeSource",
-    "ModuleIdentity",
-    "PerRepoStructureExtractor",
-    "ProjectCycleReport",
-    "ProjectDependencyGraph",
-    "ProjectTopology",
-    "ProjectTopologyResolver",
-    "RepoRole",
-    "classify_repo_role",
-]
-
-logger = get_logger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Enums and Constants
-# ---------------------------------------------------------------------------
-
-
-class RepoRole(StrEnum):
-    """Deterministic repo-role classification for cross-repo config awareness (FR-122.3, AC-122.3.1).
-
-    Values are ordered by classification priority in ``classify_repo_role()``.
-    """
-
-    SERVICE = "service"
-    CONFIG = "config"
-    LIB = "lib"
-    INFRA = "infra"
-    DEPLOYMENT = "deployment"
-    FRONTEND = "frontend"
-    UNKNOWN = "unknown"
-
-
-# Naming heuristics for repo-role classification (DD-122.5).
-_CONFIG_REPO_NAME_PATTERNS: tuple[re.Pattern[str], ...] = (
-    re.compile(r"[-_]config(?:uration)?(?:[-_]|$)", re.IGNORECASE),
-    re.compile(r"^config[-_]", re.IGNORECASE),
-    re.compile(r"[-_]properties(?:[-_]|$)", re.IGNORECASE),
-    re.compile(r"[-_]settings(?:[-_]|$)", re.IGNORECASE),
-    re.compile(r"[-_]env(?:ironment)?s?(?:[-_]|$)", re.IGNORECASE),
-)
-
-_LIB_REPO_NAME_PATTERNS: tuple[re.Pattern[str], ...] = (
-    re.compile(r"[-_](?:lib|library|common|shared|core|sdk|utils?)(?:[-_]|$)", re.IGNORECASE),
-    re.compile(r"^(?:lib|library|common|shared|core|sdk|utils?)[-_]", re.IGNORECASE),
-)
-
-_INFRA_REPO_NAME_PATTERNS: tuple[re.Pattern[str], ...] = (
-    re.compile(r"[-_](?:infra|infrastructure|platform|ops|devops|sre)(?:[-_]|$)", re.IGNORECASE),
-    re.compile(r"^(?:infra|infrastructure|platform|ops|devops|sre)[-_]", re.IGNORECASE),
-)
-
-_DEPLOYMENT_REPO_NAME_PATTERNS: tuple[re.Pattern[str], ...] = (
-    re.compile(
-        r"[-_](?:deploy|deployment|helm|chart|k8s|kubernetes|terraform|ansible|ci|cd|pipeline)(?:[-_]|$)", re.IGNORECASE
-    ),
-    re.compile(r"^(?:deploy|deployment|helm|chart|k8s|kubernetes|terraform|ansible)[-_]", re.IGNORECASE),
-)
-
-_FRONTEND_REPO_NAME_PATTERNS: tuple[re.Pattern[str], ...] = (
-    re.compile(r"[-_](?:fe|frontend|web|ui|portal|dashboard|app)(?:[-_]|$)", re.IGNORECASE),
-    re.compile(r"^(?:fe|frontend|web|ui|portal|dashboard)[-_]", re.IGNORECASE),
-)
-
-_SERVICE_REPO_NAME_PATTERNS: tuple[re.Pattern[str], ...] = (
-    re.compile(
-        r"[-_](?:service|svc|api|server|backend|gateway|worker|processor|consumer|producer)(?:[-_]|$)", re.IGNORECASE
-    ),
-    re.compile(r"^(?:service|svc|api|server|backend|gateway|worker)[-_]", re.IGNORECASE),
-)
-
-# Structure heuristics: files/dirs that indicate a config repo.
-_CONFIG_STRUCTURE_FILES: frozenset[str] = frozenset(
-    {
-        "application.yml",
-        "application.yaml",
-        "application.properties",
-        "application-dev.yml",
-        "application-prod.yml",
-        "bootstrap.yml",
-        "bootstrap.yaml",
-    }
-)
-_CONFIG_STRUCTURE_DIRS: frozenset[str] = frozenset(
-    {
-        "config",
-        "configs",
-        "configuration",
-        "properties",
-        "environments",
-    }
-)
-
-# Structure heuristics: files/dirs that indicate a lib repo.
-_LIB_STRUCTURE_DIRS: frozenset[str] = frozenset(
-    {
-        "lib",
-        "libs",
-        "packages",
-        "modules",
-    }
-)
-
-# Structure heuristics: files/dirs that indicate a deployment repo.
-_DEPLOYMENT_STRUCTURE_DIRS: frozenset[str] = frozenset(
-    {
-        "helm",
-        "charts",
-        "k8s",
-        "kubernetes",
-        "terraform",
-        "ansible",
-        "deploy",
-        "deployment",
-        "manifests",
-    }
-)
-
-
-def classify_repo_role(
-    *,
-    repo_key: str,
-    repo_path: Path | None = None,
-    repo_type: RepoType | None = None,
-) -> RepoRole:
-    """Deterministic heuristic-driven repo-role classification (DD-122.5, AC-122.3.2).
-
-    Classification priority:
-    1. Naming patterns on ``repo_key`` (strongest signal).
-    2. Structure heuristics from ``repo_path`` top-level entries.
-    3. Fallback from existing ``RepoType`` when available.
-    4. ``RepoRole.UNKNOWN`` as default.
-    """
-    repo_key_lower = repo_key.lower()
-
-    # --- Layer 0: Pre-scan structure for source-code markers (DD-122.5 refinement) ---
-    # Repos whose name matches config/deployment patterns but contain source code
-    # (src/ + build tool) are services that *manage* config, not pure config repos.
-    _has_source_code_structure = False
-    if repo_path is not None and repo_path.is_dir():
-        try:
-            _top_names = {entry.name for entry in repo_path.iterdir()}
-        except OSError:
-            _top_names = set()
-        _SOURCE_CODE_MARKERS = {"src", "main", "app", "lib"}
-        _BUILD_TOOL_MARKERS = {
-            "pom.xml",
-            "build.gradle",
-            "build.gradle.kts",
-            "go.mod",
-            "pyproject.toml",
-            "package.json",
-        }
-        _has_source_code_structure = bool(_top_names & _SOURCE_CODE_MARKERS) and bool(_top_names & _BUILD_TOOL_MARKERS)
-
-    # --- Layer 1: Naming heuristics (highest priority) ---
-    if any(p.search(repo_key_lower) for p in _CONFIG_REPO_NAME_PATTERNS):
-        if _has_source_code_structure:
-            # Name says "config" but structure says "service" — demote to SERVICE.
-            logger.debug(
-                "classify_repo_role_config_demoted",
-                repo_key=repo_key,
-                reason="source_code_structure_detected",
-            )
-            return RepoRole.SERVICE
-        return RepoRole.CONFIG
-    if any(p.search(repo_key_lower) for p in _DEPLOYMENT_REPO_NAME_PATTERNS):
-        return RepoRole.DEPLOYMENT
-    if any(p.search(repo_key_lower) for p in _INFRA_REPO_NAME_PATTERNS):
-        return RepoRole.INFRA
-    if any(p.search(repo_key_lower) for p in _LIB_REPO_NAME_PATTERNS):
-        return RepoRole.LIB
-    if any(p.search(repo_key_lower) for p in _FRONTEND_REPO_NAME_PATTERNS):
-        return RepoRole.FRONTEND
-    if any(p.search(repo_key_lower) for p in _SERVICE_REPO_NAME_PATTERNS):
-        return RepoRole.SERVICE
-
-    # --- Layer 2: Structure heuristics ---
-    if repo_path is not None and repo_path.is_dir():
-        try:
-            top_level = {entry.name for entry in repo_path.iterdir()}
-        except OSError:
-            top_level = set()
-
-        top_level_lower = {name.lower() for name in top_level}
-
-        # Config repo: dominated by config files with no source code
-        has_config_files = bool(top_level_lower & {f.lower() for f in _CONFIG_STRUCTURE_FILES})
-        has_config_dirs = bool(top_level_lower & _CONFIG_STRUCTURE_DIRS)
-        has_source_code = bool(
-            top_level & {"src", "main", "app", "lib", "pom.xml", "build.gradle", "go.mod", "pyproject.toml"}
-        )
-        if (has_config_files or has_config_dirs) and not has_source_code:
-            return RepoRole.CONFIG
-
-        # Deployment repo: dominated by deployment manifests
-        if top_level_lower & _DEPLOYMENT_STRUCTURE_DIRS and not has_source_code:
-            return RepoRole.DEPLOYMENT
-
-        # Lib repo: has lib/packages structure
-        if top_level_lower & _LIB_STRUCTURE_DIRS and not bool(top_level & {"Dockerfile", "docker-compose.yml"}):
-            return RepoRole.LIB
-
-    # --- Layer 3: Fallback from RepoType ---
-    if repo_type is not None:
-        _type_to_role: dict[RepoType, RepoRole] = {
-            RepoType.FRONTEND: RepoRole.FRONTEND,
-            RepoType.BACKEND: RepoRole.SERVICE,
-            RepoType.INFRA: RepoRole.INFRA,
-            RepoType.FULLSTACK: RepoRole.SERVICE,
-        }
-        fallback = _type_to_role.get(repo_type)
-        if fallback is not None:
-            return fallback
-
-    return RepoRole.UNKNOWN
-
-
-class EdgeSource(StrEnum):
-    """Provenance type for a dependency edge."""
-
-    IMPORT_STATEMENT = "import_statement"
-    CLIENT_WIRING = "client_wiring"
-    MANIFEST_REFERENCE = "manifest_reference"
-    SERVICE_ENTRYPOINT = "service_entrypoint"
-    ADAPTER_CONFIG = "adapter_config"
-    ANNOTATION_ATTRIBUTE = "annotation_attribute"
-
-
-class DependencyType(StrEnum):
-    """Category of dependency relationship."""
-
-    DIRECT = "direct"
-    TRANSITIVE = "transitive"
-    RUNTIME = "runtime"
-    COMPILE = "compile"
-    PROVIDED = "provided"
-
-
-# Language-specific patterns for structure extraction (TSK-113.3)
-_JAVA_IMPORT_PATTERN = re.compile(r"""^import\s+(?:static\s+)?([\w.]+)(?:\.\*)?;""")
-_KOTLIN_IMPORT_PATTERN = re.compile(r"""^import\s+(?:([\w.]+)(?:\.\*)?|\* as \w+)""")
-_PYTHON_IMPORT_PATTERN = re.compile(r"""^from\s+([\w.]+)\s+import|^import\s+([\w.]+)(?:\s+as\s+\w+)?$""")
-_GO_IMPORT_PATTERN = re.compile(r"""^import\s+"([^"]+)"|import\s+`([^"]+)`""")
-_TS_IMPORT_PATTERN = re.compile(r"""^import\s+(?:(?:{[^}]*}|\w+)\s+from\s+)?['"]([^'"]+)['"]""")
-
-# Module boundary patterns
-_JAVA_PACKAGE_PATTERN = re.compile(r"""^package\s+([\w.]+);""")
-_KOTLIN_PACKAGE_PATTERN = re.compile(r"""^package\s+([\w.]+)""")
-_PYTHON_MODULE_INIT = ("__init__.py",)
-_GO_PACKAGE_PATTERN = re.compile(r"""^package\s+(\w+)""")
-_TS_NAMESPACE_PATTERN = re.compile(r"""^namespace\s+(\w+)""")
-
-# Service/adapter patterns
-_SPRING_SERVICE_PATTERN = re.compile(r"""@(?:Rest)?Controller|@Service|@Component|@Repository""")
-_SPRING_REQUEST_MAPPING = re.compile(r"""@(?:Get|Post|Put|Delete|Patch|Request)Mapping""")
-_MICRONAUT_CONTROLLER = re.compile(r"""@(?:Controller|Client)(?:\s*\(\s*['"]([^'"]+)['"])?""")
-_QUARKUS_PATH = re.compile(r"""@Path\s*\(\s*['"]([^'"]+)['"]""")
-
-# Build manifest patterns
-_GRADLE_PROJECT_PATTERN = re.compile(r"""^\s*(?:api|implementation|testImplementation)\s+['"]([^:'"]+)""")
-_MAVEN_DEPENDENCY_PATTERN = re.compile(
-    r"""<dependency>.*?<groupId>([^<]+)</groupId>.*?<artifactId>([^<]+)</artifactId>""",
-    re.DOTALL,
-)
-_PYTHON_REQUIREMENT = re.compile(r"""^[\w\-\[\],<>=!~]+===?([\w\.\-]+)""")
-_GO_MODULE_PATTERN = re.compile(r"""^\s+([\w\.\/]+)\s+v[\d\.]+""")
-_NODE_DEPENDENCY = re.compile(r"""^['"]([\w\-@\/]+)['"]:\s*['"]?[^'"]+['"]?""")
-
-# Bounded extraction limits (DD-113.3)
-_MAX_SCAN_DEPTH = 3  # Maximum directory depth for structure scan
-_MAX_FILES_PER_REPO = 500  # Safety limit on files scanned per repo
-_MAX_EDGES_PER_REPO = 200  # Safety limit on edges extracted per repo
-
-
-# ---------------------------------------------------------------------------
-# Data Models (FR-113.2, FR-113.3, FR-113.4)
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True, slots=True)
-class ModuleIdentity:
-    """Normalized module/service identity for cross-repo topology."""
-
-    name: str
-    repo_key: str
-    module_type: str  # e.g., "spring_service", "fastapi_app", "go_package"
-    language: str  # e.g., "java", "python", "go"
-    source_path: str  # Relative path from repo root
-    is_entrypoint: bool = False
-
-    def __str__(self) -> str:
-        return f"{self.repo_key}/{self.name}"
-
-
-@dataclass(frozen=True, slots=True)
-class DependencyEdge:
-    """A directed dependency edge between modules/repos."""
-
-    source_module: str  # Fully qualified source module name
-    target_module: str  # Fully qualified target module name
-    source_repo: str
-    target_repo: str
-    dependency_type: DependencyType = DependencyType.DIRECT
-    edge_source: EdgeSource = EdgeSource.IMPORT_STATEMENT
-    source_file: str | None = None
-    line_number: int | None = None
-    evidence_snippet: str | None = None
-
-    def __hash__(self) -> int:
-        return hash((self.source_module, self.target_module, self.source_repo, self.target_repo))
-
-    def __eq__(self, other: object) -> bool:
-        if not isinstance(other, DependencyEdge):
-            return False
-        return (
-            self.source_module == other.source_module
-            and self.target_module == other.target_module
-            and self.source_repo == other.source_repo
-            and self.target_repo == other.target_repo
-        )
-
-
-@dataclass(frozen=True, slots=True)
-class CycleFinding:
-    """A detected circular dependency or forbidden edge."""
-
-    cycle_type: Literal["circular", "forbidden_layer", "forbidden_peer"]
-    involved_modules: list[str]
-    involved_repos: set[str]
-    path: list[DependencyEdge]  # The full cycle path
-    severity: Literal["error", "warning", "info"] = "error"
-    description: str = ""
-    detection_timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "cycle_type": self.cycle_type,
-            "involved_modules": self.involved_modules,
-            "involved_repos": sorted(self.involved_repos),
-            "path": [
-                {
-                    "from": edge.source_module,
-                    "to": edge.target_module,
-                    "source_repo": edge.source_repo,
-                    "target_repo": edge.target_repo,
-                    "edge_source": edge.edge_source,
-                    "source_file": edge.source_file,
-                    "line_number": edge.line_number,
-                }
-                for edge in self.path
-            ],
-            "severity": self.severity,
-            "description": self.description,
-            "detection_timestamp": self.detection_timestamp.isoformat(),
-        }
-
-
-class RepoTopologyEntry(BaseModel):
-    """Single repo entry within project topology (FR-113.2, FR-122.3)."""
-
-    repo_key: str
-    repo_path: str
-    repo_type: RepoType
-    repo_role: RepoRole = RepoRole.UNKNOWN  # Phase 122 (AC-122.3.1)
-    modules: list[str] = Field(default_factory=list)  # Fully qualified module names
-    entrypoints: list[str] = Field(default_factory=list)
-    language: str | None = None
-    scan_summary: dict[str, int] = Field(default_factory=dict)
-
-
-class ProjectTopology(BaseModel):
-    """Project topology artifact (FR-113.2, AC-113.2.2).
-
-    This artifact records:
-    - Participating repo keys and identities
-    - Resolved repo types (frontend/backend/fullstack/unknown)
-    - Normalized module/service entries when available
-    - Input provenance (AC-113.2.3)
-    """
-
-    project_storage_key: str
-    project_name: str | None = None
-    repos: list[RepoTopologyEntry] = Field(default_factory=list)
-    resolved_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    thread_id: str | None = None
-    run_id: str | None = None
-    registry_source: str | None = None
-    topology_source: str | None = None
-
-    model_config = {"extra": "allow"}
-
-
-class ProjectDependencyGraph(BaseModel):
-    """Project dependency graph artifact (FR-113.3, AC-113.3.1).
-
-    Contains normalized edges with provenance (AC-113.3.4) and supports
-    deterministic cycle detection (AC-113.3.3).
-    """
-
-    project_storage_key: str
-    nodes: dict[str, dict[str, Any]] = Field(
-        default_factory=dict,
-        description="Module identity metadata keyed by fully qualified name",
-    )
-    edges: list[dict[str, Any]] = Field(
-        default_factory=list,
-        description="All dependency edges with provenance",
-    )
-    cross_repo_edges: list[dict[str, Any]] = Field(
-        default_factory=list,
-        description="Subset of edges that cross repo boundaries",
-    )
-    generated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    provenance: dict[str, Any] = Field(default_factory=dict)
-
-    model_config = {"extra": "allow"}
-
-
-class ProjectCycleReport(BaseModel):
-    """Project cycle detection report (FR-113.3, AC-113.3.3).
-
-    Authoritative for cross-repo dependency/coupling rows. LLM reasoning
-    may explain but must not replace these results (DD-113.5).
-    """
-
-    project_storage_key: str
-    total_edges_analyzed: int
-    circular_cycles: list[dict[str, Any]] = Field(default_factory=list)
-    forbidden_layer_violations: list[dict[str, Any]] = Field(default_factory=list)
-    cross_repo_couplings: list[dict[str, Any]] = Field(default_factory=list)
-    layering_summary: dict[str, Any] = Field(default_factory=dict)
-    generated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    graph_artifact_reference: str | None = None
-
-    model_config = {"extra": "allow"}
-
-
-# ---------------------------------------------------------------------------
-# TSK-113.2: Project Topology Participation Resolver
-# ---------------------------------------------------------------------------
-
-
-class ProjectTopologyResolver:
-    """Resolve participating repos and build project topology artifact (FR-113.2).
-
-    Reuses registry/state/topology inputs already used by ``workflow-project``
-    (DD-113.3) and produces ``project-topology.json`` with provenance (AC-113.2.3).
-
-    Usage:
-        resolver = ProjectTopologyResolver(state_store=store)
-
-        topology = resolver.resolve_from_state(
-            project_storage_key="88718940",
-            thread_id="audit-20250312",
-        )
-
-        topology.write_json(output_dir / "project-topology.json")
-    """
-
-    def __init__(
-        self,
-        *,
-        state_store: Any,  # Centralized state store (PostgresStateStore)
-        repo_cache_root: Path,
-        repo_type_classifier: RepoTypeClassifier | None = None,
-    ) -> None:
-        self.state_store = state_store
-        self.repo_cache_root = repo_cache_root
-        self.repo_type_classifier = repo_type_classifier or RepoTypeClassifier()
-        self._logger = get_logger(__name__, component="ProjectTopologyResolver")
-
-    def resolve_from_state(
-        self,
-        *,
-        project_storage_key: str,
-        thread_id: str | None = None,
-        run_id: str | None = None,
-        bitbucket_project: str | None = None,
-    ) -> ProjectTopology:
-        """Resolve participating repos from centralized state (AC-113.2.1).
-
-        Args:
-            project_storage_key: Confluence numeric page_id for the project.
-            thread_id: Workflow thread ID for provenance.
-            run_id: Optional run ID for provenance.
-            bitbucket_project: Optional Bitbucket project key override.
-
-        Returns:
-            ``ProjectTopology`` with repo identities, types, and module entries.
-
-        Raises:
-            ValueError: If project cannot be resolved from state (AC-113.2.4).
-        """
-        self._logger.info(
-            "project_topology_resolving",
-            project_storage_key=project_storage_key,
-            thread_id=thread_id,
-        )
-
-        # Query repos from centralized state
-        try:
-            project_row = self._get_project_row(project_storage_key)
-        except Exception as e:
-            self._logger.exception(
-                "project_topology_resolution_failed",
-                project_storage_key=project_storage_key,
-                error=str(e),
-            )
-            raise ValueError(
-                f"Cannot resolve project topology for {project_storage_key!r}: "
-                f"project not found in centralized state. "
-                f"Cross-repo code rows must remain non-pass (AC-113.2.4)."
-            ) from e
-
-        # Check if project row was actually found (may return None without exception)
-        if project_row is None:
-            raise ValueError(
-                f"Cannot resolve project topology for {project_storage_key!r}: "
-                f"project not found in centralized state. "
-                f"Cross-repo code rows must remain non-pass (AC-113.2.4)."
-            )
-
-        repo_entries: list[RepoTopologyEntry] = []
-        repos = self._get_project_repos(
-            project_storage_key=project_storage_key,
-            bitbucket_project=bitbucket_project,
-        )
-
-        for repo_row in repos:
-            repo_key = str(repo_row.get("repo_key") or "").strip()
-            repo_slug = self._repo_slug_for_path(repo_row) or repo_key
-            local_code_path = self._repo_local_code_path(repo_row)
-            if repo_key.endswith(":project") and not local_code_path:
-                self._logger.debug(
-                    "project_topology_pseudo_repo_skipped",
-                    repo_key=repo_key,
-                )
-                continue
-            if not repo_slug and not local_code_path:
-                self._logger.debug(
-                    "project_topology_repo_identity_skipped",
-                    repo_key=repo_key,
-                )
-                continue
-            repo_path = self._resolve_repo_path(
-                repo_key=repo_key,
-                repo_slug=repo_slug,
-                local_code_path=local_code_path,
-                bitbucket_project=repo_row.get("bitbucket_project_key"),
-            )
-
-            if not repo_path or not repo_path.exists():
-                self._logger.warning(
-                    "project_topology_repo_not_found",
-                    repo_key=repo_key,
-                    repo_slug=repo_slug,
-                    repo_path=str(repo_path) if repo_path else None,
-                )
-                continue
-
-            repo_type = self.repo_type_classifier.classify(repo_path)
-            repo_role = classify_repo_role(
-                repo_key=repo_key,
-                repo_path=repo_path,
-                repo_type=repo_type,
-            )
-
-            entry = RepoTopologyEntry(
-                repo_key=repo_key,
-                repo_path=str(repo_path),
-                repo_type=repo_type,
-                repo_role=repo_role,
-                language=self._infer_repo_language(repo_path),
-                scan_summary={"modules": 0, "entrypoints": 0},
-            )
-
-            repo_entries.append(entry)
-            self._logger.debug(
-                "project_topology_repo_classified",
-                repo_key=repo_key,
-                repo_type=repo_type.value,
-                repo_role=repo_role.value,
-            )
-
-        # Sort by repo_key for deterministic output (NFR-113.1)
-        repo_entries.sort(key=lambda e: e.repo_key)
-
-        topology = ProjectTopology(
-            project_storage_key=project_storage_key,
-            project_name=project_row.get("display_name"),
-            repos=repo_entries,
-            resolved_at=datetime.now(UTC),
-            thread_id=thread_id,
-            run_id=run_id,
-            registry_source="centralized_state",
-            topology_source="registry_state_confluence",
-        )
-
-        self._logger.info(
-            "project_topology_resolved",
-            project_storage_key=project_storage_key,
-            repos_count=len(topology.repos),
-        )
-
-        return topology
-
-    def _get_project_row(self, project_storage_key: str) -> dict[str, Any] | None:
-        """Fetch project row from centralized state."""
-        if hasattr(self.state_store, "get_project_by_storage_key"):
-            return self.state_store.get_project_by_storage_key(project_storage_key)
-        if hasattr(self.state_store, "get_project"):
-            return self.state_store.get_project(project_storage_key)
-        # Fallback: try direct SQL query
-        if hasattr(self.state_store, "_conn"):
-            with self.state_store._conn.cursor(row_factory=dict_row) as cur:
-                cur.execute(
-                    """
-                    SELECT *
-                    FROM audit_state.projects
-                    WHERE project_key = %s
-                       OR metadata->>'page_id' = %s
-                       OR metadata->>'project_storage_key' = %s
-                    ORDER BY CASE WHEN project_key = %s THEN 0 ELSE 1 END, id
-                    LIMIT 1
-                    """,
-                    (project_storage_key, project_storage_key, project_storage_key, project_storage_key),
-                )
-                return cur.fetchone()
-        return None
-
-    def _get_project_repos(
-        self,
-        project_storage_key: str,
-        bitbucket_project: str | None = None,
-    ) -> list[dict[str, Any]]:
-        """Fetch repos for project from centralized state."""
-        if hasattr(self.state_store, "get_repos_for_project"):
-            return self.state_store.get_repos_for_project(project_storage_key)
-
-        # Fallback: direct SQL query
-        if hasattr(self.state_store, "_conn"):
-            with self.state_store._conn.cursor(row_factory=dict_row) as cur:
-                if bitbucket_project:
-                    cur.execute(
-                        """
-                        SELECT
-                            r.repo_key,
-                            NULLIF(
-                                btrim(
-                                    COALESCE(
-                                        r.metadata->>'repo_slug',
-                                        r.metadata->>'bitbucket_repo_key',
-                                        r.repo_key
-                                    )
-                                ),
-                                ''
-                            ) AS repo_slug,
-                            COALESCE(
-                                NULLIF(btrim(r.metadata->>'bitbucket_project_key'), ''),
-                                bp.project_key
-                            ) AS bitbucket_project_key,
-                            NULLIF(btrim(r.metadata->>'local_code_path'), '') AS local_code_path,
-                            r.metadata
-                        FROM audit_state.repos r
-                        JOIN audit_state.projects p ON p.id = r.project_id
-                        LEFT JOIN audit_state.bitbucket_projects bp ON bp.id = r.bitbucket_project_id
-                        WHERE p.project_key = %s
-                          AND r.analysis_excluded = FALSE
-                          AND lower(COALESCE(NULLIF(btrim(r.metadata->>'bitbucket_project_key'), ''), bp.project_key, '')) = lower(%s)
-                        ORDER BY r.repo_key
-                        """,
-                        (project_storage_key, bitbucket_project),
-                    )
-                else:
-                    cur.execute(
-                        """
-                        SELECT
-                            r.repo_key,
-                            NULLIF(
-                                btrim(
-                                    COALESCE(
-                                        r.metadata->>'repo_slug',
-                                        r.metadata->>'bitbucket_repo_key',
-                                        r.repo_key
-                                    )
-                                ),
-                                ''
-                            ) AS repo_slug,
-                            COALESCE(
-                                NULLIF(btrim(r.metadata->>'bitbucket_project_key'), ''),
-                                bp.project_key
-                            ) AS bitbucket_project_key,
-                            NULLIF(btrim(r.metadata->>'local_code_path'), '') AS local_code_path,
-                            r.metadata
-                        FROM audit_state.repos r
-                        JOIN audit_state.projects p ON p.id = r.project_id
-                        LEFT JOIN audit_state.bitbucket_projects bp ON bp.id = r.bitbucket_project_id
-                        WHERE p.project_key = %s
-                          AND r.analysis_excluded = FALSE
-                        ORDER BY r.repo_key
-                        """,
-                        (project_storage_key,),
-                    )
-                return cur.fetchall()
-        return []
-
-    def _resolve_repo_path(
-        self,
-        repo_key: str,
-        repo_slug: str | None = None,
-        local_code_path: str | None = None,
-        bitbucket_project: str | None = None,
-    ) -> Path | None:
-        """Resolve repo cache path from repo key and Bitbucket project."""
-        if isinstance(local_code_path, str) and local_code_path.strip():
-            local_repo_path = Path(local_code_path).expanduser()
-            if local_repo_path.exists():
-                return local_repo_path
-
-        bb_project = bitbucket_project or self._infer_bitbucket_project(repo_key)
-        if not bb_project:
-            return None
-
-        repo_dir_name = str(repo_slug or repo_key or "").strip()
-        if not repo_dir_name:
-            return None
-
-        candidate_projects: list[str] = []
-        normalized_project = str(bb_project).strip()
-        for candidate in (normalized_project.upper(), normalized_project, normalized_project.lower()):
-            if candidate and candidate not in candidate_projects:
-                candidate_projects.append(candidate)
-
-        for project_key in candidate_projects:
-            candidate_path = self.repo_cache_root / f"{project_key}-project" / repo_dir_name
-            if candidate_path.exists():
-                return candidate_path
-
-        # Standard cache pattern: <vds-cache-root>/repos/{BB_PROJECT}-project/{repo_slug}
-        return self.repo_cache_root / f"{candidate_projects[0]}-project" / repo_dir_name
-
-    @staticmethod
-    def _repo_metadata(repo_row: dict[str, Any]) -> dict[str, Any]:
-        metadata = repo_row.get("metadata")
-        return metadata if isinstance(metadata, dict) else {}
-
-    def _repo_slug_for_path(self, repo_row: dict[str, Any]) -> str:
-        metadata = self._repo_metadata(repo_row)
-        for candidate in (
-            repo_row.get("repo_slug"),
-            metadata.get("repo_slug"),
-            metadata.get("bitbucket_repo_key"),
-            repo_row.get("repo_key"),
-        ):
-            value = str(candidate or "").strip()
-            if value:
-                return value
-        return ""
-
-    def _repo_local_code_path(self, repo_row: dict[str, Any]) -> str | None:
-        metadata = self._repo_metadata(repo_row)
-        value = str(repo_row.get("local_code_path") or metadata.get("local_code_path") or "").strip()
-        return value or None
-
-    def _infer_bitbucket_project(self, repo_key: str) -> str | None:
-        """Infer Bitbucket project key from repo_key or state."""
-        if hasattr(self.state_store, "get_bitbucket_project_for_repo"):
-            return self.state_store.get_bitbucket_project_for_repo(repo_key)
-        return None
-
-    def _infer_repo_language(self, repo_path: Path) -> str | None:
-        """Infer primary language from repo structure."""
-        top_level = {entry.name for entry in repo_path.iterdir()} if repo_path.is_dir() else set()
-
-        if "pom.xml" in top_level or any(f.endswith(".java") for f in top_level):
-            return "java"
-        if "build.gradle" in top_level or "build.gradle.kts" in top_level:
-            return "java"
-        if "go.mod" in top_level:
-            return "go"
-        if "package.json" in top_level:
-            return "typescript"
-        if "requirements.txt" in top_level or "pyproject.toml" in top_level:
-            return "python"
-        if "Gemfile" in top_level:
-            return "ruby"
-        return None
-
-    def write_topology_artifact(
-        self,
-        topology: ProjectTopology,
-        output_dir: Path,
-    ) -> Path:
-        """Persist project topology artifact as JSON."""
-        output_dir.mkdir(parents=True, exist_ok=True)
-        artifact_path = output_dir / "project-topology.json"
-
-        artifact_path.write_text(
-            topology.model_dump_json(indent=2, exclude_none=True),
-            encoding="utf-8",
-        )
-
-        self._logger.info(
-            "project_topology_artifact_written",
-            artifact_path=str(artifact_path),
-            repos_count=len(topology.repos),
-        )
-
-        return artifact_path
-
-
-# ---------------------------------------------------------------------------
-# TSK-113.3: Per-Repo Structure Extraction
-# ---------------------------------------------------------------------------
-
-
-class PerRepoStructureExtractor:
-    """Bounded per-repo structure extraction for cross-repo topology (FR-113.3).
-
-    Extracts imports, client/integration wiring, module manifests, and service
-    entrypoints needed to build normalized dependency edges.
-
-    Bounded by depth and file count limits (DD-113.3) to keep extraction
-    predictable and efficient.
-    """
-
-    def __init__(
-        self,
-        *,
-        max_scan_depth: int = _MAX_SCAN_DEPTH,
-        max_files_per_repo: int = _MAX_FILES_PER_REPO,
-        max_edges_per_repo: int = _MAX_EDGES_PER_REPO,
-    ) -> None:
-        self.max_scan_depth = max_scan_depth
-        self.max_files_per_repo = max_files_per_repo
-        self.max_edges_per_repo = max_edges_per_repo
-        self._logger = get_logger(__name__, component="PerRepoStructureExtractor")
-
-    def extract_from_repo(
-        self,
-        repo_path: Path,
-        repo_key: str,
-        language: str | None = None,
-    ) -> tuple[list[ModuleIdentity], list[DependencyEdge]]:
-        """Extract module identities and dependency edges from a single repo.
-
-        Args:
-            repo_path: Path to the cloned repository.
-            repo_key: Repository key for provenance.
-            language: Optional inferred language hint.
-
-        Returns:
-            Tuple of (module_identities, dependency_edges).
-        """
-        self._logger.info(
-            "repo_structure_extraction_starting",
-            repo_key=repo_key,
-            repo_path=str(repo_path),
-            language=language,
-        )
-
-        if not language:
-            language = self._detect_language(repo_path)
-
-        modules: list[ModuleIdentity] = []
-        edges: list[DependencyEdge] = []
-
-        if language == "java":
-            modules, edges = self._extract_java_structure(repo_path, repo_key)
-        elif language == "python":
-            modules, edges = self._extract_python_structure(repo_path, repo_key)
-        elif language == "go":
-            modules, edges = self._extract_go_structure(repo_path, repo_key)
-        elif language == "typescript":
-            modules, edges = self._extract_typescript_structure(repo_path, repo_key)
-        elif language == "kotlin":
-            modules, edges = self._extract_kotlin_structure(repo_path, repo_key)
-        else:
-            self._logger.warning(
-                "repo_language_not_supported",
-                repo_key=repo_key,
-                language=language,
-            )
-
-        self._logger.info(
-            "repo_structure_extraction_complete",
-            repo_key=repo_key,
-            modules_found=len(modules),
-            edges_found=len(edges),
-        )
-
-        return modules, edges
-
-    def _detect_language(self, repo_path: Path) -> str | None:
-        """Detect primary language from build files and directory structure."""
-        if not repo_path.is_dir():
-            return None
-
-        top_level = {entry.name for entry in repo_path.iterdir()}
-
-        if "pom.xml" in top_level or any(f.startswith("build.gradle") for f in top_level):
-            return "java"
-        if "requirements.txt" in top_level or "pyproject.toml" in top_level or "setup.py" in top_level:
-            return "python"
-        if "go.mod" in top_level:
-            return "go"
-        if "package.json" in top_level and "tsconfig.json" in top_level:
-            return "typescript"
-        if "build.gradle.kts" in top_level:
-            return "kotlin"
-        return None
-
-    def _extract_java_structure(
-        self,
-        repo_path: Path,
-        repo_key: str,
-    ) -> tuple[list[ModuleIdentity], list[DependencyEdge]]:
-        """Extract Java structure from Maven/Gradle projects."""
-        modules: list[ModuleIdentity] = []
-        edges: list[DependencyEdge] = []
-
-        # Find source roots (src/main/java, src/test/java)
-        source_roots = self._find_java_source_roots(repo_path)
-        scanned_files = 0
-
-        java_scan_depth = max(self.max_scan_depth, 8)
-
-        for source_root in source_roots:
-            if scanned_files >= self.max_files_per_repo:
-                break
-
-            for java_file in self._scan_files_by_extension(source_root, ".java", java_scan_depth):
-                scanned_files += 1
-                if scanned_files > self.max_files_per_repo:
-                    break
-
-                rel_path = java_file.relative_to(repo_path)
-                module_name = self._java_file_to_module(java_file, source_root, repo_path)
-                if not module_name:
-                    continue
-
-                module = ModuleIdentity(
-                    name=module_name,
-                    repo_key=repo_key,
-                    module_type=self._classify_java_module(java_file),
-                    language="java",
-                    source_path=str(rel_path),
-                    is_entrypoint=self._is_java_entrypoint(java_file),
-                )
-                modules.append(module)
-
-                # Extract import statements
-                file_edges = self._extract_java_imports(java_file, module, repo_key, repo_path)
-                edges.extend(file_edges)
-
-                if len(edges) >= self.max_edges_per_repo:
-                    break
-
-        return modules, edges[: self.max_edges_per_repo]
-
-    def _find_java_source_roots(self, repo_path: Path) -> list[Path]:
-        """Find standard Java source root directories."""
-        roots = []
-        candidates = [
-            repo_path / "src" / "main" / "java",
-            repo_path / "src" / "test" / "java",
-            repo_path / "src" / "main" / "kotlin",
-            repo_path / "src" / "main",
-        ]
-        for candidate in candidates:
-            if candidate.is_dir():
-                roots.append(candidate)
-        return roots
-
-    def _java_file_to_module(
-        self,
-        java_file: Path,
-        source_root: Path,
-        repo_root: Path,
-    ) -> str | None:
-        """Convert Java file path to fully qualified module name."""
-        try:
-            content = java_file.read_text(encoding="utf-8", errors="ignore")
-            package_match = _JAVA_PACKAGE_PATTERN.search(content)
-            if package_match:
-                package_name = package_match.group(1)
-                class_name = java_file.stem
-                return f"{package_name}.{class_name}"
-        except OSError:
-            pass
-
-        # Fallback: derive from path
-        relative = java_file.relative_to(source_root).parent
-        package = ".".join(relative.parts) if relative.parts else "default"
-        return f"{package}.{java_file.stem}"
-
-    def _classify_java_module(self, java_file: Path) -> str:
-        """Classify Java module type (spring_service, etc.)."""
-        try:
-            content = java_file.read_text(encoding="utf-8", errors="ignore")
-            if _SPRING_SERVICE_PATTERN.search(content):
-                return "spring_service"
-            if _MICRONAUT_CONTROLLER.search(content):
-                return "micronaut_controller"
-            if _QUARKUS_PATH.search(content):
-                return "quarkus_resource"
-        except OSError:
-            pass
-        return "java_class"
-
-    def _is_java_entrypoint(self, java_file: Path) -> bool:
-        """Check if Java file is a service entrypoint."""
-        try:
-            content = java_file.read_text(encoding="utf-8", errors="ignore")
-            if _SPRING_REQUEST_MAPPING.search(content):
-                return True
-            if _QUARKUS_PATH.search(content):
-                return True
-            if "@GET" in content or "@POST" in content or "@PUT" in content:
-                return True
-        except OSError:
-            pass
-        return False
-
-    def _extract_java_imports(
-        self,
-        java_file: Path,
-        source_module: ModuleIdentity,
-        repo_key: str,
-        repo_root: Path,
-    ) -> list[DependencyEdge]:
-        """Extract import statements from Java file."""
-        edges = []
-        try:
-            lines = java_file.read_text(encoding="utf-8", errors="ignore").splitlines()
-            for line_no, line in enumerate(lines, 1):
-                match = _JAVA_IMPORT_PATTERN.match(line.strip())
-                if match:
-                    target_module = match.group(1)
-                    # Determine if cross-repo by checking package structure
-                    target_repo = self._resolve_import_target_repo(target_module, repo_key, repo_root)
-                    edge = DependencyEdge(
-                        source_module=source_module.name,
-                        target_module=target_module,
-                        source_repo=repo_key,
-                        target_repo=target_repo,
-                        edge_source=EdgeSource.IMPORT_STATEMENT,
-                        source_file=str(source_module.source_path),
-                        line_number=line_no,
-                    )
-                    edges.append(edge)
-        except OSError:
-            pass
-        return edges
-
-    def _resolve_import_target_repo(
-        self,
-        import_package: str,
-        current_repo: str,
-        repo_root: Path,
-    ) -> str:
-        """Resolve target repo for an import (simplified heuristic)."""
-        # For now, assume imports within current repo's base package are intra-repo
-        # This is a simplified heuristic - full implementation would scan all repos
-        import_package.split(".", maxsplit=1)[0]
-        return current_repo  # Default to same repo for bounded extraction
-
-    def _extract_python_structure(
-        self,
-        repo_path: Path,
-        repo_key: str,
-    ) -> tuple[list[ModuleIdentity], list[DependencyEdge]]:
-        """Extract Python structure from setup.py/pyproject.toml and source."""
-        modules: list[ModuleIdentity] = []
-        edges: list[DependencyEdge] = []
-
-        # Scan Python files
-        scanned_files = 0
-        for py_file in self._scan_files_by_extension(repo_path, ".py", self.max_scan_depth):
-            scanned_files += 1
-            if scanned_files > self.max_files_per_repo:
-                break
-
-            rel_path = py_file.relative_to(repo_path)
-            module_name = self._python_file_to_module(py_file, repo_path)
-            if not module_name:
-                continue
-
-            module = ModuleIdentity(
-                name=module_name,
-                repo_key=repo_key,
-                module_type=self._classify_python_module(py_file),
-                language="python",
-                source_path=str(rel_path),
-                is_entrypoint=self._is_python_entrypoint(py_file),
-            )
-            modules.append(module)
-
-            file_edges = self._extract_python_imports(py_file, module, repo_key, repo_path)
-            edges.extend(file_edges)
-
-            if len(edges) >= self.max_edges_per_repo:
-                break
-
-        return modules, edges[: self.max_edges_per_repo]
-
-    def _python_file_to_module(self, py_file: Path, repo_root: Path) -> str | None:
-        """Convert Python file path to module name."""
-        relative = py_file.relative_to(repo_root)
-        parts = list(relative.parts[:-1])  # Directory path
-        if py_file.stem != "__init__":
-            parts.append(py_file.stem)
-        return ".".join(parts) if parts else py_file.stem
-
-    def _classify_python_module(self, py_file: Path) -> str:
-        """Classify Python module type."""
-        try:
-            content = py_file.read_text(encoding="utf-8", errors="ignore")
-            if "FastAPI" in content or "APIRouter" in content:
-                return "fastapi_app"
-            if "Flask" in content or "@app.route" in content:
-                return "flask_app"
-            if "Django" in content:
-                return "django_app"
-        except OSError:
-            pass
-        return "python_module"
-
-    def _is_python_entrypoint(self, py_file: Path) -> bool:
-        """Check if Python file is a service entrypoint."""
-        try:
-            content = py_file.read_text(encoding="utf-8", errors="ignore")
-            if "@app." in content or "APIRouter" in content or "FastAPI" in content:
-                return True
-        except OSError:
-            pass
-        return False
-
-    def _extract_python_imports(
-        self,
-        py_file: Path,
-        source_module: ModuleIdentity,
-        repo_key: str,
-        repo_root: Path,
-    ) -> list[DependencyEdge]:
-        """Extract import statements from Python file."""
-        edges = []
-        try:
-            lines = py_file.read_text(encoding="utf-8", errors="ignore").splitlines()
-            for line_no, line in enumerate(lines, 1):
-                match = _PYTHON_IMPORT_PATTERN.match(line.strip())
-                if match:
-                    target_module = match.group(1) or match.group(2)
-                    if target_module:
-                        edge = DependencyEdge(
-                            source_module=source_module.name,
-                            target_module=target_module,
-                            source_repo=repo_key,
-                            target_repo=repo_key,  # Default to same repo
-                            edge_source=EdgeSource.IMPORT_STATEMENT,
-                            source_file=str(source_module.source_path),
-                            line_number=line_no,
-                        )
-                        edges.append(edge)
-        except OSError:
-            pass
-        return edges
-
-    def _extract_go_structure(
-        self,
-        repo_path: Path,
-        repo_key: str,
-    ) -> tuple[list[ModuleIdentity], list[DependencyEdge]]:
-        """Extract Go structure from go.mod and source."""
-        modules: list[ModuleIdentity] = []
-        edges: list[DependencyEdge] = []
-
-        # Extract module name from go.mod
-        module_prefix = ""
-        go_mod = repo_path / "go.mod"
-        if go_mod.exists():
-            try:
-                content = go_mod.read_text(encoding="utf-8")
-                for line in content.splitlines():
-                    if line.startswith("module "):
-                        module_prefix = line.split()[1]
-                        break
-            except OSError:
-                pass
-
-        scanned_files = 0
-        for go_file in self._scan_files_by_extension(repo_path, ".go", self.max_scan_depth):
-            scanned_files += 1
-            if scanned_files > self.max_files_per_repo:
-                break
-
-            rel_path = go_file.relative_to(repo_path)
-            package_name = self._extract_go_package(go_file)
-            module_name = f"{module_prefix}/{rel_path.parent.as_posix()}" if module_prefix else str(rel_path)
-            if package_name:
-                module_name = f"{module_name}:{package_name}"
-
-            module = ModuleIdentity(
-                name=module_name,
-                repo_key=repo_key,
-                module_type="go_package",
-                language="go",
-                source_path=str(rel_path),
-                is_entrypoint=self._is_go_entrypoint(go_file),
-            )
-            modules.append(module)
-
-            file_edges = self._extract_go_imports(go_file, module, repo_key)
-            edges.extend(file_edges)
-
-            if len(edges) >= self.max_edges_per_repo:
-                break
-
-        return modules, edges[: self.max_edges_per_repo]
-
-    def _extract_go_package(self, go_file: Path) -> str | None:
-        """Extract package name from Go file."""
-        try:
-            content = go_file.read_text(encoding="utf-8", errors="ignore")
-            match = _GO_PACKAGE_PATTERN.search(content)
-            return match.group(1) if match else None
-        except OSError:
-            return None
-
-    def _is_go_entrypoint(self, go_file: Path) -> bool:
-        """Check if Go file is a service entrypoint."""
-        try:
-            content = go_file.read_text(encoding="utf-8", errors="ignore")
-            if "func main" in content or "http.HandleFunc" in content or "http.ListenAndServe" in content:
-                return True
-        except OSError:
-            pass
-        return False
-
-    def _extract_go_imports(
-        self,
-        go_file: Path,
-        source_module: ModuleIdentity,
-        repo_key: str,
-    ) -> list[DependencyEdge]:
-        """Extract import statements from Go file."""
-        edges = []
-        try:
-            lines = go_file.read_text(encoding="utf-8", errors="ignore").splitlines()
-            for line_no, line in enumerate(lines, 1):
-                match = _GO_IMPORT_PATTERN.match(line.strip())
-                if match:
-                    target_module = match.group(1) or match.group(2)
-                    if target_module and not target_module.startswith('"'):
-                        edge = DependencyEdge(
-                            source_module=source_module.name,
-                            target_module=target_module,
-                            source_repo=repo_key,
-                            target_repo=repo_key,
-                            edge_source=EdgeSource.IMPORT_STATEMENT,
-                            source_file=str(source_module.source_path),
-                            line_number=line_no,
-                        )
-                        edges.append(edge)
-        except OSError:
-            pass
-        return edges
-
-    def _extract_typescript_structure(
-        self,
-        repo_path: Path,
-        repo_key: str,
-    ) -> tuple[list[ModuleIdentity], list[DependencyEdge]]:
-        """Extract TypeScript structure."""
-        modules: list[ModuleIdentity] = []
-        edges: list[DependencyEdge] = []
-
-        # Scan TS/TSX files
-        scanned_files = 0
-        for ext in (".ts", ".tsx"):
-            for ts_file in self._scan_files_by_extension(repo_path, ext, self.max_scan_depth):
-                scanned_files += 1
-                if scanned_files > self.max_files_per_repo:
-                    break
-
-                rel_path = ts_file.relative_to(repo_path)
-                module_name = str(rel_path.with_suffix(""))
-
-                module = ModuleIdentity(
-                    name=module_name,
-                    repo_key=repo_key,
-                    module_type=self._classify_typescript_module(ts_file),
-                    language="typescript",
-                    source_path=str(rel_path),
-                    is_entrypoint=self._is_typescript_entrypoint(ts_file),
-                )
-                modules.append(module)
-
-                file_edges = self._extract_typescript_imports(ts_file, module, repo_key)
-                edges.extend(file_edges)
-
-                if len(edges) >= self.max_edges_per_repo:
-                    break
-
-        return modules, edges[: self.max_edges_per_repo]
-
-    def _classify_typescript_module(self, ts_file: Path) -> str:
-        """Classify TypeScript module type."""
-        if ts_file.stem.endswith(".service") or ts_file.stem.endswith(".controller"):
-            return "angular_service"
-        if ts_file.stem.endswith(".component"):
-            return "angular_component"
-        return "typescript_module"
-
-    def _is_typescript_entrypoint(self, ts_file: Path) -> bool:
-        """Check if TypeScript file is a service entrypoint."""
-        try:
-            content = ts_file.read_text(encoding="utf-8", errors="ignore")
-            if "@Controller" in content or "@Injectable" in content:
-                return True
-            if "app.use" in content or "router." in content:
-                return True
-        except OSError:
-            pass
-        return False
-
-    def _extract_typescript_imports(
-        self,
-        ts_file: Path,
-        source_module: ModuleIdentity,
-        repo_key: str,
-    ) -> list[DependencyEdge]:
-        """Extract import statements from TypeScript file."""
-        edges = []
-        try:
-            lines = ts_file.read_text(encoding="utf-8", errors="ignore").splitlines()
-            for line_no, line in enumerate(lines, 1):
-                match = _TS_IMPORT_PATTERN.search(line)
-                if match:
-                    target_module = match.group(1)
-                    if target_module and not target_module.startswith("."):
-                        edge = DependencyEdge(
-                            source_module=source_module.name,
-                            target_module=target_module,
-                            source_repo=repo_key,
-                            target_repo=repo_key,
-                            edge_source=EdgeSource.IMPORT_STATEMENT,
-                            source_file=str(source_module.source_path),
-                            line_number=line_no,
-                        )
-                        edges.append(edge)
-        except OSError:
-            pass
-        return edges
-
-    def _extract_kotlin_structure(
-        self,
-        repo_path: Path,
-        repo_key: str,
-    ) -> tuple[list[ModuleIdentity], list[DependencyEdge]]:
-        """Extract Kotlin structure (similar to Java)."""
-        # Reuse Java extraction patterns with Kotlin-specific tweaks
-        modules: list[ModuleIdentity] = []
-        edges: list[DependencyEdge] = []
-
-        source_roots = self._find_java_source_roots(repo_path)  # Kotlin uses same structure
-        scanned_files = 0
-
-        kotlin_scan_depth = max(self.max_scan_depth, 8)
-
-        for source_root in source_roots:
-            if scanned_files >= self.max_files_per_repo:
-                break
-
-            for kt_file in self._scan_files_by_extension(source_root, ".kt", kotlin_scan_depth):
-                scanned_files += 1
-                if scanned_files > self.max_files_per_repo:
-                    break
-
-                rel_path = kt_file.relative_to(repo_path)
-                module_name = self._java_file_to_module(kt_file, source_root, repo_path)  # Reuse logic
-                if not module_name:
-                    continue
-
-                module = ModuleIdentity(
-                    name=module_name,
-                    repo_key=repo_key,
-                    module_type=self._classify_kotlin_module(kt_file),
-                    language="kotlin",
-                    source_path=str(rel_path),
-                    is_entrypoint=self._is_java_entrypoint(kt_file),  # Reuse detection
-                )
-                modules.append(module)
-
-                file_edges = self._extract_kotlin_imports(kt_file, module, repo_key, repo_path)
-                edges.extend(file_edges)
-
-                if len(edges) >= self.max_edges_per_repo:
-                    break
-
-        return modules, edges[: self.max_edges_per_repo]
-
-    def _classify_kotlin_module(self, kt_file: Path) -> str:
-        """Classify Kotlin module type."""
-        try:
-            content = kt_file.read_text(encoding="utf-8", errors="ignore")
-            if _SPRING_SERVICE_PATTERN.search(content):
-                return "spring_service"
-            if "Ktor" in content:
-                return "ktor_route"
-        except OSError:
-            pass
-        return "kotlin_class"
-
-    def _extract_kotlin_imports(
-        self,
-        kt_file: Path,
-        source_module: ModuleIdentity,
-        repo_key: str,
-        repo_root: Path,
-    ) -> list[DependencyEdge]:
-        """Extract import statements from Kotlin file."""
-        edges = []
-        try:
-            lines = kt_file.read_text(encoding="utf-8", errors="ignore").splitlines()
-            for line_no, line in enumerate(lines, 1):
-                match = _KOTLIN_IMPORT_PATTERN.match(line.strip())
-                if match:
-                    target_module = match.group(1)
-                    if target_module:
-                        edge = DependencyEdge(
-                            source_module=source_module.name,
-                            target_module=target_module,
-                            source_repo=repo_key,
-                            target_repo=repo_key,
-                            edge_source=EdgeSource.IMPORT_STATEMENT,
-                            source_file=str(source_module.source_path),
-                            line_number=line_no,
-                        )
-                        edges.append(edge)
-        except OSError:
-            pass
-        return edges
-
-    def _scan_files_by_extension(
-        self,
-        root: Path,
-        extension: str,
-        max_depth: int,
-    ) -> Iterator[Path]:
-        """Recursively scan files by extension up to max_depth."""
-        if not root.is_dir():
-            return
-
-        for entry in root.iterdir():
-            if entry.is_file() and entry.name.endswith(extension):
-                yield entry
-            elif entry.is_dir() and max_depth > 0 and not entry.name.startswith("."):
-                yield from self._scan_files_by_extension(entry, extension, max_depth - 1)
-
-
-# ---------------------------------------------------------------------------
-# TSK-113.4: Deterministic Graph Artifact Builder
-# ---------------------------------------------------------------------------
-
-
-class DependencyGraphBuilder:
-    """Build deterministic dependency graph and cycle reports (FR-113.3).
-
-    Normalizes extracted structure into:
-    - ``project-dependency-graph.json`` with edge provenance (AC-113.3.4)
-    - ``project-cycle-report.json`` with deterministic cycle checks (AC-113.3.3)
-
-    The results are authoritative for cross-repo dependency/coupling rows
-    (DD-113.5) - LLM reasoning may explain but must not replace graph results.
-    """
-
-    def __init__(
-        self,
-        *,
-        topology: ProjectTopology | None = None,
-    ) -> None:
-        self.topology = topology
-        self._logger = get_logger(__name__, component="DependencyGraphBuilder")
-
-    def build_graph(
-        self,
-        all_modules: list[ModuleIdentity],
-        all_edges: list[DependencyEdge],
-        project_storage_key: str,
-    ) -> ProjectDependencyGraph:
-        """Build normalized dependency graph artifact.
-
-        Args:
-            all_modules: All module identities from participating repos.
-            all_edges: All extracted dependency edges.
-            project_storage_key: Project key for provenance.
-
-        Returns:
-            ``ProjectDependencyGraph`` with nodes, edges, and provenance.
-        """
-        self._logger.info(
-            "dependency_graph_building",
-            project_storage_key=project_storage_key,
-            modules_count=len(all_modules),
-            edges_count=len(all_edges),
-        )
-
-        # Build node index
-        nodes: dict[str, dict[str, Any]] = {}
-        for module in all_modules:
-            nodes[module.name] = {
-                "repo_key": module.repo_key,
-                "module_type": module.module_type,
-                "language": module.language,
-                "source_path": module.source_path,
-                "is_entrypoint": module.is_entrypoint,
-            }
-
-        # Normalize edges to dicts with provenance
-        edges: list[dict[str, Any]] = []
-        cross_repo_edges: list[dict[str, Any]] = []
-
-        # Sort edges deterministically (NFR-113.1)
-        sorted_edges = sorted(
-            all_edges,
-            key=lambda e: (e.source_module, e.target_module, e.source_repo, e.target_repo),
-        )
-
-        for edge in sorted_edges:
-            edge_dict = {
-                "source": edge.source_module,
-                "target": edge.target_module,
-                "source_repo": edge.source_repo,
-                "target_repo": edge.target_repo,
-                "dependency_type": edge.dependency_type.value,
-                "edge_source": edge.edge_source.value,
-                "source_file": edge.source_file,
-                "line_number": edge.line_number,
-                "evidence_snippet": edge.evidence_snippet,
-                "is_cross_repo": edge.source_repo != edge.target_repo,
-            }
-            edges.append(edge_dict)
-
-            if edge.source_repo != edge.target_repo:
-                cross_repo_edges.append(edge_dict)
-
-        graph = ProjectDependencyGraph(
-            project_storage_key=project_storage_key,
-            nodes=nodes,
-            edges=edges,
-            cross_repo_edges=cross_repo_edges,
-            generated_at=datetime.now(UTC),
-            provenance={
-                "topology_source": "per_repo_structure_extraction",
-                "total_modules": len(nodes),
-                "total_edges": len(edges),
-                "cross_repo_edges": len(cross_repo_edges),
-            },
-        )
-
-        self._logger.info(
-            "dependency_graph_built",
-            nodes_count=len(nodes),
-            edges_count=len(edges),
-            cross_repo_count=len(cross_repo_edges),
-        )
-
-        return graph
-
-    def detect_cycles(
-        self,
-        graph: ProjectDependencyGraph,
-    ) -> ProjectCycleReport:
-        """Detect circular dependencies and layering violations (AC-113.3.3).
-
-        Uses deterministic algorithms (Tarjan's for SCCs, DFS for paths)
-        to ensure reproducible results (NFR-113.1).
-
-        Args:
-            graph: The dependency graph to analyze.
-
-        Returns:
-            ``ProjectCycleReport`` with authoritative findings.
-        """
-        self._logger.info(
-            "cycle_detection_starting",
-            project_storage_key=graph.project_storage_key,
-            edges_count=len(graph.edges),
-        )
-
-        # Build adjacency list for cycle detection
-        adjacency = self._build_adjacency_list(graph)
-        node_to_repo = self._build_node_to_repo_map(graph)
-
-        circular_cycles: list[dict[str, Any]] = []
-        forbidden_layer_violations: list[dict[str, Any]] = []
-        cross_repo_couplings: list[dict[str, Any]] = []
-
-        # Detect SCCs using Tarjan's algorithm
-        sccs = self._tarjan_scc(adjacency)
-
-        for scc in sccs:
-            if len(scc) > 1:
-                # Found a cycle
-                cycle_edges = self._extract_cycle_path(scc, graph.edges)
-                involved_repos = {node_to_repo.get(n, "unknown") for n in scc}
-
-                finding = CycleFinding(
-                    cycle_type="circular",
-                    involved_modules=list(scc),
-                    involved_repos=involved_repos,
-                    path=cycle_edges,
-                    severity="error",
-                    description=f"Circular dependency detected involving {len(scc)} modules",
-                )
-
-                circular_cycles.append(finding.to_dict())
-
-        # Analyze cross-repo couplings
-        for edge_dict in graph.cross_repo_edges:
-            coupling_key = (
-                edge_dict["source_repo"],
-                edge_dict["target_repo"],
-            )
-            cross_repo_couplings.append(
-                {
-                    "source_repo": coupling_key[0],
-                    "target_repo": coupling_key[1],
-                    "source_module": edge_dict["source"],
-                    "target_module": edge_dict["target"],
-                    "edge_source": edge_dict["edge_source"],
-                }
-            )
-
-        report = ProjectCycleReport(
-            project_storage_key=graph.project_storage_key,
-            total_edges_analyzed=len(graph.edges),
-            circular_cycles=circular_cycles,
-            forbidden_layer_violations=forbidden_layer_violations,
-            cross_repo_couplings=cross_repo_couplings,
-            layering_summary={
-                "cycles_found": len(circular_cycles),
-                "cross_repo_couplings": len(cross_repo_couplings),
-                "layer_violations": len(forbidden_layer_violations),
-            },
-            generated_at=datetime.now(UTC),
-            graph_artifact_reference="project-dependency-graph.json",
-        )
-
-        self._logger.info(
-            "cycle_detection_complete",
-            cycles_found=len(circular_cycles),
-            cross_repo_couplings=len(cross_repo_couplings),
-        )
-
-        return report
-
-    def _build_adjacency_list(
-        self,
-        graph: ProjectDependencyGraph,
-    ) -> dict[str, set[str]]:
-        """Build adjacency list from graph edges."""
-        adjacency: dict[str, set[str]] = {}
-        for edge in graph.edges:
-            source = edge["source"]
-            target = edge["target"]
-            if source not in adjacency:
-                adjacency[source] = set()
-            adjacency[source].add(target)
-        return adjacency
-
-    def _build_node_to_repo_map(
-        self,
-        graph: ProjectDependencyGraph,
-    ) -> dict[str, str]:
-        """Map module names to their repo keys."""
-        node_to_repo: dict[str, str] = {}
-        for node_name, node_data in graph.nodes.items():
-            node_to_repo[node_name] = node_data.get("repo_key", "unknown")
-        return node_to_repo
-
-    def _tarjan_scc(
-        self,
-        adjacency: dict[str, set[str]],
-    ) -> list[set[str]]:
-        """Tarjan's strongly connected components algorithm.
-
-        Returns SCCs with size > 1 (cycles).
-        Deterministic implementation for reproducibility (NFR-113.1).
-        """
-        index_counter = [0]
-        stack: list[str] = []
-        lowlink: dict[str, int] = {}
-        index: dict[str, int] = {}
-        on_stack: dict[str, bool] = {}
-        sccs: list[set[str]] = []
-
-        def strongconnect(v: str) -> None:
-            index[v] = index_counter[0]
-            lowlink[v] = index_counter[0]
-            index_counter[0] += 1
-            stack.append(v)
-            on_stack[v] = True
-
-            for w in sorted(adjacency.get(v, set())):  # Sort for determinism
-                if w not in index:
-                    strongconnect(w)
-                    lowlink[v] = min(lowlink[v], lowlink[w])
-                elif on_stack.get(w, False):
-                    lowlink[v] = min(lowlink[v], index[w])
-
-            if lowlink[v] == index[v]:
-                # Start a new SCC
-                scc: set[str] = set()
-                while True:
-                    w = stack.pop()
-                    on_stack[w] = False
-                    scc.add(w)
-                    if w == v:
-                        break
-                if len(scc) > 1:
-                    sccs.append(scc)
-
-        # Process nodes in sorted order for determinism
-        for v in sorted(adjacency.keys()):
-            if v not in index:
-                strongconnect(v)
-
-        return sccs
-
-    def _extract_cycle_path(
-        self,
-        scc_nodes: set[str],
-        all_edges: list[dict[str, Any]],
-    ) -> list[DependencyEdge]:
-        """Extract the cycle path from SCC nodes."""
-        # Build subgraph of SCC
-        scc_edges = [e for e in all_edges if e["source"] in scc_nodes and e["target"] in scc_nodes]
-
-        # Convert to DependencyEdge objects
-        path_edges = []
-        for e in scc_edges:
-            path_edges.append(
-                DependencyEdge(
-                    source_module=e["source"],
-                    target_module=e["target"],
-                    source_repo=e["source_repo"],
-                    target_repo=e["target_repo"],
-                    dependency_type=DependencyType(e.get("dependency_type", "direct")),
-                    edge_source=EdgeSource(e.get("edge_source", "import_statement")),
-                    source_file=e.get("source_file"),
-                    line_number=e.get("line_number"),
-                )
-            )
-
-        return path_edges
-
-    def write_graph_artifact(
-        self,
-        graph: ProjectDependencyGraph,
-        output_dir: Path,
-    ) -> Path:
-        """Persist dependency graph artifact as JSON."""
-        output_dir.mkdir(parents=True, exist_ok=True)
-        artifact_path = output_dir / "project-dependency-graph.json"
-
-        artifact_path.write_text(
-            graph.model_dump_json(indent=2, exclude_none=True),
-            encoding="utf-8",
-        )
-
-        self._logger.info(
-            "dependency_graph_artifact_written",
-            artifact_path=str(artifact_path),
-        )
-
-        return artifact_path
-
-    def write_cycle_report_artifact(
-        self,
-        report: ProjectCycleReport,
-        output_dir: Path,
-    ) -> Path:
-        """Persist cycle report artifact as JSON."""
-        output_dir.mkdir(parents=True, exist_ok=True)
-        artifact_path = output_dir / "project-cycle-report.json"
-
-        artifact_path.write_text(
-            report.model_dump_json(indent=2, exclude_none=True),
-            encoding="utf-8",
-        )
-
-        self._logger.info(
-            "cycle_report_artifact_written",
-            artifact_path=str(artifact_path),
-        )
-
-        return artifact_path
-
-
-# ---------------------------------------------------------------------------
-# Convenience: Combined Workflow (TSK-113.2 + TSK-113.3 + TSK-113.4)
-# ---------------------------------------------------------------------------
-
-
-def build_project_topology_artifacts(
-    *,
-    state_store: Any,
-    project_storage_key: str,
-    repo_cache_root: Path,
-    output_dir: Path,
-    thread_id: str | None = None,
-    run_id: str | None = None,
-) -> tuple[ProjectTopology, ProjectDependencyGraph, ProjectCycleReport]:
-    """End-to-end workflow for building all Phase 113 project artifacts.
-
-    This is the main entry point for TSK-113.2 through TSK-113.4, combining:
-    1. Project topology resolution (FR-113.2)
-    2. Per-repo structure extraction (FR-113.3)
-    3. Dependency graph and cycle report generation (FR-113.3)
-
-    Args:
-        state_store: Centralized state store instance.
-        project_storage_key: Confluence numeric page_id for the project.
-        repo_cache_root: Root path for repo cache.
-        output_dir: Directory to write artifact JSON files.
-        thread_id: Optional thread ID for provenance.
-        run_id: Optional run ID for provenance.
-
-    Returns:
-        Tuple of (topology, graph, cycle_report) artifacts.
-
-    Raises:
-        ValueError: If project topology cannot be resolved (AC-113.2.4).
-    """
-    resolver = ProjectTopologyResolver(
-        state_store=state_store,
-        repo_cache_root=repo_cache_root,
-    )
-
-    topology = resolver.resolve_from_state(
-        project_storage_key=project_storage_key,
-        thread_id=thread_id,
-        run_id=run_id,
-    )
-
-    resolver.write_topology_artifact(topology, output_dir)
-
-    # Extract structure from each repo
-    extractor = PerRepoStructureExtractor()
-    all_modules: list[ModuleIdentity] = []
-    all_edges: list[DependencyEdge] = []
-
-    for repo_entry in topology.repos:
-        repo_path = Path(repo_entry.repo_path)
-        modules, edges = extractor.extract_from_repo(
-            repo_path=repo_path,
-            repo_key=repo_entry.repo_key,
-            language=repo_entry.language,
-        )
-        all_modules.extend(modules)
-        all_edges.extend(edges)
-
-    # Build graph and detect cycles
-    graph_builder = DependencyGraphBuilder(topology=topology)
-    graph = graph_builder.build_graph(
-        all_modules=all_modules,
-        all_edges=all_edges,
-        project_storage_key=project_storage_key,
-    )
-    graph_builder.write_graph_artifact(graph, output_dir)
-
-    cycle_report = graph_builder.detect_cycles(graph)
-    graph_builder.write_cycle_report_artifact(cycle_report, output_dir)
-
-    return topology, graph, cycle_report