repomap-cli 1.0.0__py3-none-any.whl

repomap/__init__.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+import hashlib
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+CACHE_DIR = Path.home() / ".cache" / "repomap"
+
+
+def get_project_cache_dir(project_path: str) -> Path:
+    """获取项目的缓存目录（基于规范化后的项目路径哈希隔离）。"""
+    canonical_path = str(Path(project_path).expanduser().resolve())
+    path_hash = hashlib.md5(canonical_path.encode()).hexdigest()[:8]
+    project_name = Path(canonical_path).name
+    cache_dir = CACHE_DIR / f"{project_name}_{path_hash}"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def get_cache_paths(project_path: str) -> tuple[Path, Path, Path]:
+    """获取缓存文件路径: (symbols_cache, git_cache, last_snapshot)"""
+    cache_dir = get_project_cache_dir(project_path)
+    return (
+        cache_dir / "symbols.json",
+        cache_dir / "git.json",
+        cache_dir / "last_snapshot.json",
+    )
+
+
+def get_session_cache_path(project_path: str) -> Path:
+    """获取跨进程短期扫描缓存路径。"""
+    cache_dir = get_project_cache_dir(project_path)
+    return cache_dir / "session_scan.json"
+
+
+def get_incremental_cache_path(project_path: str) -> Path:
+    """获取增量扫描持久化缓存路径。"""
+    cache_dir = get_project_cache_dir(project_path)
+    return cache_dir / "incremental.json"
+
+
+@dataclass
+class FileCacheEntry:
+    """单文件增量缓存条目——对应一次全量扫描中一个文件的解析结果"""
+    mtime: float
+    symbols_json: list[dict] = field(default_factory=list)
+    imports: list[str] = field(default_factory=list)
+    import_bindings_json: list[dict] = field(default_factory=list)
+    exports_json: list[dict] = field(default_factory=list)
+    calls_json: list[dict] = field(default_factory=list)
+    routes_json: list[dict] = field(default_factory=list)
+
+
+@dataclass
+class IncrementalCache:
+    """持久化的增量扫描基线，用于后续增量扫描时识别变更文件并还原未变更文件"""
+    project_root_hash: str = ""
+    git_head: str = ""
+    files: dict[str, FileCacheEntry] = field(default_factory=dict)
+    scan_stats_json: dict = field(default_factory=dict)
+
+
+@dataclass
+class Symbol:
+    """代码符号（函数 / 类 / 接口等）"""
+
+    id: str
+    name: str
+    kind: str
+    file: str
+    line: int
+    end_line: int = 0
+    col: int = 0
+    visibility: str = "private"
+    docstring: str = ""
+    signature: str = ""
+    pagerank: float = 0.0
+
+
+@dataclass
+class Edge:
+    source: str
+    target: str
+    weight: float
+    kind: str
+
+
+@dataclass(frozen=True)
+class JSImportBinding:
+    local_name: str
+    imported_name: str
+    module: str
+    line: int
+    kind: str = "named"
+
+
+@dataclass(frozen=True)
+class JSExportBinding:
+    exported_name: str
+    source_name: str | None
+    module: str | None
+    line: int
+    kind: str = "local"
+
+
+@dataclass(frozen=True)
+class PathAliasRule:
+    alias_pattern: str
+    target_patterns: tuple[str, ...]
+
+
+@dataclass
+class ProjectImportConfig:
+    config_path: str | None = None
+    config_dir: str | None = None
+    base_url: str | None = None
+    alias_rules: list[PathAliasRule] = field(default_factory=list)
+
+
+@dataclass
+class ScanStats:
+    listed_source_files: int = 0
+    selected_source_files: int = 0
+    processed_files: int = 0
+    filtered_path_files: int = 0
+    filtered_large_files: int = 0
+    truncated_files: int = 0
+    failed_files: list[str] = field(default_factory=list)  # 记录失败的文件路径（前N个）
+    scan_duration_ms: int = 0  # 扫描耗时（毫秒）
+    timeout_triggered: bool = False  # 是否触发超时熔断
+    skipped_files: int = 0  # 因 mtime 未变跳过的文件数（增量扫描）
+
+
+@dataclass
+class HttpRoute:
+    """HTTP 路由定义（从 AST 中提取）"""
+    method: str       # GET, POST, PUT, DELETE, PATCH
+    path: str         # /api/users/:id
+    handler: str      # 处理函数名
+    file: str         # 文件路径
+    line: int         # 行号
+    framework: str    # fastapi, flask, express, axum
+
+
+@dataclass
+class RepoGraph:
+    symbols: dict[str, Symbol] = field(default_factory=dict)
+    outgoing: dict[str, list[Edge]] = field(default_factory=lambda: defaultdict(list))
+    incoming: dict[str, list[Edge]] = field(default_factory=lambda: defaultdict(list))
+    file_symbols: dict[str, list[str]] = field(default_factory=lambda: defaultdict(list))
+    file_imports: dict[str, list[str]] = field(default_factory=lambda: defaultdict(list))
+    file_calls: dict[str, list[tuple[str, int]]] = field(default_factory=lambda: defaultdict(list))
+    file_import_bindings: dict[str, list[JSImportBinding]] = field(default_factory=lambda: defaultdict(list))
+    file_exports: dict[str, list[JSExportBinding]] = field(default_factory=lambda: defaultdict(list))
+
+
+def call_reference_parts(call_ref: Any) -> tuple[str, int, str]:
+    if isinstance(call_ref, (list, tuple)):
+        if len(call_ref) >= 3:
+            return str(call_ref[0]), int(call_ref[1]), str(call_ref[2] or "direct")
+        if len(call_ref) >= 2:
+            return str(call_ref[0]), int(call_ref[1]), "direct"
+    name = getattr(call_ref, "name", "")
+    line = getattr(call_ref, "line", 0)
+    kind = getattr(call_ref, "kind", "direct")
+    return str(name), int(line), str(kind or "direct")
+
+
+def serialize_symbol(symbol: Symbol) -> dict[str, Any]:
+    return {
+        "id": symbol.id,
+        "name": symbol.name,
+        "kind": symbol.kind,
+        "file": symbol.file,
+        "line": symbol.line,
+        "end_line": symbol.end_line,
+        "col": symbol.col,
+        "visibility": symbol.visibility,
+        "signature": symbol.signature,
+        "docstring": symbol.docstring,
+        "pagerank": symbol.pagerank,
+    }
+
+
+def serialize_edge(edge: Edge) -> dict[str, Any]:
+    return {
+        "source": edge.source,
+        "target": edge.target,
+        "weight": edge.weight,
+        "kind": edge.kind,
+    }
+
+
+def edge_identity_from_edge(edge: Edge) -> tuple[str, str, str] | None:
+    if not edge.source or not edge.target:
+        return None
+    return (edge.source, edge.target, edge.kind)
+
+
+def edge_identity_from_row(row: dict[str, Any]) -> tuple[str, str, str] | None:
+    source = row.get("source", row.get("from_id"))
+    target = row.get("target", row.get("to_id"))
+    kind = row.get("kind", "call")
+    if not source or not target:
+        return None
+    return (source, target, kind)
+
+
+def compare_graph_snapshots(
+    current_symbols: list[Symbol],
+    current_edges: list[Edge],
+    previous_symbols: list[dict[str, Any]],
+    previous_edges: list[dict[str, Any]],
+    incoming_map: dict[str, list[Edge]] | None = None,
+) -> dict[str, Any]:
+    current_symbol_map = {symbol.id: symbol for symbol in current_symbols}
+    previous_symbol_map = {row["id"]: row for row in previous_symbols}
+
+    current_symbol_ids = set(current_symbol_map)
+    previous_symbol_ids = set(previous_symbol_map)
+
+    added_symbol_ids = sorted(current_symbol_ids - previous_symbol_ids)
+    removed_symbol_ids = sorted(previous_symbol_ids - current_symbol_ids)
+
+    modified_symbols = []
+    for symbol_id in sorted(current_symbol_ids & previous_symbol_ids):
+        current = current_symbol_map[symbol_id]
+        previous = previous_symbol_map[symbol_id]
+        sig_changed = current.signature != previous.get("signature", "")
+        loc_changed = (
+            current.line != previous.get("line")
+            or current.end_line != previous.get("end_line", current.end_line)
+            or current.file != previous.get("file")
+        )
+        if sig_changed or loc_changed:
+            entry = {
+                "id": symbol_id,
+                "name": current.name,
+                "file": current.file,
+                "visibility": current.visibility,
+                "kind": current.kind,
+                "line_change": f"{previous.get('line')} -> {current.line}",
+                "old_signature": previous.get("signature", ""),
+                "new_signature": current.signature,
+                "signature_changed": sig_changed,
+            }
+            # 附加调用者信息
+            if incoming_map:
+                callers = [e for e in incoming_map.get(symbol_id, []) if e.kind == "call"]
+                entry["affected_callers"] = [
+                    {"symbol_id": e.source, "kind": e.kind}
+                    for e in callers[:10]
+                ]
+                entry["affected_caller_count"] = len(callers)
+                # 风险评级：导出符号签名变更→HIGH，否则有调用者→MEDIUM
+                if sig_changed and entry.get("visibility") == "exported":
+                    entry["risk"] = "HIGH"
+                elif sig_changed and len(callers) >= 3:
+                    entry["risk"] = "MEDIUM"
+                else:
+                    entry["risk"] = "LOW"
+            modified_symbols.append(entry)
+
+    current_edge_set = {
+        edge_id
+        for edge in current_edges
+        for edge_id in [edge_identity_from_edge(edge)]
+        if edge_id is not None
+    }
+    previous_edge_set = {
+        edge_id
+        for row in previous_edges
+        for edge_id in [edge_identity_from_row(row)]
+        if edge_id is not None
+    }
+
+    edges_added = sorted(current_edge_set - previous_edge_set)
+    edges_removed = sorted(previous_edge_set - current_edge_set)
+
+    return {
+        "summary": {
+            "added": len(added_symbol_ids),
+            "removed": len(removed_symbol_ids),
+            "modified": len(modified_symbols),
+            "edges_added": len(edges_added),
+            "edges_removed": len(edges_removed),
+        },
+        "added_symbols": [
+            {
+                "id": symbol_id,
+                "name": current_symbol_map[symbol_id].name,
+                "file": current_symbol_map[symbol_id].file,
+                "line": current_symbol_map[symbol_id].line,
+            }
+            for symbol_id in added_symbol_ids
+        ],
+        "removed_symbols": [
+            {
+                "id": symbol_id,
+                "name": previous_symbol_map[symbol_id].get("name", symbol_id),
+                "file": previous_symbol_map[symbol_id].get("file", ""),
+                "line": previous_symbol_map[symbol_id].get("line", 0),
+            }
+            for symbol_id in removed_symbol_ids
+        ],
+        "modified_symbols": modified_symbols,
+        "call_chain_changes": {
+            "new_calls": [
+                {"from": source, "to": target, "kind": kind}
+                for source, target, kind in edges_added[:20]
+            ],
+            "removed_calls": [
+                {"from": source, "to": target, "kind": kind}
+                for source, target, kind in edges_removed[:20]
+            ],
+        },
+    }