source-kb 0.2.2__py3-none-any.whl

core/skeleton/metadata.py

@@ -0,0 +1,96 @@
+"""Global metadata pre-generation for prompt injection.
+
+Generates glossary (class names + JavaDoc), dependency summary, and cross-references
+from skeleton entries. Pre-generated once per module, shared across all sub-agent prompts.
+
+Usage:
+    from core.skeleton.metadata import pregenerate, load_pregenerated, generate_global_metadata
+
+    # Pre-generate to .meta/global-metadata.md
+    pregenerate(module_dir, module_name="my-service")
+
+    # Load in prompt rendering
+    text = load_pregenerated(module_dir)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from core.skeleton.metadata_builders import (
+    build_glossary, build_dependency_summary, build_cross_references,
+)
+
+logger = logging.getLogger(__name__)
+
+PREGENERATE_FILE = "global-metadata.md"
+
+
+def generate_global_metadata(
+    skeleton_entries: list[dict],
+    doc_type: str = "",
+    module_name: str = "",
+    hooks=None,
+) -> dict[str, str]:
+    """Generate global metadata sections from skeleton entries.
+
+    Returns dict with keys: glossary, dependency_summary, cross_references.
+    """
+    return {
+        "glossary": build_glossary(skeleton_entries),
+        "dependency_summary": build_dependency_summary(skeleton_entries, hooks=hooks),
+        "cross_references": build_cross_references(skeleton_entries, doc_type),
+    }
+
+
+def format_metadata_for_prompt(metadata: dict[str, str], max_chars: int = 3000) -> str:
+    """Format metadata dict into a prompt-injectable text block."""
+    parts: list[str] = []
+    remaining = max_chars
+
+    sections = [
+        ("Module Core Concepts", "glossary"),
+        ("Business Dependencies", "dependency_summary"),
+        ("Cross-Document References", "cross_references"),
+    ]
+
+    for title, key in sections:
+        content = metadata.get(key, "")
+        if not content or remaining < 200:
+            continue
+        section = f"### {title}\n\n{content}"
+        if len(section) > remaining:
+            section = section[:remaining - 30] + "\n\n[truncated]"
+        parts.append(section)
+        remaining -= len(section)
+
+    if not parts:
+        return ""
+    return "## Global Metadata (terminology consistency reference)\n\n" + "\n\n".join(parts)
+
+
+def pregenerate(module_dir: Path, module_name: str = "") -> Path:
+    """Pre-generate global metadata to .meta/global-metadata.md."""
+    from core.skeleton.file_list import load_skeleton
+    from core.paths import ensure_dir
+
+    entries = load_skeleton(module_dir)
+    if not entries:
+        raise RuntimeError(f"No skeleton entries found in {module_dir}")
+
+    metadata = generate_global_metadata(entries, module_name=module_name)
+    text = format_metadata_for_prompt(metadata, max_chars=4000)
+
+    output_path = module_dir / ".meta" / PREGENERATE_FILE
+    ensure_dir(output_path.parent)
+    output_path.write_text(text, encoding="utf-8")
+    return output_path
+
+
+def load_pregenerated(module_dir: Path) -> str:
+    """Load pre-generated metadata file. Returns empty string if not found."""
+    path = module_dir / ".meta" / PREGENERATE_FILE
+    if path.exists():
+        return path.read_text(encoding="utf-8").strip()
+    return ""

core/skeleton/metadata_builders.py

@@ -0,0 +1,264 @@
+"""Metadata builders — glossary, dependency summary, cross-references.
+
+Internal helpers for core/skeleton/metadata.py. Not part of public API.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections import defaultdict
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def build_glossary(entries: list[dict]) -> str:
+    """Build glossary: prioritize classes with JavaDoc, then business classes."""
+    inject_count = _count_injection_refs(entries)
+
+    candidates: list[tuple[int, str]] = []
+    seen: set[str] = set()
+
+    for entry in entries:
+        for cls in entry.get("classes", []):
+            name = cls.get("name", "")
+            if not name or name in seen or len(name) < 3:
+                continue
+            seen.add(name)
+
+            doc = cls.get("doc", "")
+            if doc and _is_placeholder_doc(doc):
+                doc = ""
+
+            if not doc and _is_excluded_class(name):
+                continue
+
+            priority = 0
+            if doc:
+                priority += 3
+            if _is_business_suffix(name):
+                priority += 2
+            if inject_count.get(name, 0) >= 2:
+                priority += 1
+
+            if priority < 2:
+                continue
+
+            if doc:
+                clean_doc = doc.split("\n")[0].strip()
+                clean_doc = clean_doc.replace("<br>", "").replace("&lt;br&gt;", "").strip()
+                clean_doc = clean_doc.rstrip(".").strip()[:80]
+                line = f"- **{name}**: {clean_doc}" if clean_doc else f"- **{name}**"
+            elif inject_count.get(name, 0) >= 2:
+                line = f"- **{name}** (injected by {inject_count[name]} classes)"
+            else:
+                line = f"- **{name}**"
+
+            candidates.append((priority, line))
+
+    if not candidates:
+        return ""
+
+    candidates.sort(key=lambda x: (-x[0], x[1]))
+    lines = [item[1] for item in candidates[:20]]
+    return "\n".join(lines)
+
+
+def build_dependency_summary(entries: list[dict], hooks=None) -> str:
+    """Build dependency summary: Service -> injected business dependencies."""
+    if hooks:
+        inject_annotations = hooks.get_inject_annotations()
+        framework_types = hooks.get_framework_types()
+    else:
+        inject_annotations = {"@Autowired", "@Resource", "@Inject", "Autowired", "Resource", "Inject"}
+        framework_types = set()
+
+    deps: dict[str, list[str]] = defaultdict(list)
+
+    for entry in entries:
+        classes = entry.get("classes", [])
+        if not classes:
+            continue
+        main_class = classes[0].get("name", "")
+        if not main_class or not _is_core_business_class(main_class):
+            continue
+
+        fields = entry.get("fields", []) or classes[0].get("fields", [])
+        for field in fields:
+            annotations = field.get("annotations", [])
+            field_type = field.get("type", "")
+            if not field_type or not field_type[0].isupper():
+                continue
+
+            is_injected = any(
+                any(
+                    inj in ((a.get("name", "") if isinstance(a, dict) else str(a)))
+                    for inj in inject_annotations
+                )
+                for a in annotations
+            ) if annotations else True
+
+            if not is_injected:
+                continue
+
+            clean_type = re.sub(r'<.*>', '', field_type).strip()
+
+            if clean_type in framework_types:
+                continue
+            if clean_type.endswith(("Mapper", "Dao", "DaoImpl", "Repository")):
+                continue
+            if not _is_injectable_type(clean_type):
+                continue
+
+            if clean_type and clean_type != main_class:
+                deps[main_class].append(clean_type)
+
+    if not deps:
+        return ""
+
+    filtered = {k: v for k, v in deps.items() if len(set(v)) >= 2}
+    if not filtered:
+        filtered = deps
+
+    lines = []
+    for cls, dep_list in sorted(filtered.items(), key=lambda x: -len(set(x[1])))[:10]:
+        unique_deps = sorted(set(dep_list))
+        if len(unique_deps) > 8:
+            dep_str = ", ".join(unique_deps[:8]) + f" ... ({len(unique_deps)} total)"
+        else:
+            dep_str = ", ".join(unique_deps)
+        lines.append(f"- {cls} -> {dep_str}")
+
+    return "\n".join(lines)
+
+
+def build_cross_references(entries: list[dict], doc_type: str, preset: dict | None = None) -> str:
+    """Build cross-reference hints (which classes belong to other doc types)."""
+    hints: list[str] = []
+    infra_classes: list[str] = []
+    model_classes: list[str] = []
+
+    for entry in entries:
+        for cls in entry.get("classes", []):
+            name = cls.get("name", "")
+            if _is_infra_class(name):
+                infra_classes.append(name)
+            elif name.endswith(("VO", "DTO", "DO", "Entity", "Model")):
+                model_classes.append(name)
+
+    has_model_dep = False
+    has_arch_dep = False
+    if preset:
+        from core.preset import get_doc_type_config
+        cfg = get_doc_type_config(preset, doc_type)
+        deps = cfg.get("depends_on", [])
+        has_model_dep = any(d in ("data-models", "enums-and-constants") for d in deps)
+        has_arch_dep = any(d in ("architecture",) for d in deps)
+    else:
+        has_model_dep = doc_type == "business-logic"
+        has_arch_dep = doc_type == "business-logic"
+
+    if has_model_dep and model_classes:
+        model_doc = "data-models.md"
+        if preset:
+            try:
+                from core.preset import get_doc_filename
+                model_doc = get_doc_filename(preset, "data-models", strict=False) or model_doc
+            except Exception as e:
+                logger.debug("get_doc_filename failed for data-models: %s", e)
+        hints.append(f"Data model classes (see {model_doc}): {', '.join(model_classes[:5])}")
+    if has_arch_dep and infra_classes:
+        arch_doc = "architecture.md"
+        if preset:
+            try:
+                from core.preset import get_doc_filename
+                arch_doc = get_doc_filename(preset, "architecture", strict=False) or arch_doc
+            except Exception as e:
+                logger.debug("get_doc_filename failed for architecture: %s", e)
+        hints.append(f"Infrastructure classes (see {arch_doc}): {', '.join(infra_classes[:5])}")
+
+    return "\n".join(f"- {h}" for h in hints) if hints else ""
+
+
+# ---------------------------------------------------------------------------
+# Classification helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_placeholder_doc(doc: str) -> bool:
+    placeholders = ["TODO", "FIXME", "&lt;br&gt;"]
+    return any(p in doc for p in placeholders)
+
+
+def _is_excluded_class(name: str) -> bool:
+    excluded_suffixes = (
+        "Config", "Configuration", "Properties", "Aspect", "Interceptor", "Filter",
+        "Mapper", "Dao", "DaoImpl", "Repository",
+        "DTO", "VO", "BO", "DO", "PO", "Param", "Request", "Response", "Result",
+        "Entity", "Model",
+        "Util", "Utils", "Helper", "Tool", "Tools",
+        "Constant", "Constants", "Enum",
+        "Converter", "Adapter", "Wrapper",
+        "Test", "Tests", "Mock",
+    )
+    java_types = {"String", "Integer", "Long", "Boolean", "Double", "Float",
+                  "List", "Map", "Set", "Date", "BigDecimal", "Object",
+                  "Collection", "Optional", "Class", "Void"}
+    return name.endswith(excluded_suffixes) or name in java_types
+
+
+def _is_business_suffix(name: str) -> bool:
+    suffixes = ("ServiceImpl", "Service", "Handler", "Processor", "Manager",
+                "Facade", "Strategy", "Validator", "Factory",
+                "Listener", "Consumer", "Producer", "Client", "Feign", "Biz", "BizImpl")
+    return any(name.endswith(s) for s in suffixes)
+
+
+def _count_injection_refs(entries: list[dict]) -> dict[str, int]:
+    counts: defaultdict[str, int] = defaultdict(int)
+    for entry in entries:
+        for field in entry.get("fields", []):
+            ftype = field.get("type", "")
+            if ftype and ftype[0].isupper() and len(ftype) > 2:
+                base = ftype.split("<")[0].split("[")[0].strip()
+                if not _is_excluded_class(base):
+                    counts[base] += 1
+    return dict(counts)
+
+
+def _is_core_business_class(name: str) -> bool:
+    if not name or not name[0].isupper() or len(name) <= 2:
+        return False
+    infra_suffixes = ("Config", "Configuration", "Properties", "Interceptor",
+                      "Filter", "Aspect", "Advisor", "Converter", "Mapper")
+    if name.endswith(infra_suffixes):
+        return False
+    data_suffixes = ("DTO", "VO", "DO", "Entity", "Enum", "Constant", "Constants")
+    if name.endswith(data_suffixes):
+        return False
+    java_types = {"String", "Integer", "Long", "Boolean", "Double", "Float",
+                  "List", "Map", "Set", "Date", "BigDecimal", "Object",
+                  "Collection", "Optional", "Class", "Void"}
+    if name in java_types:
+        return False
+    business_suffixes = ("ServiceImpl", "Service", "Handler", "Processor",
+                         "Manager", "Listener", "Factory", "Client", "Feign",
+                         "Strategy", "Facade", "Biz", "BizImpl")
+    return any(name.endswith(s) for s in business_suffixes)
+
+
+def _is_injectable_type(name: str) -> bool:
+    if not name or not name[0].isupper() or len(name) <= 2:
+        return False
+    exclude = {"String", "Integer", "Long", "Boolean", "Double", "Float",
+               "List", "Map", "Set", "Date", "BigDecimal", "Object",
+               "Collection", "Optional", "Class", "Void", "byte", "int",
+               "DateTimeFormatter", "Logger", "ObjectMapper"}
+    if name in exclude:
+        return False
+    return True
+
+
+def _is_infra_class(name: str) -> bool:
+    return name.endswith(("Config", "Configuration", "Properties", "Interceptor", "Filter", "Aspect", "Advisor"))

