source-kb 0.2.2__py3-none-any.whl

engine/pipeline/steps/audit_helpers.py

@@ -0,0 +1,155 @@
+"""Audit helpers — progress tracking, prompt building, and utilities."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+
+from core.interfaces import PipelineContext
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_AUDIT_ORDER = [
+    "source-tree-analysis", "data-models", "enums-and-constants",
+    "database-access", "api-contracts", "architecture",
+    "caching", "messaging", "scheduled-tasks", "error-handling",
+    "security", "aop-and-interceptors", "observability",
+    "async-and-events", "external-integrations",
+    "business-logic", "utils", "index",
+]
+
+
+def compute_doc_size(module_dir: Path) -> int:
+    """Compute total size of markdown docs in a module directory."""
+    if not module_dir.is_dir():
+        return 0
+    return sum(f.stat().st_size for f in module_dir.glob("*.md"))
+
+
+def get_audit_order(ctx: PipelineContext) -> list[str]:
+    """Get document audit order from preset or default."""
+    from core.preset import load_preset
+
+    preset_name = ctx.kb_config.get("preset", "generic")
+    try:
+        preset = load_preset(preset_name)
+        doc_types = preset.get("doc_types", {})
+        ordered = sorted(
+            [(k, v.get("batch", 99)) for k, v in doc_types.items() if isinstance(v, dict)],
+            key=lambda x: x[1],
+        )
+        return [k for k, _ in ordered]
+    except Exception:
+        return _DEFAULT_AUDIT_ORDER
+
+
+def load_audit_progress(module_dir: Path) -> dict:
+    """Load audit progress state."""
+    progress_file = module_dir / ".audit-progress.json"
+    if not progress_file.exists():
+        return {}
+    try:
+        return json.loads(progress_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def update_audit_progress(
+    module_dir: Path, doc_type: str, status: str, findings_count: int = 0
+) -> None:
+    """Update audit progress for a document type."""
+    progress_file = module_dir / ".audit-progress.json"
+    progress: dict = {}
+    if progress_file.exists():
+        try:
+            progress = json.loads(progress_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    progress[doc_type] = {
+        "status": status,
+        "findings_count": findings_count,
+        "last_updated": time.strftime("%Y-%m-%dT%H:%M:%S"),
+    }
+    progress_file.write_text(
+        json.dumps(progress, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+
+def build_audit_system_prompt(doc_type: str) -> str:
+    """Build system prompt for document audit. Loads from preset template if available."""
+    from core.preset import find_preset_template
+
+    template_path = find_preset_template("java-spring", "audit-system.md")
+    if template_path and template_path.exists():
+        try:
+            return template_path.read_text(encoding="utf-8").strip()
+        except OSError:
+            pass
+    return (
+        "You are a knowledge base quality auditor. Compare document content against "
+        "the source code skeleton and identify inconsistencies.\n\n"
+        "Output format: JSON array, each element contains:\n"
+        "- dimension: audit dimension name\n"
+        '- status: "pass" or "fail"\n'
+        "- detail: issue description (required when status=fail)\n"
+        "- fix: suggested fix content (optional)\n\n"
+        "Audit dimensions:\n"
+        "- completeness: classes/methods/fields in skeleton covered in document\n"
+        "- accuracy: document descriptions match source code\n"
+        "- freshness: no outdated content (source deleted/renamed but doc not updated)\n"
+        "- reference_integrity: cross-document reference links are valid\n\n"
+        "Output JSON only, no other text."
+    )
+
+
+def build_audit_user_prompt(
+    doc_file: Path, doc_type: str, module_dir: Path, doc_truncate_chars: int = 50000
+) -> str:
+    """Build user prompt for document audit."""
+    try:
+        doc_content = doc_file.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        doc_content = ""
+
+    if len(doc_content) > doc_truncate_chars:
+        doc_content = doc_content[:doc_truncate_chars] + "\n\n... (truncated)"
+
+    skeleton_summary = ""
+    meta_dir = module_dir / ".meta"
+    summary_path = meta_dir / "skeleton-summary.json"
+    if summary_path.exists():
+        try:
+            summary_data = json.loads(summary_path.read_text(encoding="utf-8"))
+            summary_lines = []
+            for entry in summary_data[:50]:
+                fname = entry.get("file", "")
+                mc = entry.get("method_count", 0)
+                summary_lines.append(f"  {fname} ({mc} methods)")
+            skeleton_summary = "\n".join(summary_lines)
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    parts = [
+        f"Doc type: {doc_type}",
+        f"Doc path: {doc_file.name}",
+        "",
+        "Document content:",
+        doc_content,
+    ]
+
+    if skeleton_summary:
+        parts.extend([
+            "",
+            "Skeleton summary (file list):",
+            skeleton_summary,
+        ])
+
+    parts.extend([
+        "",
+        "Audit this document and output JSON-formatted audit results.",
+    ])
+
+    return "\n".join(parts)

engine/pipeline/steps/classify_llm.py

@@ -0,0 +1,236 @@
+"""LLM classification step — batch LLM calls for uncovered files.
+
+Handles:
+- LlmClassifyStep: orchestrates LLM-based file classification
+- Batch LLM calls with result caching
+- Delegated mode skip logic
+
+Requirements: 12.1, 12.2, 12.3
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+from core.interfaces import Step, StepResult, PipelineContext, LlmStrategy, LlmRequest
+from core.paths import file_list_dir, file_list_path
+from engine.pipeline import register_step
+
+logger = logging.getLogger(__name__)
+
+CACHE_FILENAME = ".llm-classify-cache.json"
+
+
+@register_step
+class LlmClassifyStep(Step):
+    """LLM-assisted classification for files not covered by rules.
+
+    Triggers when uncovered files exist after rule-based classification.
+    Results are cached to avoid redundant LLM calls on re-runs.
+    Skipped in delegated mode (no LLM access).
+    """
+
+    default_name = "llm-classify"
+
+    def __init__(self):
+        super().__init__("llm-classify")
+
+    def run(self, ctx: PipelineContext) -> StepResult:
+        from core.skeleton.file_list import load_skeleton
+        from core.skeleton.classify import find_uncovered_files
+        from core.preset import load_preset, get_doc_type_mapping
+        from engine.strategies import create_strategy
+        from engine.pipeline.steps.generate import _make_config_obj
+        from engine.pipeline.steps.classify_prompt import (
+            build_classify_prompt, parse_classify_response, generate_rules,
+        )
+
+        # Create strategy — if delegated, this step is handled by Agent directly
+        config_obj = _make_config_obj(ctx)
+        strategy = create_strategy(config_obj)
+
+        # Probe: delegated strategy means Agent handles classification
+        from core.interfaces import LlmRequest
+        probe = strategy.call(LlmRequest(system="probe", user="probe"))
+        if probe.status == "delegated":
+            return StepResult(status="skipped", message="Delegated mode: LLM classify handled by Agent")
+
+        preset_name = ctx.kb_config.get("preset", "generic")
+        preset = load_preset(preset_name)
+        doc_mapping = get_doc_type_mapping(preset)
+        strategy = create_strategy(config_obj)
+
+        module_repos: dict[str, Path] = ctx.state.get("module_repos", {})
+        cache_dir = _resolve_cache_dir(ctx)
+
+        total_uncovered = 0
+        total_classified = 0
+
+        for name in module_repos:
+            module_dir = ctx.knowledge_dir / name
+            source_cache = cache_dir / name
+            entries = load_skeleton(module_dir)
+            if not entries:
+                continue
+
+            uncovered = find_uncovered_files(entries, preset)
+            if not uncovered:
+                continue
+
+            total_uncovered += len(uncovered)
+
+            # Check cache
+            cached = _load_cache(module_dir)
+            cache_key = _compute_cache_key(uncovered)
+            if cached.get("key") == cache_key and cached.get("classifications"):
+                classifications = cached["classifications"]
+                total_classified += len(classifications)
+                _apply_classifications(module_dir, classifications, doc_mapping, source_cache)
+                continue
+
+            # Build prompt and call LLM
+            limits = preset.get("limits", {})
+            classify_max_tokens = limits.get("classify_max_tokens", 4096)
+            system_prompt, user_prompt = build_classify_prompt(uncovered, preset)
+            try:
+                resp = strategy.call(LlmRequest(
+                    system=system_prompt,
+                    user=user_prompt,
+                    max_tokens=classify_max_tokens,
+                    temperature=0.1,
+                ))
+            except Exception as e:
+                print(f"  [{name}] LLM classify error: {e}", file=sys.stderr)
+                continue
+
+            if resp.status == "delegated":
+                continue
+
+            classifications = parse_classify_response(resp.content)
+            if not classifications:
+                continue
+
+            total_classified += len(classifications)
+
+            # Cache results
+            _save_cache(module_dir, cache_key, classifications)
+
+            # Apply to file lists
+            _apply_classifications(module_dir, classifications, doc_mapping, source_cache)
+
+            # Generate rules
+            rules = generate_rules(classifications, preset)
+            if rules:
+                _write_rules(ctx.project_root, preset_name, rules)
+
+        if total_uncovered == 0:
+            return StepResult(status="ok", message="All files covered by rules")
+
+        return StepResult(
+            status="ok",
+            message=f"LLM classified {total_classified}/{total_uncovered} uncovered files",
+            details={"uncovered": total_uncovered, "classified": total_classified},
+        )
+
+
+def _resolve_cache_dir(ctx: PipelineContext) -> Path:
+    """Resolve source cache directory."""
+    cache_dir = Path(ctx.kb_config.get("source", {}).get("cache_dir", ".source-cache"))
+    if not cache_dir.is_absolute():
+        cache_dir = (ctx.project_root / cache_dir).resolve()
+    return cache_dir
+
+
+def _compute_cache_key(entries: list[dict]) -> str:
+    """Compute a stable cache key from uncovered entries."""
+    import hashlib
+    files = sorted(e.get("file", "") for e in entries)
+    return hashlib.md5("|".join(files).encode()).hexdigest()
+
+
+def _load_cache(module_dir: Path) -> dict:
+    """Load classification cache for a module."""
+    cache_path = module_dir / ".meta" / CACHE_FILENAME
+    if not cache_path.exists():
+        return {}
+    try:
+        return json.loads(cache_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save_cache(module_dir: Path, key: str, classifications: list[dict]) -> None:
+    """Save classification results to cache."""
+    cache_path = module_dir / ".meta" / CACHE_FILENAME
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    data = {"key": key, "classifications": classifications}
+    cache_path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def _apply_classifications(
+    module_dir: Path,
+    classifications: list[dict],
+    doc_mapping: dict[str, str],
+    source_cache: Path,
+) -> None:
+    """Apply LLM classifications to file lists."""
+    fl_dir = file_list_dir(module_dir)
+    fl_dir.mkdir(parents=True, exist_ok=True)
+
+    # Group files by target doc type
+    additions: dict[str, list[str]] = {}
+    for cls in classifications:
+        category = cls.get("category", "")
+        file_path = cls.get("file", "")
+        if not category or not file_path:
+            continue
+        # Find which doc file this category maps to
+        for doc_key, doc_filename in doc_mapping.items():
+            if doc_key == category or category in doc_key:
+                stem = doc_filename.removesuffix(".md")
+                full_path = str((source_cache / file_path).resolve()).replace("\\", "/")
+                additions.setdefault(stem, []).append(full_path)
+                break
+
+    # Append to existing file lists
+    for stem, files in additions.items():
+        fl = file_list_path(module_dir, stem)
+        existing = set()
+        if fl.exists():
+            existing = set(fl.read_text(encoding="utf-8").strip().splitlines())
+        existing.update(files)
+        fl.write_text("\n".join(sorted(existing)) + "\n", encoding="utf-8")
+
+
+def _write_rules(project_root: Path, preset_name: str, rules: list[dict]) -> None:
+    """Write generated rules to custom_rules.yaml."""
+    import yaml
+
+    rules_path = project_root / "presets" / preset_name / "custom_rules.yaml"
+    rules_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict = {}
+    if rules_path.exists():
+        try:
+            existing = yaml.safe_load(rules_path.read_text(encoding="utf-8")) or {}
+        except Exception:
+            pass
+
+    classification = existing.setdefault("file_classification", {})
+    for rule in rules:
+        target = rule.get("target_category", "")
+        action = rule.get("action", "")
+        value = rule.get("value", "")
+        if target and action and value:
+            cat = classification.setdefault(target, {})
+            cat.setdefault(action, [])
+            if value not in cat[action]:
+                cat[action].append(value)
+
+    rules_path.write_text(
+        yaml.dump(existing, allow_unicode=True, default_flow_style=False),
+        encoding="utf-8",
+    )

engine/pipeline/steps/classify_prompt.py

@@ -0,0 +1,223 @@
+"""Classification prompt module — template building and result parsing.
+
+Handles:
+- Classification prompt template construction
+- LLM result parsing (JSON extraction)
+- Rule generation from classification results
+
+Requirements: 12.3
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def build_classify_prompt(
+    uncovered_entries: list[dict],
+    preset: dict,
+    max_files: int = 50,
+) -> tuple[str, str]:
+    """Build LLM classification prompt.
+
+    Args:
+        uncovered_entries: Skeleton entries not covered by rules
+        preset: Current preset configuration
+        max_files: Max files per prompt batch
+
+    Returns:
+        (system_prompt, user_prompt)
+    """
+    entries = uncovered_entries[:max_files]
+    classification = preset.get("file_classification", {})
+
+    rules_summary = _format_rules(classification)
+    files_summary = _format_files(entries)
+    categories = sorted(classification.keys())
+
+    language = preset.get("language", "any")
+    language_label = preset.get("name", language)
+
+    system_prompt = (
+        f"You are a {language_label} source code classification expert.\n"
+        "Your task is to classify source files that cannot be automatically categorized by existing rules, determining which document category they belong to.\n\n"
+        "Rules:\n"
+        "1. Each file must be assigned to at least one category\n"
+        "2. Prefer existing categories; only suggest a new category if the file truly cannot fit into any existing one\n"
+        "3. Suggested rules must be automatable (based on annotations, field types, path patterns)\n"
+        "4. Output strict JSON format, do not add markdown code block markers"
+    )
+
+    user_prompt = (
+        f"## Existing Classification Rules\n\n{rules_summary}\n\n"
+        f"## Available Categories\n{', '.join(categories)}\n\n"
+        f"## Unclassified Files ({len(entries)} total)\n\n{files_summary}\n\n"
+        "## Output Requirements\n\n"
+        "Output strict JSON:\n"
+        "{\n"
+        '  "classifications": [\n'
+        '    {"file": "path", "category": "category_name", "reason": "rationale",\n'
+        '     "rule_suggestion": {"target_category": "category", '
+        '"action": "patterns_append", "value": "value"}}\n'
+        "  ]\n"
+        "}\n\n"
+        "Note: rule_suggestion is optional."
+    )
+
+    return system_prompt, user_prompt
+
+
+def parse_classify_response(response_text: str) -> list[dict]:
+    """Parse LLM classification response.
+
+    Handles:
+    - Raw JSON
+    - JSON wrapped in markdown code blocks
+    - Partial JSON extraction
+
+    Returns:
+        List of classification dicts with keys: file, category, reason, rule_suggestion
+    """
+    if not response_text:
+        return []
+
+    text = response_text.strip()
+
+    # Remove markdown code block wrapper
+    if text.startswith("```"):
+        lines = text.split("\n")
+        if lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        text = "\n".join(lines)
+
+    # Try direct parse
+    data = _try_parse_json(text)
+    if data is None:
+        # Try extracting JSON block
+        match = re.search(r'\{[\s\S]*\}', text)
+        if match:
+            data = _try_parse_json(match.group())
+
+    if not data:
+        return []
+
+    classifications = data.get("classifications", [])
+    return [
+        {
+            "file": c.get("file", ""),
+            "category": c.get("category", ""),
+            "reason": c.get("reason", ""),
+            "rule_suggestion": c.get("rule_suggestion"),
+        }
+        for c in classifications
+        if c.get("file") and c.get("category")
+    ]
+
+
+def generate_rules(classifications: list[dict], preset: dict) -> list[dict]:
+    """Generate automation rules from classification results.
+
+    Only generates rules when a clear pattern is detected
+    (e.g., multiple files with same path pattern classified to same category).
+
+    Returns:
+        List of rule dicts with keys: target_category, action, value
+    """
+    rules: list[dict] = []
+    valid_categories = set(preset.get("file_classification", {}).keys())
+
+    for cls in classifications:
+        suggestion = cls.get("rule_suggestion")
+        if not suggestion:
+            continue
+
+        target = suggestion.get("target_category", "")
+        action = suggestion.get("action", "")
+        value = suggestion.get("value", "")
+
+        if not target or not action or not value:
+            continue
+        if target not in valid_categories:
+            continue
+        if not action.endswith("_append"):
+            continue
+
+        rules.append({
+            "target_category": target,
+            "action": action,
+            "value": value,
+        })
+
+    return _deduplicate_rules(rules)
+
+
+def _format_rules(classification: dict) -> str:
+    """Format classification rules for prompt context."""
+    lines = []
+    for name, config in classification.items():
+        if not isinstance(config, dict):
+            continue
+        parts = [f"**{name}**"]
+        if config.get("class_annotations"):
+            parts.append(f"  Class annotations: {config['class_annotations']}")
+        if config.get("method_annotations"):
+            parts.append(f"  Method annotations: {config['method_annotations']}")
+        if config.get("field_types"):
+            parts.append(f"  Field types: {config['field_types'][:10]}")
+        if config.get("patterns"):
+            parts.append(f"  Path patterns: {config['patterns']}")
+        if config.get("affects"):
+            parts.append(f"  Affects documents: {config['affects']}")
+        lines.append("\n".join(parts))
+    return "\n\n".join(lines)
+
+
+def _format_files(entries: list[dict]) -> str:
+    """Format uncovered files for prompt."""
+    lines = []
+    for entry in entries:
+        file_path = entry.get("file", "")
+        classes = entry.get("classes", [])
+        methods = entry.get("methods", [])
+
+        parts = [f"### {file_path}"]
+        if classes:
+            class_info = []
+            for c in classes[:3]:
+                annos = c.get("annotations", [])
+                anno_str = f" [{', '.join(str(a) for a in annos[:5])}]" if annos else ""
+                class_info.append(f"{c.get('name', '?')}{anno_str}")
+            parts.append(f"  Classes: {'; '.join(class_info)}")
+        if methods:
+            method_names = [m.get("name", "?") for m in methods[:8]]
+            parts.append(f"  Methods: {', '.join(method_names)}")
+        lines.append("\n".join(parts))
+
+    return "\n\n".join(lines)
+
+
+def _try_parse_json(text: str) -> dict | None:
+    """Try to parse JSON, return None on failure."""
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+def _deduplicate_rules(rules: list[dict]) -> list[dict]:
+    """Remove duplicate rules."""
+    seen: set[str] = set()
+    unique: list[dict] = []
+    for rule in rules:
+        key = f"{rule['target_category']}:{rule['action']}:{rule['value']}"
+        if key not in seen:
+            seen.add(key)
+            unique.append(rule)
+    return unique