source-kb 0.2.2__py3-none-any.whl

core/skeleton/cmd_lock.py

@@ -0,0 +1,87 @@
+"""Lock management command — acquire/release/status for both Agent and CLI modes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+
+def cmd_lock(args: argparse.Namespace) -> None:
+    """Unified lock management for both Agent and CLI modes."""
+    lock_dir = Path(args.dir)
+    lock_path = lock_dir / ".kb-lock"
+    lock_meta_path = lock_dir / ".kb-lock.json"
+
+    if args.action == "acquire":
+        lock_dir.mkdir(parents=True, exist_ok=True)
+
+        # Check if already locked
+        if lock_path.exists():
+            if _is_stale_lock(lock_meta_path):
+                lock_path.unlink(missing_ok=True)
+                lock_meta_path.unlink(missing_ok=True)
+                print(json.dumps({"status": "warning", "message": "Stale lock overridden"},
+                                 ensure_ascii=False), file=sys.stderr)
+            else:
+                meta = {}
+                if lock_meta_path.exists():
+                    try:
+                        meta = json.loads(lock_meta_path.read_text(encoding="utf-8"))
+                    except (json.JSONDecodeError, OSError):
+                        pass
+                print(json.dumps({"status": "error", "message": "Already locked",
+                                  **meta}, ensure_ascii=False), file=sys.stderr)
+                sys.exit(1)
+
+        # Acquire
+        lock_path.write_text(str(os.getpid()), encoding="utf-8")
+        meta = {
+            "pid": os.getpid(),
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            "operation": args.operation or "unknown",
+        }
+        lock_meta_path.write_text(json.dumps(meta, ensure_ascii=False), encoding="utf-8")
+        print(json.dumps({"status": "ok", "action": "acquired"}, ensure_ascii=False),
+              file=sys.stderr)
+
+    elif args.action == "release":
+        lock_path.unlink(missing_ok=True)
+        lock_meta_path.unlink(missing_ok=True)
+        print(json.dumps({"status": "ok", "action": "released"}, ensure_ascii=False),
+              file=sys.stderr)
+
+    elif args.action == "status":
+        if lock_path.exists():
+            meta = {}
+            if lock_meta_path.exists():
+                try:
+                    meta = json.loads(lock_meta_path.read_text(encoding="utf-8"))
+                except (json.JSONDecodeError, OSError):
+                    pass
+            stale = _is_stale_lock(lock_meta_path)
+            print(json.dumps({"status": "locked", "stale": stale, **meta},
+                             ensure_ascii=False), file=sys.stderr)
+        else:
+            print(json.dumps({"status": "unlocked"}, ensure_ascii=False), file=sys.stderr)
+
+
+def _is_stale_lock(lock_meta_path: Path) -> bool:
+    """Check if a lock is stale (>30 minutes old)."""
+    if not lock_meta_path.exists():
+        return True
+    try:
+        meta = json.loads(lock_meta_path.read_text(encoding="utf-8"))
+        ts = meta.get("timestamp", "")
+        if not ts:
+            return True
+        from datetime import datetime, timezone
+        lock_time = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        now = datetime.now(timezone.utc)
+        age_minutes = (now - lock_time).total_seconds() / 60
+        return age_minutes > 30
+    except (json.JSONDecodeError, OSError, ValueError):
+        return True

core/skeleton/cmd_merge_delta.py

@@ -0,0 +1,41 @@
+"""Merge delta command — merge skeleton delta into existing skeleton."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def cmd_merge_delta(args: argparse.Namespace) -> None:
+    """Merge skeleton delta into existing skeleton."""
+    from core.skeleton.merge_delta import merge_delta
+
+    delta_path = Path(args.delta)
+    target_path = Path(args.target)
+
+    if not delta_path.exists():
+        print(json.dumps({"status": "error", "message": f"Delta not found: {delta_path}"},
+                         ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        stats = merge_delta(
+            delta_path=delta_path,
+            module_dir=target_path,
+            dry_run=args.dry_run,
+            cleanup=not args.no_cleanup,
+        )
+    except (json.JSONDecodeError, ValueError) as e:
+        print(json.dumps({"status": "error", "message": f"Malformed delta: {e}"},
+                         ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+    result = {"status": "ok", "replaced": stats.replaced, "added": stats.added}
+    if stats.unmatched:
+        result["unmatched"] = stats.unmatched
+    if args.dry_run:
+        result["dry_run"] = True
+
+    print(json.dumps(result, ensure_ascii=False), file=sys.stderr)

core/skeleton/community.py

@@ -0,0 +1,233 @@
+"""Community detection — Louvain-based file grouping for intelligent splitting.
+
+Uses dependency graph to identify highly cohesive file groups via community
+detection. Falls back to connected components when networkx is unavailable.
+
+Usage:
+    from core.skeleton.community import detect_communities, validate_communities, split_by_community
+
+    graph = build_dependency_graph(skeleton_entries)
+    communities = detect_communities(graph, resolution=1.0)
+    valid = validate_communities(communities, max_files_per_shard=80)
+    plan = split_by_community(entries, graph, resolution=1.0)
+"""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from core.skeleton.dependency_graph import DependencyGraph
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def detect_communities(
+    graph: DependencyGraph,
+    resolution: float = 1.0,
+) -> list[list[str]]:
+    """Detect communities in the dependency graph.
+
+    Uses networkx Louvain algorithm if available, otherwise falls back
+    to connected components with weight threshold.
+
+    Args:
+        graph: DependencyGraph instance
+        resolution: Louvain resolution parameter (higher = smaller communities)
+
+    Returns:
+        List of file path lists, each sub-list is a community.
+    """
+    if not graph.adjacency:
+        return []
+
+    try:
+        return _detect_communities_networkx(graph, resolution)
+    except ImportError:
+        return _detect_communities_fallback(graph)
+
+
+def validate_communities(
+    communities: list[list[str]],
+    max_files_per_shard: int = 80,
+) -> bool:
+    """Validate that all communities are within size constraints.
+
+    Args:
+        communities: Output from detect_communities
+        max_files_per_shard: Maximum files allowed per community
+
+    Returns:
+        True if all communities are within limits.
+    """
+    if not communities:
+        return True
+    return all(len(c) <= max_files_per_shard for c in communities)
+
+
+def split_by_community(
+    entries: list[dict[str, Any]],
+    graph: DependencyGraph,
+    resolution: float = 1.0,
+    max_files_per_shard: int = 80,
+    max_lines_per_shard: int = 8000,
+) -> list[list[dict[str, Any]]]:
+    """Split skeleton entries into groups based on community detection.
+
+    Args:
+        entries: File info dicts with at least {name, path, lines}
+        graph: DependencyGraph built from skeleton
+        resolution: Louvain resolution parameter
+        max_files_per_shard: Max files per group
+        max_lines_per_shard: Max lines per group
+
+    Returns:
+        List of entry groups. Each group is a list of file dicts.
+    """
+    communities = detect_communities(graph, resolution)
+    if not communities or len(communities) <= 1:
+        return [entries] if entries else []
+
+    # Build lookup indices
+    path_to_entry = {e.get("path", ""): e for e in entries}
+    name_to_entry = {e.get("name", ""): e for e in entries}
+
+    groups: list[list[dict]] = []
+    assigned: set[str] = set()
+
+    for community_files in communities:
+        group: list[dict] = []
+        for filepath in community_files:
+            entry = path_to_entry.get(filepath)
+            if not entry:
+                fname = Path(filepath).name
+                entry = name_to_entry.get(fname)
+            if entry and entry.get("name", "") not in assigned:
+                group.append(entry)
+                assigned.add(entry.get("name", ""))
+        if group:
+            # Split oversized communities
+            group_lines = sum(e.get("lines", 0) for e in group)
+            if len(group) > max_files_per_shard or group_lines > max_lines_per_shard:
+                sub_groups = _split_oversized(group, max_lines_per_shard, max_files_per_shard)
+                groups.extend(sub_groups)
+            else:
+                groups.append(group)
+
+    # Handle unassigned entries
+    unassigned = [e for e in entries if e.get("name", "") not in assigned]
+    if unassigned:
+        unassigned_lines = sum(e.get("lines", 0) for e in unassigned)
+        if unassigned_lines < 200 and len(unassigned) < 5 and groups:
+            # Merge into smallest group
+            smallest = min(groups, key=lambda g: sum(e.get("lines", 0) for e in g))
+            smallest.extend(unassigned)
+        else:
+            groups.append(unassigned)
+
+    return groups
+
+
+# ---------------------------------------------------------------------------
+# Internal: networkx-based detection
+# ---------------------------------------------------------------------------
+
+
+def _detect_communities_networkx(
+    graph: DependencyGraph,
+    resolution: float = 1.0,
+) -> list[list[str]]:
+    """Use networkx Louvain community detection."""
+    import networkx as nx
+
+    G = nx.Graph()
+    all_nodes = graph.nodes
+    G.add_nodes_from(all_nodes)
+
+    # Add weighted edges (undirected, take max weight for bidirectional)
+    for source, targets in graph.adjacency.items():
+        for target, weight in targets.items():
+            if G.has_edge(source, target):
+                existing = G[source][target].get("weight", 0)
+                G[source][target]["weight"] = max(existing, weight)
+            else:
+                G.add_edge(source, target, weight=weight)
+
+    if G.number_of_edges() == 0:
+        return [[n] for n in G.nodes()]
+
+    communities = nx.community.louvain_communities(
+        G, weight="weight", resolution=resolution, seed=42
+    )
+    return [sorted(list(c)) for c in communities]
+
+
+# ---------------------------------------------------------------------------
+# Internal: Fallback detection (no networkx)
+# ---------------------------------------------------------------------------
+
+
+def _detect_communities_fallback(
+    graph: DependencyGraph,
+) -> list[list[str]]:
+    """Fallback: connected components with weight threshold >= 2."""
+    adj: dict[str, set[str]] = defaultdict(set)
+    all_nodes = graph.nodes
+
+    for source, targets in graph.adjacency.items():
+        for target, weight in targets.items():
+            if weight >= 2:
+                adj[source].add(target)
+                adj[target].add(source)
+
+    visited: set[str] = set()
+    communities: list[list[str]] = []
+
+    for node in sorted(all_nodes):
+        if node in visited:
+            continue
+        component: list[str] = []
+        queue = [node]
+        while queue:
+            current = queue.pop(0)
+            if current in visited:
+                continue
+            visited.add(current)
+            component.append(current)
+            for neighbor in adj.get(current, set()):
+                if neighbor not in visited:
+                    queue.append(neighbor)
+        communities.append(sorted(component))
+
+    return communities
+
+
+# ---------------------------------------------------------------------------
+# Internal: Helpers
+# ---------------------------------------------------------------------------
+
+
+def _split_oversized(
+    files: list[dict], max_lines: int, max_files: int
+) -> list[list[dict]]:
+    """Split an oversized community using LPT greedy balancing."""
+    total_lines = sum(f.get("lines", 0) for f in files)
+    n = max(
+        math.ceil(len(files) / max_files),
+        math.ceil(total_lines / max_lines),
+        2,
+    )
+    buckets: list[list[dict]] = [[] for _ in range(n)]
+    bucket_lines = [0] * n
+
+    for f in sorted(files, key=lambda x: -x.get("lines", 0)):
+        lightest = min(range(n), key=lambda i: bucket_lines[i])
+        buckets[lightest].append(f)
+        bucket_lines[lightest] += f.get("lines", 0)
+
+    return [b for b in buckets if b]

core/skeleton/dependency_graph.py

@@ -0,0 +1,306 @@
+"""Dependency graph construction — file-level dependency analysis from skeleton data.
+
+Builds a weighted directed graph from skeleton entries. Supports topological sort
+and cycle detection. Dependency weights: inheritance=4, injection=3, import=2, call=1.
+
+Usage:
+    from core.skeleton.dependency_graph import (
+        DependencyEdge, DependencyGraph, build_dependency_graph, topo_sort, detect_cycles
+    )
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DependencyEdge:
+    """A single dependency edge between two files."""
+
+    source: str
+    target: str
+    weight: int = 1
+    kind: str = "import"  # import | inheritance | injection | call
+
+
+@dataclass
+class DependencyGraph:
+    """File-level dependency graph with adjacency dict and edge list."""
+
+    adjacency: dict[str, dict[str, int]] = field(default_factory=dict)
+    edges: list[DependencyEdge] = field(default_factory=list)
+
+    @property
+    def nodes(self) -> set[str]:
+        """All nodes in the graph."""
+        nodes = set(self.adjacency.keys())
+        for targets in self.adjacency.values():
+            nodes.update(targets.keys())
+        return nodes
+
+    def add_edge(self, source: str, target: str, weight: int, kind: str) -> None:
+        """Add or accumulate an edge."""
+        if source not in self.adjacency:
+            self.adjacency[source] = {}
+        self.adjacency.setdefault(source, {})[target] = (
+            self.adjacency.get(source, {}).get(target, 0) + weight
+        )
+        self.edges.append(DependencyEdge(source=source, target=target, weight=weight, kind=kind))
+
+
+# Edge weight constants
+WEIGHT_INHERITANCE = 4
+WEIGHT_INJECTION = 3
+WEIGHT_IMPORT = 2
+WEIGHT_CALL = 1
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def build_dependency_graph(
+    skeleton_entries: list[dict[str, Any]],
+    project_package_prefix: str | None = None,
+) -> DependencyGraph:
+    """Build a file-level dependency graph from skeleton entries."""
+    class_to_file = _build_class_to_file_index(skeleton_entries)
+    field_type_to_file = _build_field_type_index(skeleton_entries)
+    if project_package_prefix is None:
+        project_package_prefix = _infer_package_prefix(skeleton_entries)
+
+    graph = DependencyGraph()
+    for entry in skeleton_entries:
+        source_file = entry.get("file", "")
+        if not source_file:
+            continue
+        _add_import_edges(entry, source_file, class_to_file, project_package_prefix, graph)
+        _add_inheritance_edges(entry, source_file, class_to_file, graph)
+        _add_injection_edges(entry, source_file, class_to_file, graph)
+        _add_call_edges(entry, source_file, class_to_file, field_type_to_file, graph)
+    return graph
+
+
+def topo_sort(graph: DependencyGraph) -> list[str]:
+    """Topological sort (Kahn's algorithm). Dependencies come first."""
+    nodes = graph.nodes
+    in_degree: dict[str, int] = {n: 0 for n in nodes}
+    for source, targets in graph.adjacency.items():
+        for target in targets:
+            if target in in_degree:
+                in_degree[target] += 1
+
+    queue = deque(sorted(n for n in nodes if in_degree[n] == 0))
+    result: list[str] = []
+    while queue:
+        node = queue.popleft()
+        result.append(node)
+        for target in graph.adjacency.get(node, {}):
+            if target in in_degree:
+                in_degree[target] -= 1
+                if in_degree[target] == 0:
+                    queue.append(target)
+    # Append remaining (cycle members)
+    if len(result) < len(nodes):
+        result.extend(sorted(n for n in nodes if n not in set(result)))
+    return result
+
+
+def detect_cycles(graph: DependencyGraph) -> list[list[str]]:
+    """Detect cycles in the dependency graph using DFS."""
+    nodes = graph.nodes
+    visited: set[str] = set()
+    rec_stack: set[str] = set()
+    cycles: list[list[str]] = []
+    path: list[str] = []
+
+    def dfs(node: str) -> None:
+        visited.add(node)
+        rec_stack.add(node)
+        path.append(node)
+        for neighbor in graph.adjacency.get(node, {}):
+            if neighbor not in visited:
+                dfs(neighbor)
+            elif neighbor in rec_stack:
+                cycle_start = path.index(neighbor)
+                cycles.append(path[cycle_start:] + [neighbor])
+        path.pop()
+        rec_stack.discard(node)
+
+    for node in sorted(nodes):
+        if node not in visited:
+            dfs(node)
+    return cycles
+
+
+# ---------------------------------------------------------------------------
+# Internal: Index builders
+# ---------------------------------------------------------------------------
+
+
+def _build_class_to_file_index(entries: list[dict]) -> dict[str, str]:
+    """Build class_name → file_path index."""
+    index: dict[str, str] = {}
+    for entry in entries:
+        filepath = entry.get("file", "")
+        for cls in entry.get("classes", []):
+            name = cls.get("name", "")
+            if name:
+                index[name] = filepath
+        stem = Path(filepath).stem
+        if stem and stem not in index:
+            index[stem] = filepath
+    return index
+
+
+def _build_field_type_index(entries: list[dict]) -> dict[str, dict[str, str]]:
+    """Build file → {field_name: field_type} index."""
+    index: dict[str, dict[str, str]] = {}
+    for entry in entries:
+        filepath = entry.get("file", "")
+        fields: dict[str, str] = {}
+        for f in entry.get("fields", []):
+            if f.get("name") and f.get("type"):
+                fields[f["name"]] = f["type"]
+        if fields:
+            index[filepath] = fields
+    return index
+
+
+def _infer_package_prefix(entries: list[dict]) -> str:
+    """Auto-infer project package prefix from skeleton entries."""
+    prefix_counts: dict[str, int] = defaultdict(int)
+    for entry in entries:
+        for imp in entry.get("imports", []):
+            parts = imp.split(".")
+            if len(parts) >= 3:
+                prefix = ".".join(parts[:3])
+                prefix_counts[prefix] += 1
+    if not prefix_counts:
+        for entry in entries:
+            filepath = entry.get("file", "").replace("\\", "/")
+            idx = filepath.find("/java/")
+            if idx >= 0:
+                pkg_path = filepath[idx + 6:]
+                parts = pkg_path.split("/")
+                if len(parts) >= 3:
+                    prefix = ".".join(parts[:3])
+                    prefix_counts[prefix] += 1
+    if prefix_counts:
+        return max(prefix_counts, key=prefix_counts.get)
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Internal: Edge builders
+# ---------------------------------------------------------------------------
+
+_COMMON_TYPES = frozenset({
+    "String", "Integer", "Long", "Double", "Float", "Boolean", "Byte", "Short",
+    "Object", "Void", "BigDecimal", "BigInteger", "Date",
+    "LocalDate", "LocalDateTime", "Instant", "Duration",
+    "List", "Map", "Set", "Collection", "Optional", "Stream",
+    "HashMap", "ArrayList", "HashSet", "LinkedList",
+    "Serializable", "Comparable", "Iterable", "Iterator",
+    "Exception", "RuntimeException", "Throwable", "Logger", "Log",
+    "HttpServletRequest", "HttpServletResponse", "ResponseEntity",
+})
+
+
+def get_common_types(hooks=None) -> frozenset[str]:
+    """Get common types to exclude from dependency analysis."""
+    if hooks:
+        custom = hooks.get_common_types()
+        if custom:
+            return custom
+    return _COMMON_TYPES
+
+
+def _add_import_edges(entry: dict, source: str, class_to_file: dict, prefix: str, graph: DependencyGraph):
+    for imp in entry.get("imports", []):
+        if prefix and not imp.startswith(prefix):
+            continue
+        class_name = imp.split(".")[-1]
+        if class_name == "*":
+            continue
+        target = class_to_file.get(class_name)
+        if target and target != source:
+            graph.add_edge(source, target, WEIGHT_IMPORT, "import")
+
+
+def _add_inheritance_edges(entry: dict, source: str, class_to_file: dict, graph: DependencyGraph):
+    for cls in entry.get("classes", []):
+        extends = cls.get("extends", "")
+        if extends:
+            target = class_to_file.get(extends.split(".")[-1])
+            if target and target != source:
+                graph.add_edge(source, target, WEIGHT_INHERITANCE, "inheritance")
+        for iface in cls.get("implements", []) or []:
+            target = class_to_file.get(iface.split(".")[-1])
+            if target and target != source:
+                graph.add_edge(source, target, WEIGHT_INHERITANCE, "inheritance")
+
+
+def _add_injection_edges(entry: dict, source: str, class_to_file: dict, graph: DependencyGraph,
+                         inject_annotations: set[str] | None = None,
+                         common_types: frozenset[str] | None = None):
+    if inject_annotations is None:
+        inject_annotations = {"@Autowired", "@Resource", "@Inject", "@Value"}
+    if common_types is None:
+        common_types = _COMMON_TYPES
+    for f in entry.get("fields", []):
+        raw_annotations = f.get("annotations", [])
+        field_type = f.get("type", "")
+        if not field_type or not field_type[0].isupper():
+            continue
+        # Normalize annotations: handle both str list and dict list formats
+        annotations: list[str] = []
+        for a in raw_annotations:
+            if isinstance(a, str):
+                annotations.append(a)
+            elif isinstance(a, dict):
+                annotations.append(a.get("name", a.get("annotation", "")))
+        is_injected = any(
+            any(a.startswith(inj) for inj in inject_annotations) for a in annotations
+        )
+        if is_injected:
+            clean_type = re.sub(r'<.*>', '', field_type).strip()
+            target = class_to_file.get(clean_type)
+            if target and target != source:
+                graph.add_edge(source, target, WEIGHT_INJECTION, "injection")
+        elif field_type[0].isupper() and field_type not in common_types:
+            clean_type = re.sub(r'<.*>', '', field_type).strip()
+            if clean_type not in common_types:
+                target = class_to_file.get(clean_type)
+                if target and target != source:
+                    graph.add_edge(source, target, WEIGHT_CALL, "call")
+
+
+def _add_call_edges(entry: dict, source: str, class_to_file: dict,
+                    field_type_index: dict, graph: DependencyGraph):
+    calls = entry.get("calls", [])
+    if not calls:
+        return
+    file_fields = field_type_index.get(source, {})
+    for receiver in calls:
+        resolved_type = file_fields.get(receiver)
+        if resolved_type:
+            clean_type = re.sub(r'<.*>', '', resolved_type).strip()
+            target = class_to_file.get(clean_type)
+            if target and target != source:
+                graph.add_edge(source, target, WEIGHT_CALL, "call")
+        elif receiver[0:1].isupper():
+            target = class_to_file.get(receiver)
+            if target and target != source:
+                graph.add_edge(source, target, WEIGHT_CALL, "call")