core/skeleton/module_dag.py

@@ -0,0 +1,330 @@
+"""Cross-module DAG topological sort — build module dependency order from pom.xml.
+
+Parses multi-module Maven projects to determine generation order: modules that are
+depended upon should be generated first so downstream modules can reference their docs.
+
+Usage:
+    from core.skeleton.module_dag import build_module_dag, topo_sort_modules
+
+    dag = build_module_dag(source_cache_dir, module_names)
+    ordered = topo_sort_modules(dag)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from core.skeleton.pom_parser import parse_pom
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ModuleNode:
+    """A single module in the dependency DAG."""
+
+    name: str
+    artifact_id: str = ""
+    group_id: str = ""
+    pom_path: Path | None = None
+
+
+@dataclass
+class ModuleDAG:
+    """Directed acyclic graph of module dependencies.
+
+    Edges point from dependent → dependency (A depends on B → edge A→B).
+    Topological sort yields dependencies first (B before A).
+    """
+
+    nodes: dict[str, ModuleNode] = field(default_factory=dict)
+    # adjacency: module_name → set of module_names it depends on
+    edges: dict[str, set[str]] = field(default_factory=dict)
+    # reverse: module_name → set of module_names that depend on it
+    reverse_edges: dict[str, set[str]] = field(default_factory=dict)
+
+    def add_node(self, node: ModuleNode) -> None:
+        self.nodes[node.name] = node
+        self.edges.setdefault(node.name, set())
+        self.reverse_edges.setdefault(node.name, set())
+
+    def add_edge(self, dependent: str, dependency: str) -> None:
+        """Add edge: `dependent` depends on `dependency`."""
+        self.edges.setdefault(dependent, set()).add(dependency)
+        self.reverse_edges.setdefault(dependency, set()).add(dependent)
+
+    @property
+    def module_names(self) -> list[str]:
+        return list(self.nodes.keys())
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def build_module_dag(
+    source_cache_dir: Path,
+    module_names: list[str],
+    module_paths: dict[str, Path] | None = None,
+) -> ModuleDAG:
+    """Build a module dependency DAG by parsing pom.xml files.
+
+    Args:
+        source_cache_dir: Root directory containing module source caches.
+        module_names: List of module names to include in the DAG.
+        module_paths: Optional explicit mapping of module_name → source directory.
+                      If not provided, assumes source_cache_dir/{module_name}/pom.xml.
+
+    Returns:
+        ModuleDAG with nodes and dependency edges between known modules.
+    """
+    dag = ModuleDAG()
+
+    # Phase 1: Parse all pom.xml files and build artifact→module index
+    artifact_to_module: dict[str, str] = {}  # "groupId:artifactId" → module_name
+    module_poms: dict[str, dict[str, Any]] = {}
+
+    for module_name in module_names:
+        if module_paths and module_name in module_paths:
+            module_dir = module_paths[module_name]
+        else:
+            module_dir = source_cache_dir / module_name
+
+        pom_path = _find_pom(module_dir)
+        if pom_path is None:
+            logger.debug("No pom.xml found for module %s in %s", module_name, module_dir)
+            dag.add_node(ModuleNode(name=module_name))
+            continue
+
+        try:
+            pom_data = parse_pom(pom_path)
+        except Exception as e:
+            logger.warning("Failed to parse pom.xml for %s: %s", module_name, e)
+            dag.add_node(ModuleNode(name=module_name))
+            continue
+
+        group_id = pom_data.get("group_id", "")
+        artifact_id = pom_data.get("artifact_id", "")
+
+        node = ModuleNode(
+            name=module_name,
+            artifact_id=artifact_id,
+            group_id=group_id,
+            pom_path=pom_path,
+        )
+        dag.add_node(node)
+
+        # Register artifact coordinate → module name
+        if group_id and artifact_id:
+            key = f"{group_id}:{artifact_id}"
+            artifact_to_module[key] = module_name
+        # Also register without groupId for fuzzy matching
+        if artifact_id:
+            artifact_to_module.setdefault(artifact_id, module_name)
+
+        module_poms[module_name] = pom_data
+
+    # Phase 2: Build edges from dependency declarations
+    for module_name, pom_data in module_poms.items():
+        all_deps = pom_data.get("dependencies", []) + pom_data.get("dependency_management", [])
+
+        for dep in all_deps:
+            dep_group = dep.get("groupId", "")
+            dep_artifact = dep.get("artifactId", "")
+            if not dep_artifact:
+                continue
+
+            # Skip test/provided scope dependencies for ordering purposes
+            scope = dep.get("scope", "compile")
+            if scope in ("test", "provided", "system"):
+                continue
+
+            # Try to match against known modules
+            dep_key = f"{dep_group}:{dep_artifact}" if dep_group else ""
+            target_module = None
+
+            if dep_key and dep_key in artifact_to_module:
+                target_module = artifact_to_module[dep_key]
+            elif dep_artifact in artifact_to_module:
+                target_module = artifact_to_module[dep_artifact]
+
+            if target_module and target_module != module_name:
+                dag.add_edge(module_name, target_module)
+                logger.debug(
+                    "Module %s depends on %s (via %s:%s)",
+                    module_name, target_module, dep_group, dep_artifact,
+                )
+
+    return dag
+
+
+def topo_sort_modules(dag: ModuleDAG) -> list[str]:
+    """Topological sort: dependencies come first (Kahn's algorithm).
+
+    Modules with no dependencies are generated first. If cycles exist,
+    remaining modules are appended in alphabetical order at the end.
+
+    Returns:
+        Ordered list of module names (generate in this order).
+    """
+    if not dag.nodes:
+        return []
+
+    # Compute in-degree (number of dependencies each module has)
+    in_degree: dict[str, int] = {name: 0 for name in dag.nodes}
+    for module_name, deps in dag.edges.items():
+        # in_degree counts how many modules this module depends on
+        # But for topo sort we want: dependency comes first
+        # So we reverse: edge A→B means A depends on B, B should come first
+        for dep in deps:
+            if dep in in_degree:
+                pass  # dep is depended upon, not the one with in-degree
+
+    # Recompute using reverse_edges for proper Kahn's
+    # reverse_edges[B] = {A} means A depends on B
+    # For generation order: B before A
+    # Standard Kahn's on the "depends-on" graph reversed:
+    # Node with in_degree 0 = no one depends on it... wrong direction.
+    #
+    # Correct approach: treat edges as "must come before" relationships.
+    # If A depends on B, then B must come before A.
+    # So edge direction for topo sort: B → A (B before A).
+    # in_degree of A = number of modules A depends on.
+
+    in_degree = {name: len(deps) for name, deps in dag.edges.items()}
+    # Ensure all nodes are present
+    for name in dag.nodes:
+        in_degree.setdefault(name, 0)
+
+    queue = deque(sorted(n for n in dag.nodes if in_degree.get(n, 0) == 0))
+    result: list[str] = []
+
+    while queue:
+        node = queue.popleft()
+        result.append(node)
+        # For each module that depends on `node`, decrease its in-degree
+        for dependent in dag.reverse_edges.get(node, set()):
+            if dependent in in_degree:
+                in_degree[dependent] -= 1
+                if in_degree[dependent] == 0:
+                    queue.append(dependent)
+
+    # Handle cycles: append remaining nodes alphabetically
+    remaining = sorted(n for n in dag.nodes if n not in set(result))
+    if remaining:
+        logger.warning(
+            "Cycle detected in module dependencies. Appending %d modules: %s",
+            len(remaining), remaining,
+        )
+        result.extend(remaining)
+
+    return result
+
+
+def detect_module_cycles(dag: ModuleDAG) -> list[list[str]]:
+    """Detect cycles in the module dependency graph.
+
+    Returns:
+        List of cycles, each cycle is a list of module names forming the loop.
+    """
+    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 dep in dag.edges.get(node, set()):
+            if dep not in dag.nodes:
+                continue
+            if dep not in visited:
+                dfs(dep)
+            elif dep in rec_stack:
+                cycle_start = path.index(dep)
+                cycles.append(path[cycle_start:] + [dep])
+
+        path.pop()
+        rec_stack.discard(node)
+
+    for node in sorted(dag.nodes):
+        if node not in visited:
+            dfs(node)
+
+    return cycles
+
+
+def get_generation_layers(dag: ModuleDAG) -> list[list[str]]:
+    """Group modules into parallel generation layers.
+
+    Each layer contains modules whose dependencies are all in previous layers.
+    Modules within the same layer can be generated in parallel.
+
+    Returns:
+        List of layers, each layer is a list of module names.
+    """
+    if not dag.nodes:
+        return []
+
+    in_degree = {name: len(deps) for name, deps in dag.edges.items()}
+    for name in dag.nodes:
+        in_degree.setdefault(name, 0)
+
+    remaining = set(dag.nodes.keys())
+    layers: list[list[str]] = []
+
+    while remaining:
+        # Find all nodes with in_degree 0 among remaining
+        layer = sorted(n for n in remaining if in_degree.get(n, 0) == 0)
+        if not layer:
+            # Cycle: break by taking alphabetically first remaining node
+            layer = [sorted(remaining)[0]]
+            logger.warning("Breaking cycle at module: %s", layer[0])
+
+        layers.append(layer)
+        remaining -= set(layer)
+
+        # Decrease in-degree for dependents
+        for node in layer:
+            for dependent in dag.reverse_edges.get(node, set()):
+                if dependent in remaining:
+                    in_degree[dependent] = in_degree.get(dependent, 1) - 1
+
+    return layers
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _find_pom(module_dir: Path) -> Path | None:
+    """Find pom.xml in a module directory, checking common locations."""
+    if not module_dir.is_dir():
+        return None
+
+    # Direct pom.xml
+    direct = module_dir / "pom.xml"
+    if direct.exists():
+        return direct
+
+    # Check one level deeper (e.g., module-name/module-provider/pom.xml)
+    for child in module_dir.iterdir():
+        if child.is_dir() and not child.name.startswith("."):
+            candidate = child / "pom.xml"
+            if candidate.exists():
+                return candidate
+
+    return None