@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/circular_dependency_orchestrator/src/vds_circular_dependency_orchestrator/cli.py

@@ -1,904 +0,0 @@
-"""CLI for circular dependency analysis across multi-repository VDS projects."""
-
-from __future__ import annotations
-
-import importlib.metadata as metadata
-import json
-import sys
-import xml.etree.ElementTree as ET
-from dataclasses import dataclass
-from enum import IntEnum
-from pathlib import Path
-from typing import Any
-
-import structlog
-import typer
-from rich.console import Console
-
-APP_NAME = "vds-circular-dependency"
-NS = {"m": "http://maven.apache.org/POM/4.0.0"}
-ALLOWED_SCOPES = {"repo", "artifact", "module", "full-project"}
-IGNORED_MAVEN_SCOPES = {"test", "provided", "import"}
-PACKAGE_MANIFEST_NAMES = ("package.json",)
-POM_NAME = "pom.xml"
-IGNORED_DIR_NAMES = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build", "target"}
-IGNORED_PATH_SUFFIXES = (".corrupted",)
-PRESET_REPO_NAMES = {
-    "PAR": {
-        "merchant-billing",
-        "merchant-proc",
-        "merchant-profile-fe",
-        "merchant-profile-service",
-        "merchant-report",
-        "merchant-transaction",
-    },
-    "INSURANCE": {
-        "insurance-customer-business",
-        "insurance-policy-business",
-        "insurance-insurer-service",
-        "insurance-customer-webview",
-    },
-}
-
-
-class ExitCode(IntEnum):
-    NO_CYCLE = 0
-    ERROR = 1
-    CYCLE_FOUND = 2
-    PARTIAL_ANALYSIS = 3
-
-
-app = typer.Typer(
-    name=APP_NAME,
-    help="Circular dependency analysis operations for multi-repository VDS projects.",
-    add_completion=False,
-    no_args_is_help=True,
-)
-console = Console(stderr=True)
-_cli_state: dict[str, Any] = {"json_only": False}
-
-
-@dataclass(frozen=True)
-class EvidenceRef:
-    source_type: str
-    path: str
-    line: int | None
-    detail: str
-
-
-@dataclass(frozen=True)
-class ArtifactDependency:
-    target_name: str
-    target_key: str
-    ecosystem: str
-    scope: str
-    is_internal: bool
-    has_internal_signal: bool
-    evidence: EvidenceRef
-
-
-@dataclass(frozen=True)
-class RepoManifest:
-    repo_name: str
-    repo_path: Path
-    ecosystem: str
-    artifact_name: str
-    artifact_key: str
-    evidence: EvidenceRef
-    dependencies: tuple[ArtifactDependency, ...]
-
-
-@dataclass(frozen=True)
-class IgnoredInput:
-    path: str
-    reason: str
-
-
-@dataclass(frozen=True)
-class GraphEdge:
-    source: str
-    target: str
-    scope: str
-    ecosystem: str
-    classification: str
-    evidence_refs: tuple[EvidenceRef, ...]
-
-
-def _emit_json(payload: dict[str, Any]) -> None:
-    text = json.dumps(payload, indent=2, sort_keys=True)
-    if sys.stdout.isatty():
-        typer.echo(text)
-    else:
-        sys.stdout.write(text + "\n")
-
-
-def _version_callback(value: bool | None) -> bool | None:
-    if value:
-        try:
-            version = metadata.version("vds-circular-dependency-orchestrator")
-        except metadata.PackageNotFoundError:
-            version = "unknown"
-        typer.echo(f"{APP_NAME} {version}")
-        raise typer.Exit()
-    return value
-
-
-@app.callback()
-def cli_main(
-    version: bool = typer.Option(False, "--version", callback=_version_callback, is_eager=True),
-    json_only: bool = typer.Option(False, "--json-only", help="Emit JSON output only."),
-    structured_logs: bool = typer.Option(
-        False,
-        "--structured-logs/--no-structured-logs",
-        help="Emit JSON structured logs via structlog.",
-    ),
-) -> None:
-    _cli_state["json_only"] = json_only
-    if structured_logs:
-        structlog.configure(
-            processors=[
-                structlog.stdlib.filter_by_level,
-                structlog.stdlib.add_log_level,
-                structlog.processors.TimeStamper(fmt="iso"),
-                structlog.processors.JSONRenderer(),
-            ],
-            logger_factory=structlog.stdlib.LoggerFactory(),
-            wrapper_class=structlog.stdlib.BoundLogger,
-        )
-
-
-def _text_lines(path: Path) -> list[str]:
-    return path.read_text(encoding="utf-8").splitlines()
-
-
-def _find_line_number(lines: list[str], needle: str) -> int | None:
-    for index, line in enumerate(lines, start=1):
-        if needle in line:
-            return index
-    return None
-
-
-def _normalize_name(name: str) -> str:
-    return name.strip()
-
-
-def _is_ignored_directory(path: Path) -> tuple[bool, str | None]:
-    name = path.name
-    if name in IGNORED_DIR_NAMES:
-        return True, f"ignored_dir:{name}"
-    for suffix in IGNORED_PATH_SUFFIXES:
-        if suffix in name:
-            return True, f"ignored_suffix:{suffix}"
-    return False, None
-
-
-def _maven_key(group_id: str, artifact_id: str) -> str:
-    return f"maven:{group_id}:{artifact_id}"
-
-
-def _npm_key(name: str) -> str:
-    return f"npm:{name}"
-
-
-def _looks_internal_maven_dependency(group_id: str, artifact_id: str) -> bool:
-    internal_group_prefixes = (
-        "vn.com.viettel.vds",
-        "vn.com.viettel",
-    )
-    internal_name_prefixes = (
-        "vds-",
-        "viettel",
-    )
-    internal_name_exact = {
-        "auth-utils",
-        "client-lib",
-        "internal-cache-lib",
-        "handle-otp",
-        "insurance-insuremo-common",
-        "vds-otp-adapter",
-    }
-    return (
-        group_id.startswith(internal_group_prefixes)
-        or artifact_id.startswith(internal_name_prefixes)
-        or artifact_id in internal_name_exact
-    )
-
-
-def _manifest_ref(path: Path, detail: str, line: int | None) -> EvidenceRef:
-    return EvidenceRef(source_type="manifest", path=str(path.resolve()), line=line, detail=detail)
-
-
-def _child_text(element: ET.Element, tag: str) -> str | None:
-    child = element.find(f"m:{tag}", NS)
-    if child is None or child.text is None:
-        return None
-    return child.text.strip()
-
-
-def _discover_repo_roots(project_root: Path, repo_paths: list[Path]) -> tuple[list[Path], list[IgnoredInput]]:
-    ignored: list[IgnoredInput] = []
-    if repo_paths:
-        roots: list[Path] = []
-        for path in repo_paths:
-            resolved = path.resolve()
-            is_ignored, reason = _is_ignored_directory(resolved)
-            if is_ignored and reason is not None:
-                ignored.append(IgnoredInput(path=str(resolved), reason=reason))
-                continue
-            roots.append(resolved)
-    else:
-        roots = sorted(
-            {
-                path.parent.resolve()
-                for pattern in (POM_NAME, *PACKAGE_MANIFEST_NAMES)
-                for path in project_root.rglob(pattern)
-                if not any(part in IGNORED_DIR_NAMES for part in path.parts)
-            },
-            key=lambda item: str(item),
-        )
-    filtered: list[Path] = []
-    for root in roots:
-        if not root.is_dir():
-            continue
-        is_ignored, reason = _is_ignored_directory(root)
-        if is_ignored and reason is not None:
-            ignored.append(IgnoredInput(path=str(root), reason=reason))
-            continue
-        filtered.append(root)
-    return filtered, sorted(ignored, key=lambda item: (item.reason, item.path))
-
-
-def _parse_maven_manifest(path: Path, repo_root: Path) -> RepoManifest | None:
-    try:
-        tree = ET.parse(path)
-    except ET.ParseError:
-        return None
-
-    root = tree.getroot()
-    group_id = _child_text(root, "groupId")
-    artifact_id = _child_text(root, "artifactId")
-    version = _child_text(root, "version")
-
-    parent = root.find("m:parent", NS)
-    if parent is not None:
-        group_id = group_id or _child_text(parent, "groupId")
-        version = version or _child_text(parent, "version")
-
-    if not artifact_id:
-        return None
-
-    lines = _text_lines(path)
-    artifact_line = _find_line_number(lines, f"<artifactId>{artifact_id}</artifactId>")
-    artifact_key = _maven_key(group_id or "unknown", artifact_id)
-    dependencies: list[ArtifactDependency] = []
-
-    for dependency in root.findall("m:dependencies/m:dependency", NS):
-        dep_group_id = _child_text(dependency, "groupId") or "unknown"
-        dep_artifact_id = _child_text(dependency, "artifactId")
-        dep_scope = _child_text(dependency, "scope") or "compile"
-        _child_text(dependency, "version")
-        if not dep_artifact_id or dep_scope in IGNORED_MAVEN_SCOPES:
-            continue
-        detail = f"dependency:{dep_group_id}:{dep_artifact_id}"
-        line = _find_line_number(lines, f"<artifactId>{dep_artifact_id}</artifactId>")
-        dependency_ref = _manifest_ref(path, detail, line)
-        dependencies.append(
-            ArtifactDependency(
-                target_name=dep_artifact_id,
-                target_key=_maven_key(dep_group_id, dep_artifact_id),
-                ecosystem="maven",
-                scope=dep_scope,
-                is_internal=False,
-                has_internal_signal=_looks_internal_maven_dependency(dep_group_id, dep_artifact_id),
-                evidence=dependency_ref,
-            )
-        )
-
-    return RepoManifest(
-        repo_name=repo_root.name,
-        repo_path=repo_root,
-        ecosystem="maven",
-        artifact_name=artifact_id,
-        artifact_key=artifact_key,
-        evidence=_manifest_ref(path, f"artifact:{artifact_id}", artifact_line),
-        dependencies=tuple(dependencies),
-    )
-
-
-def _parse_package_manifest(path: Path, repo_root: Path) -> RepoManifest | None:
-    try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError:
-        return None
-
-    name = payload.get("name")
-    if not isinstance(name, str) or not name.strip():
-        return None
-
-    lines = _text_lines(path)
-    name_line = _find_line_number(lines, f'"name": "{name}"')
-    dependencies: list[ArtifactDependency] = []
-    for section in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
-        raw = payload.get(section)
-        if not isinstance(raw, dict):
-            continue
-        for dep_name in sorted(raw):
-            line = _find_line_number(lines, f'"{dep_name}"')
-            dependencies.append(
-                ArtifactDependency(
-                    target_name=dep_name,
-                    target_key=_npm_key(dep_name),
-                    ecosystem="npm",
-                    scope=section,
-                    is_internal=False,
-                    has_internal_signal=False,
-                    evidence=_manifest_ref(path, f"dependency:{dep_name}", line),
-                )
-            )
-
-    return RepoManifest(
-        repo_name=repo_root.name,
-        repo_path=repo_root,
-        ecosystem="npm",
-        artifact_name=name,
-        artifact_key=_npm_key(name),
-        evidence=_manifest_ref(path, f"package:{name}", name_line),
-        dependencies=tuple(dependencies),
-    )
-
-
-def _load_repo_manifest(repo_root: Path) -> RepoManifest | None:
-    pom_path = repo_root / POM_NAME
-    if pom_path.exists():
-        manifest = _parse_maven_manifest(pom_path, repo_root)
-        if manifest is not None:
-            return manifest
-
-    for filename in PACKAGE_MANIFEST_NAMES:
-        package_path = repo_root / filename
-        if package_path.exists():
-            manifest = _parse_package_manifest(package_path, repo_root)
-            if manifest is not None:
-                return manifest
-    return None
-
-
-def _collect_manifests(project_root: Path, repo_paths: list[Path]) -> tuple[list[RepoManifest], list[IgnoredInput]]:
-    manifests: list[RepoManifest] = []
-    repo_roots, ignored = _discover_repo_roots(project_root, repo_paths)
-    for repo_root in repo_roots:
-        manifest = _load_repo_manifest(repo_root)
-        if manifest is not None:
-            manifests.append(manifest)
-    manifests.sort(key=lambda item: (item.repo_name, item.artifact_key))
-    return manifests, ignored
-
-
-def _collect_external_owner_inventory(project_root: Path) -> list[RepoManifest]:
-    candidate = project_root.resolve().parent / "LIB-project"
-    if not candidate.exists() or not candidate.is_dir():
-        return []
-    manifests, _ignored = _collect_manifests(candidate, [])
-    return manifests
-
-
-def _mark_internal_dependencies(
-    manifests: list[RepoManifest], owner_inventory: list[RepoManifest]
-) -> tuple[list[RepoManifest], dict[str, str], set[str]]:
-    owner_manifests = [*manifests, *owner_inventory]
-    artifact_owner_by_key = {manifest.artifact_key: manifest.repo_name for manifest in owner_manifests}
-    artifact_owner_by_name = {manifest.artifact_name: manifest.repo_name for manifest in owner_manifests}
-    in_scope_repo_names = {manifest.repo_name for manifest in manifests}
-    rewritten: list[RepoManifest] = []
-    for manifest in manifests:
-        dependencies: list[ArtifactDependency] = []
-        for dependency in manifest.dependencies:
-            is_internal = (
-                dependency.target_key in artifact_owner_by_key or dependency.target_name in artifact_owner_by_name
-            )
-            dependencies.append(
-                ArtifactDependency(
-                    target_name=dependency.target_name,
-                    target_key=dependency.target_key,
-                    ecosystem=dependency.ecosystem,
-                    scope=dependency.scope,
-                    is_internal=is_internal,
-                    has_internal_signal=dependency.has_internal_signal,
-                    evidence=dependency.evidence,
-                )
-            )
-        rewritten.append(
-            RepoManifest(
-                repo_name=manifest.repo_name,
-                repo_path=manifest.repo_path,
-                ecosystem=manifest.ecosystem,
-                artifact_name=manifest.artifact_name,
-                artifact_key=manifest.artifact_key,
-                evidence=manifest.evidence,
-                dependencies=tuple(dependencies),
-            )
-        )
-    return rewritten, artifact_owner_by_key, in_scope_repo_names
-
-
-def _build_graph_edges(
-    manifests: list[RepoManifest], artifact_owner_by_key: dict[str, str], in_scope_repo_names: set[str]
-) -> tuple[list[GraphEdge], list[GraphEdge]]:
-    artifact_edges: list[GraphEdge] = []
-    repo_edges_by_pair: dict[tuple[str, str], GraphEdge] = {}
-
-    for manifest in manifests:
-        for dependency in manifest.dependencies:
-            classification = "internal" if dependency.is_internal else "external"
-            artifact_edge = GraphEdge(
-                source=manifest.artifact_key,
-                target=dependency.target_key,
-                scope="artifact",
-                ecosystem=dependency.ecosystem,
-                classification=classification,
-                evidence_refs=(dependency.evidence,),
-            )
-            artifact_edges.append(artifact_edge)
-            if not dependency.is_internal:
-                continue
-
-            target_repo = artifact_owner_by_key.get(dependency.target_key)
-            if target_repo is None or target_repo not in in_scope_repo_names:
-                continue
-            pair = (manifest.repo_name, target_repo)
-            existing = repo_edges_by_pair.get(pair)
-            if existing is None:
-                repo_edges_by_pair[pair] = GraphEdge(
-                    source=manifest.repo_name,
-                    target=target_repo,
-                    scope="repository",
-                    ecosystem=dependency.ecosystem,
-                    classification="internal",
-                    evidence_refs=(dependency.evidence,),
-                )
-            else:
-                repo_edges_by_pair[pair] = GraphEdge(
-                    source=existing.source,
-                    target=existing.target,
-                    scope=existing.scope,
-                    ecosystem=existing.ecosystem,
-                    classification=existing.classification,
-                    evidence_refs=tuple(
-                        sorted(
-                            existing.evidence_refs + (dependency.evidence,),
-                            key=lambda item: (item.path, item.line or 0, item.detail),
-                        )
-                    ),
-                )
-
-    artifact_edges.sort(key=lambda edge: (edge.source, edge.target, edge.scope))
-    repo_edges = sorted(repo_edges_by_pair.values(), key=lambda edge: (edge.source, edge.target, edge.scope))
-    return repo_edges, artifact_edges
-
-
-def _adjacency(edges: list[GraphEdge]) -> dict[str, list[str]]:
-    graph: dict[str, list[str]] = {}
-    for edge in edges:
-        graph.setdefault(edge.source, []).append(edge.target)
-        graph.setdefault(edge.target, [])
-    for node in graph:
-        graph[node] = sorted(set(graph[node]))
-    return graph
-
-
-def _canonical_cycle(path: list[str]) -> tuple[str, ...]:
-    ring = path[:-1]
-    rotations = [tuple(ring[index:] + ring[:index]) for index in range(len(ring))]
-    reversed_ring = list(reversed(ring))
-    rotations.extend(tuple(reversed_ring[index:] + reversed_ring[:index]) for index in range(len(reversed_ring)))
-    best = min(rotations)
-    return best + (best[0],)
-
-
-def _find_cycles(edges: list[GraphEdge]) -> list[list[str]]:
-    graph = _adjacency(edges)
-    seen: set[tuple[str, ...]] = set()
-    cycles: list[list[str]] = []
-
-    def dfs(start: str, current: str, stack: list[str], visited: set[str]) -> None:
-        for neighbor in graph.get(current, []):
-            if neighbor == start and len(stack) >= 2:
-                cycle = stack + [start]
-                canonical = _canonical_cycle(cycle)
-                if canonical not in seen:
-                    seen.add(canonical)
-                    cycles.append(list(canonical))
-                continue
-            if neighbor in visited:
-                continue
-            dfs(start, neighbor, stack + [neighbor], visited | {neighbor})
-
-    for node in sorted(graph):
-        dfs(node, node, [node], {node})
-    cycles.sort(key=lambda cycle: (len(cycle), cycle))
-    return cycles
-
-
-def _edge_lookup(edges: list[GraphEdge]) -> dict[tuple[str, str], GraphEdge]:
-    return {(edge.source, edge.target): edge for edge in edges}
-
-
-def _serialize_evidence(ref: EvidenceRef) -> dict[str, Any]:
-    return {
-        "source_type": ref.source_type,
-        "path": ref.path,
-        "line": ref.line,
-        "detail": ref.detail,
-    }
-
-
-def _serialize_edge(edge: GraphEdge) -> dict[str, Any]:
-    return {
-        "source": edge.source,
-        "target": edge.target,
-        "scope": edge.scope,
-        "ecosystem": edge.ecosystem,
-        "classification": edge.classification,
-        "evidence_refs": [_serialize_evidence(ref) for ref in edge.evidence_refs],
-    }
-
-
-def _serialize_node(repo_name: str, manifests: list[RepoManifest]) -> dict[str, Any]:
-    manifest = next(item for item in manifests if item.repo_name == repo_name)
-    return {
-        "id": repo_name,
-        "scope": "repository",
-        "repo_name": manifest.repo_name,
-        "repo_path": str(manifest.repo_path.resolve()),
-        "artifact_name": manifest.artifact_name,
-        "artifact_key": manifest.artifact_key,
-        "ecosystem": manifest.ecosystem,
-        "evidence_ref": _serialize_evidence(manifest.evidence),
-    }
-
-
-def _serialize_artifact_node(manifest: RepoManifest) -> dict[str, Any]:
-    return {
-        "id": manifest.artifact_key,
-        "scope": "artifact",
-        "repo_name": manifest.repo_name,
-        "repo_path": str(manifest.repo_path.resolve()),
-        "artifact_name": manifest.artifact_name,
-        "artifact_key": manifest.artifact_key,
-        "ecosystem": manifest.ecosystem,
-        "evidence_ref": _serialize_evidence(manifest.evidence),
-    }
-
-
-def _cycle_payload(
-    *,
-    cycle: list[str],
-    scope: str,
-    edge_by_pair: dict[tuple[str, str], GraphEdge],
-) -> dict[str, Any]:
-    edge_payloads: list[dict[str, Any]] = []
-    for source, target in zip(cycle, cycle[1:], strict=False):
-        edge = edge_by_pair[(source, target)]
-        edge_payloads.append(_serialize_edge(edge))
-    return {
-        "scope": scope,
-        "classification": "confirmed_cycle",
-        "confidence": "high",
-        "cycle_path": cycle,
-        "edge_count": len(cycle) - 1,
-        "edges": edge_payloads,
-        "assumptions": [],
-        "remediation_hints": [
-            "Extract shared contracts into a dependency-neutral package.",
-            "Invert dependency direction for one edge in the loop.",
-        ],
-    }
-
-
-def _analysis_state(
-    repo_cycles: list[list[str]], artifact_cycles: list[list[str]], manifests: list[RepoManifest]
-) -> str:
-    if repo_cycles or artifact_cycles:
-        return "cycles_detected"
-    if manifests:
-        return "complete"
-    return "no_manifests_found"
-
-
-def _classification(
-    repo_cycles: list[list[str]],
-    artifact_cycles: list[list[str]],
-    manifests: list[RepoManifest],
-    evidence_gap_count: int,
-) -> str:
-    if repo_cycles or artifact_cycles:
-        return "confirmed_cycle"
-    if evidence_gap_count > 0:
-        return "evidence_gap"
-    if manifests:
-        return "no_cycle_detected"
-    return "evidence_gap"
-
-
-def _confidence(manifests: list[RepoManifest]) -> str:
-    return "high" if manifests else "low"
-
-
-def _apply_preset(project_root: Path, preset: str | None, repo_paths: list[Path]) -> tuple[list[Path], dict[str, Any]]:
-    if repo_paths:
-        return repo_paths, {"preset_applied": False, "preset_repo_count": len(repo_paths)}
-    if preset is None:
-        return repo_paths, {"preset_applied": False, "preset_repo_count": 0}
-
-    preset_key = preset.upper()
-    repo_names = PRESET_REPO_NAMES.get(preset_key)
-    if repo_names is None:
-        raise typer.BadParameter(
-            f"Unsupported preset '{preset}'. Expected one of: {', '.join(sorted(PRESET_REPO_NAMES))}"
-        )
-
-    selected = [project_root / repo_name for repo_name in sorted(repo_names)]
-    return selected, {
-        "preset_applied": True,
-        "preset_name": preset_key,
-        "preset_repo_count": len(selected),
-    }
-
-
-def _determine_exit_code(payload: dict[str, Any]) -> ExitCode:
-    if payload.get("summary", {}).get("evidence_gaps", 0) > 0:
-        return ExitCode.PARTIAL_ANALYSIS
-    if payload.get("summary", {}).get("cycles_confirmed", 0) > 0:
-        return ExitCode.CYCLE_FOUND
-    return ExitCode.NO_CYCLE
-
-
-def _collect_unresolved_internal_dependencies(manifests: list[RepoManifest]) -> list[dict[str, Any]]:
-    unresolved: dict[tuple[str, str, str], dict[str, Any]] = {}
-    for manifest in manifests:
-        for dependency in manifest.dependencies:
-            if dependency.is_internal or not dependency.has_internal_signal:
-                continue
-            key = (dependency.ecosystem, dependency.target_name, dependency.target_key)
-            item = unresolved.setdefault(
-                key,
-                {
-                    "ecosystem": dependency.ecosystem,
-                    "target_name": dependency.target_name,
-                    "target_key": dependency.target_key,
-                    "referenced_by_repos": set(),
-                    "evidence_refs": [],
-                },
-            )
-            item["referenced_by_repos"].add(manifest.repo_name)
-            item["evidence_refs"].append(_serialize_evidence(dependency.evidence))
-    results: list[dict[str, Any]] = []
-    for item in sorted(unresolved.values(), key=lambda row: (row["ecosystem"], row["target_name"])):
-        results.append(
-            {
-                "reason": "Internal-looking dependency has no owning repo inside the scanned root.",
-                "gap_type": "unresolved_internal_ownership",
-                "ecosystem": item["ecosystem"],
-                "target_name": item["target_name"],
-                "target_key": item["target_key"],
-                "referenced_by_repos": sorted(item["referenced_by_repos"]),
-                "evidence_refs": item["evidence_refs"],
-            }
-        )
-    return results
-
-
-def analyze_project(project_root: Path, repo_paths: list[Path], preset: str | None = None) -> dict[str, Any]:
-    effective_repo_paths, preset_info = _apply_preset(project_root, preset, repo_paths)
-    manifests, ignored_inputs = _collect_manifests(project_root, effective_repo_paths)
-    owner_inventory = _collect_external_owner_inventory(project_root)
-    manifests, artifact_owner_by_key, in_scope_repo_names = _mark_internal_dependencies(manifests, owner_inventory)
-    repo_edges, artifact_edges = _build_graph_edges(manifests, artifact_owner_by_key, in_scope_repo_names)
-    repo_cycles = _find_cycles(repo_edges)
-    artifact_cycles = _find_cycles([edge for edge in artifact_edges if edge.classification == "internal"])
-    repo_lookup = _edge_lookup(repo_edges)
-    artifact_lookup = _edge_lookup([edge for edge in artifact_edges if edge.classification == "internal"])
-
-    repository_nodes = [_serialize_node(manifest.repo_name, manifests) for manifest in manifests]
-    artifact_nodes = [_serialize_artifact_node(manifest) for manifest in manifests]
-
-    repo_cycle_payloads = [
-        _cycle_payload(cycle=cycle, scope="repository", edge_by_pair=repo_lookup) for cycle in repo_cycles
-    ]
-    artifact_cycle_payloads = [
-        _cycle_payload(cycle=cycle, scope="artifact", edge_by_pair=artifact_lookup) for cycle in artifact_cycles
-    ]
-
-    evidence_gaps: list[dict[str, Any]] = []
-    if not manifests:
-        evidence_gaps.append(
-            {
-                "reason": "No supported manifests found under the project root.",
-                "expected_files": [POM_NAME, *PACKAGE_MANIFEST_NAMES],
-            }
-        )
-    if ignored_inputs:
-        evidence_gaps.append(
-            {
-                "reason": "Some candidate inputs were ignored by scope controls.",
-                "ignored_inputs": [{"path": item.path, "reason": item.reason} for item in ignored_inputs],
-            }
-        )
-
-    unresolved_internal_dependencies = _collect_unresolved_internal_dependencies(manifests)
-    evidence_gaps.extend(unresolved_internal_dependencies)
-
-    shared_internal_dependencies = sorted(
-        {
-            dependency.target_name
-            for manifest in manifests
-            for dependency in manifest.dependencies
-            if dependency.is_internal
-        }
-    )
-
-    payload = {
-        "analysis_state": _analysis_state(repo_cycles, artifact_cycles, manifests),
-        "classification": _classification(repo_cycles, artifact_cycles, manifests, len(evidence_gaps)),
-        "confidence": _confidence(manifests),
-        "project_root": str(project_root.resolve()),
-        "manifests_scanned": len(manifests),
-        "topology_filenames": {
-            "dependency_graph": "project-dependency-graph.json",
-            "cycle_report": "project-cycle-report.json",
-        },
-        "repository_nodes": repository_nodes,
-        "artifact_nodes": artifact_nodes,
-        "repository_edges": [_serialize_edge(edge) for edge in repo_edges],
-        "artifact_edges": [_serialize_edge(edge) for edge in artifact_edges],
-        "cycles": repo_cycle_payloads + artifact_cycle_payloads,
-        "evidence_gaps": evidence_gaps,
-        "unresolved_internal_dependencies": unresolved_internal_dependencies,
-        "shared_internal_dependencies": shared_internal_dependencies,
-        "ignored_inputs": [{"path": item.path, "reason": item.reason} for item in ignored_inputs],
-        "summary": {
-            "repos_in_scope": len(repository_nodes),
-            "artifacts_in_scope": len(artifact_nodes),
-            "internal_repo_edges": len(repo_edges),
-            "internal_artifact_edges": len([edge for edge in artifact_edges if edge.classification == "internal"]),
-            "external_artifact_edges": len([edge for edge in artifact_edges if edge.classification == "external"]),
-            "cycles_confirmed": len(repo_cycle_payloads) + len(artifact_cycle_payloads),
-            "cycles_probable": 0,
-            "evidence_gaps": len(evidence_gaps),
-        },
-    }
-    payload.update(preset_info)
-    payload["exit_code"] = int(_determine_exit_code(payload))
-    return payload
-
-
-def _render_markdown(payload: dict[str, Any]) -> str:
-    lines = [
-        "# Circular Dependency Report",
-        "",
-        f"- Analysis state: {payload.get('analysis_state', 'unknown')}",
-        f"- Classification: {payload.get('classification', 'unknown')}",
-        f"- Confidence: {payload.get('confidence', 'unknown')}",
-        f"- Project root: {payload.get('project_root', 'unknown')}",
-        f"- Exit code: {payload.get('exit_code', 1)}",
-        "",
-        "## Summary",
-        "",
-    ]
-    summary = payload.get("summary", {})
-    for key in (
-        "repos_in_scope",
-        "artifacts_in_scope",
-        "internal_repo_edges",
-        "internal_artifact_edges",
-        "external_artifact_edges",
-        "cycles_confirmed",
-        "evidence_gaps",
-    ):
-        lines.append(f"- {key}: {summary.get(key, 0)}")
-
-    cycles = payload.get("cycles", [])
-    if cycles:
-        lines.extend(["", "## Cycles", ""])
-        for index, cycle in enumerate(cycles, start=1):
-            lines.append(
-                f"### Cycle {index}: {cycle.get('scope', 'unknown')} :: {' -> '.join(cycle.get('cycle_path', []))}"
-            )
-            lines.append(f"- Classification: {cycle.get('classification', 'unknown')}")
-            lines.append(f"- Confidence: {cycle.get('confidence', 'unknown')}")
-            for edge in cycle.get("edges", []):
-                evidence = edge.get("evidence_refs", [])
-                refs = ", ".join(
-                    f"{ref.get('path')}:{ref.get('line') or '?'} ({ref.get('detail')})" for ref in evidence
-                )
-                lines.append(f"- Edge: {edge.get('source')} -> {edge.get('target')} [{refs}]")
-    else:
-        lines.extend(["", "## Cycles", "", "No confirmed circular dependencies detected in the analyzed manifests."])
-
-    evidence_gaps = payload.get("evidence_gaps", [])
-    if evidence_gaps:
-        lines.extend(["", "## Evidence Gaps", ""])
-        for gap in evidence_gaps:
-            detail = gap.get("target_name")
-            if detail:
-                lines.append(f"- {gap.get('reason', 'Unknown evidence gap')} [{detail}]")
-            else:
-                lines.append(f"- {gap.get('reason', 'Unknown evidence gap')}")
-
-    ignored_inputs = payload.get("ignored_inputs", [])
-    if ignored_inputs:
-        lines.extend(["", "## Ignored Inputs", ""])
-        for item in ignored_inputs:
-            lines.append(f"- {item.get('path')} [{item.get('reason')}]")
-
-    return "\n".join(lines) + "\n"
-
-
-@app.command()
-def analyze(
-    project_root: Path = typer.Option(..., "--project-root", exists=True, file_okay=False, dir_okay=True),
-    scope: str = typer.Option(
-        "full-project",
-        "--scope",
-        help="Analysis scope: repo, artifact, module, or full-project.",
-    ),
-    repo_path: list[Path] = typer.Option(
-        None,
-        "--repo-path",
-        help="Explicit repository path(s) within the project root. Repeatable.",
-    ),
-    preset: str | None = typer.Option(
-        None,
-        "--preset",
-        help="Optional project preset such as PAR or INSURANCE.",
-    ),
-) -> None:
-    """Analyze manifests and emit a circular-dependency report."""
-    if scope not in ALLOWED_SCOPES:
-        raise typer.BadParameter(f"Unsupported scope '{scope}'. Expected one of: {', '.join(sorted(ALLOWED_SCOPES))}")
-
-    payload = analyze_project(project_root=project_root, repo_paths=repo_path or [], preset=preset)
-    payload["requested_scope"] = scope
-    payload["preset"] = preset
-    payload["repo_paths"] = [str(path.resolve()) for path in repo_path or []]
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        raise typer.Exit(code=int(payload.get("exit_code", ExitCode.ERROR)))
-
-    console.print(_render_markdown(payload), markup=False)
-    raise typer.Exit(code=int(payload.get("exit_code", ExitCode.ERROR)))
-
-
-@app.command()
-def report(
-    input: Path = typer.Option(..., "--input", exists=True, dir_okay=False, readable=True),
-    format: str = typer.Option("markdown", "--format", help="Output format: markdown or json-summary."),
-) -> None:
-    """Render a report from prior JSON output."""
-    payload = json.loads(input.read_text(encoding="utf-8"))
-    if format not in {"markdown", "json-summary"}:
-        raise typer.BadParameter("Unsupported format. Expected markdown or json-summary")
-
-    if _cli_state.get("json_only") or format == "json-summary":
-        summary_payload = {
-            "analysis_state": payload.get("analysis_state"),
-            "classification": payload.get("classification"),
-            "confidence": payload.get("confidence"),
-            "summary": payload.get("summary", {}),
-            "cycles": payload.get("cycles", []),
-            "evidence_gaps": payload.get("evidence_gaps", []),
-        }
-        _emit_json(summary_payload)
-        return
-
-    console.print(_render_markdown(payload), markup=False)
-
-
-def main() -> None:
-    """Script compatibility wrapper."""
-    app()
-
-
-if __name__ == "__main__":
-    main()