source-kb 0.2.2__py3-none-any.whl

core/docs/section_updater.py

@@ -0,0 +1,286 @@
+"""Section-level document manipulation.
+
+Locates and replaces/appends/removes specific sections in Markdown documents.
+Shared by both sync and audit pipelines.
+
+Usage:
+    from core.docs.section_updater import replace_section, append_section, remove_section, list_sections
+
+    success = replace_section(doc_path, "## User Management", new_content, level=2)
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def replace_section(
+    doc_path: Path,
+    heading: str,
+    new_content: str,
+    level: int = 2,
+) -> bool:
+    """Replace content of a specific section.
+
+    Section boundary: from target heading (inclusive) to next heading of
+    equal or higher level (exclusive), or end of file.
+
+    Args:
+        doc_path: Path to the markdown file
+        heading: Full heading text (e.g., "## User Management") or just the text part
+        new_content: Replacement content (heading line is preserved, only body replaced)
+        level: Heading level (2 = ##, 3 = ###)
+
+    Returns:
+        True if section found and replaced, False if heading not found.
+    """
+    lines, bom = _read_lines(doc_path)
+    normalized_heading = _ensure_heading_prefix(heading, level)
+    bounds = find_section_boundaries(lines, normalized_heading, level)
+    if bounds is None:
+        return False
+
+    start_idx, end_idx = bounds
+
+    # Build replacement: keep heading line + new content
+    heading_line = lines[start_idx]
+    content_lines = new_content.rstrip("\n").split("\n") if new_content.strip() else []
+
+    # Ensure blank line after heading if content exists
+    replacement = [heading_line]
+    if content_lines:
+        if content_lines[0].strip():  # no blank line at start
+            replacement.append("")
+        replacement.extend(content_lines)
+        replacement.append("")  # blank line before next section
+
+    new_lines = lines[:start_idx] + replacement + lines[end_idx:]
+    _write_lines(doc_path, new_lines, bom)
+    return True
+
+
+def append_section(
+    doc_path: Path,
+    heading: str,
+    content: str,
+    parent_heading: str | None = None,
+    level: int = 2,
+) -> bool:
+    """Append a new section to the document.
+
+    If parent_heading is specified, inserts as last child of that section.
+    Otherwise appends at end of file.
+
+    Returns:
+        True if successfully appended.
+    """
+    lines, bom = _read_lines(doc_path)
+    normalized_heading = _ensure_heading_prefix(heading, level)
+    content_lines = content.rstrip("\n").split("\n") if content.strip() else []
+
+    section_block = ["", normalized_heading]
+    if content_lines:
+        section_block.append("")
+        section_block.extend(content_lines)
+    section_block.append("")
+
+    if parent_heading:
+        parent_normalized = _ensure_heading_prefix(parent_heading, level - 1 if level > 1 else level)
+        parent_level = _count_hashes(parent_normalized)
+        bounds = find_section_boundaries(lines, parent_normalized, parent_level)
+        if bounds is not None:
+            _, end_idx = bounds
+            # Insert before the end of parent section
+            new_lines = lines[:end_idx] + section_block + lines[end_idx:]
+            _write_lines(doc_path, new_lines, bom)
+            return True
+
+    # Fallback: append at end
+    # Ensure file ends with newline before appending
+    if lines and lines[-1].strip():
+        lines.append("")
+    new_lines = lines + section_block
+    _write_lines(doc_path, new_lines, bom)
+    return True
+
+
+def remove_section(
+    doc_path: Path,
+    heading: str,
+    level: int = 2,
+) -> bool:
+    """Remove a section and its content.
+
+    Returns:
+        True if section found and removed, False if not found.
+    """
+    lines, bom = _read_lines(doc_path)
+    normalized_heading = _ensure_heading_prefix(heading, level)
+    bounds = find_section_boundaries(lines, normalized_heading, level)
+    if bounds is None:
+        return False
+
+    start_idx, end_idx = bounds
+    new_lines = lines[:start_idx] + lines[end_idx:]
+
+    # Clean up double blank lines at removal point
+    if start_idx > 0 and start_idx < len(new_lines):
+        if not new_lines[start_idx - 1].strip() and (
+            start_idx >= len(new_lines) or not new_lines[start_idx].strip()
+        ):
+            new_lines.pop(start_idx)
+
+    _write_lines(doc_path, new_lines, bom)
+    return True
+
+
+def list_sections(
+    doc_path: Path,
+    level: int = 2,
+) -> list[str]:
+    """List all section headings at the specified level.
+
+    Returns:
+        List of heading strings (e.g., ["## User Management", "## Order Processing"])
+    """
+    lines, _ = _read_lines(doc_path)
+    prefix = "#" * level + " "
+    result: list[str] = []
+    for line in lines:
+        if line.startswith(prefix) and not line.startswith("#" * (level + 1)):
+            result.append(line)
+    return result
+
+
+def find_section_boundaries(
+    lines: list[str],
+    heading: str,
+    level: int = 2,
+) -> tuple[int, int] | None:
+    """Find start and end line indices for a section.
+
+    Args:
+        lines: Document lines (no trailing newlines)
+        heading: Normalized heading with prefix (e.g., "## User Management")
+        level: Heading level
+
+    Returns:
+        (start_idx, end_idx) where start is the heading line (inclusive) and
+        end is the first line of the next section (exclusive), or len(lines).
+        Returns None if heading not found.
+    """
+    target_norm = _normalize_heading(heading)
+    start_idx: int | None = None
+
+    for i, line in enumerate(lines):
+        if _normalize_heading(line) == target_norm:
+            start_idx = i
+            break
+
+    if start_idx is None:
+        return None
+
+    # Find end: next heading of equal or higher level
+    target_level = _count_hashes(heading)
+    for j in range(start_idx + 1, len(lines)):
+        if lines[j].startswith("#"):
+            current_level = _count_hashes(lines[j])
+            if current_level <= target_level:
+                return (start_idx, j)
+
+    return (start_idx, len(lines))
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+_EMOJI_PATTERN = re.compile(
+    r"[\U0001F300-\U0001F9FF\U00002600-\U000027BF\U0001FA00-\U0001FA6F"
+    r"\U0001FA70-\U0001FAFF\U00002702-\U000027B0]+\s*"
+)
+
+
+def _normalize_heading(text: str) -> str:
+    """Normalize a heading for comparison.
+
+    Strips whitespace, removes emoji prefixes after #, lowercases.
+    """
+    text = text.strip()
+    if not text.startswith("#"):
+        return text.lower()
+
+    # Split into prefix (###) and title
+    match = re.match(r"(#+)\s*(.*)", text)
+    if not match:
+        return text.lower()
+
+    hashes = match.group(1)
+    title = match.group(2)
+
+    # Remove leading emoji from title
+    title = _EMOJI_PATTERN.sub("", title).strip()
+
+    return f"{hashes} {title}".lower()
+
+
+def _count_hashes(line: str) -> int:
+    """Count leading # characters."""
+    count = 0
+    for ch in line:
+        if ch == "#":
+            count += 1
+        else:
+            break
+    return count
+
+
+def _ensure_heading_prefix(heading: str, level: int) -> str:
+    """Ensure heading has the correct # prefix."""
+    heading = heading.strip()
+    if heading.startswith("#"):
+        return heading
+    return "#" * level + " " + heading
+
+
+def _read_lines(doc_path: Path) -> tuple[list[str], str]:
+    """Read file into lines, detecting BOM.
+
+    Returns:
+        (lines_without_newlines, bom_prefix)
+    """
+    raw = doc_path.read_bytes()
+    bom = ""
+    if raw.startswith(b"\xef\xbb\xbf"):
+        bom = "\ufeff"
+        raw = raw[3:]
+
+    text = raw.decode("utf-8")
+    # Normalize line endings
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = text.split("\n")
+
+    # Remove trailing empty line if file ended with \n (split artifact)
+    if lines and lines[-1] == "":
+        lines.pop()
+
+    return lines, bom
+
+
+def _write_lines(doc_path: Path, lines: list[str], bom: str = "") -> None:
+    """Write lines back to file, preserving BOM and ensuring trailing newline."""
+    content = "\n".join(lines)
+    if not content.endswith("\n"):
+        content += "\n"
+    if bom:
+        doc_path.write_bytes(b"\xef\xbb\xbf" + content.encode("utf-8"))
+    else:
+        doc_path.write_text(content, encoding="utf-8")

core/docs/shared.py

@@ -0,0 +1,149 @@
+"""Shared document generation — cross-module summaries.
+
+Generates _shared/ documents that aggregate information across all modules.
+
+Usage:
+    from core.docs.shared import generate_shared_docs
+
+    generated = generate_shared_docs(knowledge_dir, config, kb_name)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from core.paths import ensure_dir
+
+logger = logging.getLogger(__name__)
+
+
+def generate_shared_docs(
+    knowledge_dir: Path,
+    config: dict[str, Any],
+    kb_name: str,
+) -> list[str]:
+    """Generate _shared/ cross-module documents.
+
+    Returns list of generated file names.
+    """
+    shared_dir = knowledge_dir / "_shared"
+    ensure_dir(shared_dir)
+
+    generated: list[str] = []
+
+    # Always generate project overview
+    overview = _generate_project_overview(shared_dir, knowledge_dir, config, kb_name)
+    if overview:
+        generated.append("project-overview.md")
+
+    # Cross-module calls (if multiple modules)
+    modules = _get_module_dirs(knowledge_dir)
+    if len(modules) >= 2:
+        cross = _generate_cross_module_calls(shared_dir, modules)
+        if cross:
+            generated.append("cross-module-calls.md")
+
+    return generated
+
+
+def _generate_project_overview(
+    shared_dir: Path, knowledge_dir: Path, config: dict, kb_name: str
+) -> bool:
+    """Generate project-overview.md from module index files."""
+    kb_config = config["knowledge_bases"][kb_name]
+    modules = _get_module_dirs(knowledge_dir)
+
+    lines = [f"# {kb_config.get('name', kb_name)} — Project Overview", ""]
+
+    for module_dir in modules:
+        index_file = module_dir / "index.md"
+        if index_file.exists():
+            # Extract first few lines as summary
+            content = index_file.read_text(encoding="utf-8")
+            first_lines = content.splitlines()[:5]
+            lines.append(f"## {module_dir.name}")
+            lines.extend(first_lines)
+            lines.append("")
+        else:
+            lines.append(f"## {module_dir.name}")
+            lines.append("(index.md not yet generated)")
+            lines.append("")
+
+    output = shared_dir / "project-overview.md"
+    output.write_text("\n".join(lines), encoding="utf-8")
+    return True
+
+
+def _generate_cross_module_calls(shared_dir: Path, modules: list[Path]) -> bool:
+    """Generate cross-module-calls.md by scanning for inter-module references."""
+    lines = ["# Cross-module call relationships", ""]
+
+    for module_dir in modules:
+        bl_file = module_dir / "business-logic.md"
+        if not bl_file.exists():
+            continue
+        content = bl_file.read_text(encoding="utf-8")
+
+        # Find references to other modules
+        other_modules = [m.name for m in modules if m != module_dir]
+        refs = []
+        for other in other_modules:
+            if other in content:
+                refs.append(other)
+
+        if refs:
+            lines.append(f"## {module_dir.name}")
+            lines.append(f"References modules: {', '.join(refs)}")
+            lines.append("")
+
+    if len(lines) <= 2:
+        return False
+
+    output = shared_dir / "cross-module-calls.md"
+    output.write_text("\n".join(lines), encoding="utf-8")
+    return True
+
+
+def _get_module_dirs(knowledge_dir: Path) -> list[Path]:
+    """Get all module directories (non-hidden, non-_shared)."""
+    if not knowledge_dir.is_dir():
+        return []
+    return sorted(
+        d for d in knowledge_dir.iterdir()
+        if d.is_dir() and not d.name.startswith(".") and d.name != "_shared"
+    )
+
+
+def module_order_topo(config: dict, kb_name: str) -> list[str]:
+    """Compute topological order of modules based on inter-module dependencies.
+
+    Reads pom.xml or package.json to determine dependency DAG.
+    Falls back to alphabetical order if no dependencies detected.
+
+    Returns ordered list of module names (upstream first).
+    """
+    kb_config = config["knowledge_bases"][kb_name]
+    source = kb_config.get("source", {})
+
+    if source.get("structure") == "multi-repo":
+        modules = [r["name"] for r in source.get("repos", [])]
+    elif source.get("structure") == "monorepo":
+        modules = [m["name"] for m in source.get("modules", [])]
+    else:
+        return []
+
+    # TODO: Parse pom.xml/package.json for actual dependency graph
+    # For now, heuristic: base-lib types first, then services
+    base_libs = []
+    services = []
+    for mod_cfg in source.get("repos", source.get("modules", [])):
+        name = mod_cfg.get("name", "")
+        mod_type = mod_cfg.get("type", "service")
+        if mod_type in ("base-lib", "api-contract"):
+            base_libs.append(name)
+        else:
+            services.append(name)
+
+    return base_libs + services