source-kb 0.2.2__py3-none-any.whl

core/prompt/templates.py

@@ -0,0 +1,357 @@
+"""Prompt template dataclass and registry.
+
+Provides parameterized prompt templates for LLM steps (sync section-update,
+audit doc-type checks, etc.). Templates are registered by name and looked up
+at runtime.
+
+Usage:
+    from core.prompt.templates import PromptTemplate, register, get, list_templates
+
+    template = get("sync:section-update")
+    system, user = template.render(doc_type="business-logic", ...)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PromptTemplate:
+    """A parameterized prompt template with system and user parts."""
+
+    name: str
+    system_template: str
+    user_template: str
+
+    def render(self, **kwargs: str) -> tuple[str, str]:
+        """Render both templates with provided variables.
+
+        Missing keys render as empty string (safe fallback).
+        Returns (system_prompt, user_prompt).
+        """
+        safe = _SafeDict(kwargs)
+        return (
+            self.system_template.format_map(safe),
+            self.user_template.format_map(safe),
+        )
+
+
+class _SafeDict(dict):
+    """format_map fallback — missing keys render as empty string."""
+    def __missing__(self, key: str) -> str:
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+_REGISTRY: dict[str, PromptTemplate] = {}
+
+
+def register(template: PromptTemplate) -> PromptTemplate:
+    """Register a template by name. Returns the template for decorator use."""
+    _REGISTRY[template.name] = template
+    return template
+
+
+def get(name: str) -> PromptTemplate:
+    """Look up a registered template by name. Raises KeyError if not found."""
+    if name not in _REGISTRY:
+        available = ", ".join(sorted(_REGISTRY.keys()))
+        raise KeyError(f"Template '{name}' not found. Available: {available}")
+    return _REGISTRY[name]
+
+
+def list_templates() -> list[str]:
+    """Return sorted list of all registered template names."""
+    return sorted(_REGISTRY.keys())
+
+
+# ---------------------------------------------------------------------------
+# Built-in templates: Audit
+# ---------------------------------------------------------------------------
+
+_AUDIT_SYSTEM_COMMON = (
+    "You are a knowledge base auditor. Compare the document against source code "
+    "and report findings.\n"
+    'Return ONLY a JSON object: {{"findings": [{{"dimension": "...", '
+    '"status": "pass|fail", "detail": "...", "fix": "..."}}]}}\n'
+    '- "pass": document matches source code for this dimension\n'
+    '- "fail": inconsistency found — "detail" explains what\'s wrong, '
+    '"fix" gives the corrected content\n'
+    "- Be precise: cite specific class/method/field names\n"
+    "- Output in Chinese"
+)
+
+register(PromptTemplate(
+    name="audit:source-tree",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: source-tree-analysis.md\n"
+        "Dimensions: 1.file completeness 2.directory structure 3.file responsibility "
+        "4.file count 5.new/deleted files",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Source skeleton:\n{skeleton}\n\nActual file list:\n{file_list}\n\n"
+        "Audit source-tree-analysis.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:data-models",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: data-models.md\n"
+        "Dimensions: 1.entity completeness 2.field consistency 3.annotation accuracy "
+        "4.table name mapping 5.DTO/VO coverage 6.enum values 7.inheritance",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Entity/DTO/VO skeleton:\n{skeleton}\n\nSource snippets:\n{source_snippets}\n\n"
+        "Audit data-models.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:api-contracts",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: api-contracts.md\n"
+        "Dimensions: 1.interface completeness 2.URL path 3.HTTP method 4.request params "
+        "5.response type 6.error codes 7.Feign fallback 8.permission annotations",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Controller/API skeleton:\n{skeleton}\n\n"
+        "Audit api-contracts.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:architecture",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: architecture.md\n"
+        "Dimensions: 1.tech stack versions 2.dependency list 3.layer structure "
+        "4.middleware config 5.component relationships 6.config items",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "pom.xml:\n{pom_xml}\n\nConfig (yml):\n{yml_config}\n\n"
+        "Config class skeleton:\n{skeleton}\n\n"
+        "Audit architecture.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:business-logic",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: business-logic.md\n"
+        "Dimensions (10 method-level): 1.method purpose 2.parameter semantics "
+        "3.return value meaning 4.core logic flow 5.branch condition rationale "
+        "6.exception handling 7.external dependency 8.state mutation "
+        "9.performance/concurrency 10.edge case coverage "
+        "Plus: 11.reference integrity 12.dedup compliance",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Service skeleton:\n{skeleton}\n\nSource code (high-complexity methods):\n"
+        "{source_code}\n\nNeutral doc headings:\n{neutral_doc_headings}\n\n"
+        "Audit business-logic.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:messaging",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: messaging.md\n"
+        "Dimensions: 1.topic completeness 2.message body structure "
+        "3.consumer groupId 4.producer/consumer relationships",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Messaging skeleton:\n{skeleton}\n\n"
+        "Audit messaging.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:caching",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: caching.md\n"
+        "Dimensions: 1.key completeness 2.TTL accuracy 3.data type correctness",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Caching skeleton:\n{skeleton}\n\nKey constants:\n{key_constants}\n\n"
+        "Audit caching.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:enums",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: enums-and-constants.md\n"
+        "Dimensions: 1.enum completeness 2.enum value accuracy "
+        "3.constant value correctness 4.usage context",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Enum/constant skeleton:\n{skeleton}\n\n"
+        "Audit enums-and-constants.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:utils",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: utils.md\n"
+        "Dimensions: 1.utility class completeness 2.method signature accuracy "
+        "3.usage context",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Utility skeleton:\n{skeleton}\n\n"
+        "Audit utils.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:external",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: external-integrations.md\n"
+        "Dimensions: 1.integration completeness 2.endpoint/URL accuracy "
+        "3.request/response format 4.error handling",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Integration skeleton:\n{skeleton}\n\n"
+        "Audit external-integrations.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:database",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: database-access.md\n"
+        "Dimensions: 1.mapper completeness 2.SQL semantics accuracy "
+        "3.transaction boundaries 4.pagination params 5.batch operations 6.table mapping",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "DAO/Mapper skeleton:\n{skeleton}\n\nSource snippets:\n{source_snippets}\n\n"
+        "Audit database-access.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:scheduled",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: scheduled-tasks.md\n"
+        "Dimensions: 1.task completeness 2.cron expression accuracy "
+        "3.execution frequency 4.idempotency 5.error handling 6.sharding strategy",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Scheduled task skeleton:\n{skeleton}\n\n"
+        "Audit scheduled-tasks.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:error",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: error-handling.md\n"
+        "Dimensions: 1.exception class completeness 2.hierarchy structure "
+        "3.error code mapping 4.global handler logic 5.user-facing messages",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Exception skeleton:\n{skeleton}\n\n"
+        "Audit error-handling.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:security",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: security.md\n"
+        "Dimensions: 1.auth flow completeness 2.token mechanism "
+        "3.permission model 4.filter chain order 5.permission identifiers",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Security skeleton:\n{skeleton}\n\n"
+        "Audit security.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:aop",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: aop-and-interceptors.md\n"
+        "Dimensions: 1.aspect completeness 2.pointcut expression accuracy "
+        "3.execution order 4.interceptor chain 5.advice type logic",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "AOP/Interceptor skeleton:\n{skeleton}\n\n"
+        "Audit aop-and-interceptors.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:observability",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: observability.md\n"
+        "Dimensions: 1.metric completeness 2.metric name accuracy "
+        "3.alert thresholds 4.logging config 5.health checks",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Observability skeleton:\n{skeleton}\n\n"
+        "Audit observability.md against source code."
+    ),
+))
+
+register(PromptTemplate(
+    name="audit:async",
+    system_template=_AUDIT_SYSTEM_COMMON + "\nTarget: async-and-events.md\n"
+        "Dimensions: 1.thread pool config 2.async method completeness "
+        "3.event pub/sub relationships 4.failure handling 5.event timing",
+    user_template=(
+        "Module: {module_name}\nCurrent document:\n{doc_content}\n\n"
+        "Async/Event skeleton:\n{skeleton}\n\n"
+        "Audit async-and-events.md against source code."
+    ),
+))
+
+# ---------------------------------------------------------------------------
+# Built-in templates: Sync (incremental update)
+# ---------------------------------------------------------------------------
+
+register(PromptTemplate(
+    name="sync:section-update",
+    system_template=(
+        "You are a knowledge base maintainer. Update a specific document section "
+        "based on source code changes.\nRules:\n"
+        "- Only rewrite the affected section, preserve the rest\n"
+        "- Maintain existing document structure and style\n"
+        "- Write from business perspective, not code translation\n"
+        "- Output the complete updated section content in Chinese\n"
+        "- Do NOT output anything outside the section content"
+    ),
+    user_template=(
+        "Document type: {doc_type}\nSection heading: {section_heading}\n\n"
+        "Current section content:\n{old_content}\n\n"
+        "Changed source files:\n{changed_files}\n\n"
+        "Skeleton delta:\n{skeleton_delta}\n\n"
+        "Rewrite this section to reflect the source code changes."
+    ),
+))
+
+# ---------------------------------------------------------------------------
+# Audit doc_type → template name mapping
+# ---------------------------------------------------------------------------
+
+
+def get_audit_doc_type_map(preset: dict | None = None) -> dict[str, str]:
+    """Generate audit template mapping from preset doc_types dynamically."""
+    if preset:
+        doc_types = preset.get("doc_types", {})
+        if doc_types:
+            result: dict[str, str] = {}
+            for dt_key in doc_types:
+                short = dt_key.split("-")[0] if "-" in dt_key else dt_key
+                result[dt_key] = f"audit:{short}"
+            return result
+    # Fallback for backward compat
+    return AUDIT_DOC_TYPE_MAP
+
+
+AUDIT_DOC_TYPE_MAP: dict[str, str] = {
+    "source-tree-analysis": "audit:source-tree",
+    "data-models": "audit:data-models",
+    "api-contracts": "audit:api-contracts",
+    "architecture": "audit:architecture",
+    "business-logic": "audit:business-logic",
+    "messaging": "audit:messaging",
+    "caching": "audit:caching",
+    "enums-and-constants": "audit:enums",
+    "utils": "audit:utils",
+    "external-integrations": "audit:external",
+    "database-access": "audit:database",
+    "scheduled-tasks": "audit:scheduled",
+    "error-handling": "audit:error",
+    "security": "audit:security",
+    "aop-and-interceptors": "audit:aop",
+    "observability": "audit:observability",
+    "async-and-events": "audit:async",
+}

core/prompt/validate_parity.py

@@ -0,0 +1,162 @@
+"""Template parity validation — ensures CLI and Agent templates stay in sync.
+
+Validates that:
+1. Every CLI_Template (audit:*, sync:*) has a corresponding Agent_Template .md file
+2. Variable placeholders match between CLI and Agent versions
+3. No orphaned Agent templates without CLI registration
+
+Usage:
+    python -m core.prompt validate-parity --preset java-spring
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class ParityViolation:
+    """A single parity violation."""
+
+    template_name: str
+    violation_type: str  # "missing_agent", "missing_cli", "variable_mismatch"
+    detail: str
+
+
+def validate_parity(preset_name: str) -> list[ParityViolation]:
+    """Compare CLI templates against Agent template files.
+
+    Returns list of violations (empty = all good).
+    """
+    from core.prompt.templates import _REGISTRY as REGISTRY
+    from core.preset import PRESETS_DIR
+
+    violations: list[ParityViolation] = []
+    templates_dir = PRESETS_DIR / preset_name / "templates"
+
+    if not templates_dir.is_dir():
+        violations.append(ParityViolation(
+            template_name="*",
+            violation_type="missing_agent",
+            detail=f"Templates directory not found: {templates_dir}",
+        ))
+        return violations
+
+    # Check CLI → Agent direction
+    for name, template in REGISTRY.items():
+        if not (name.startswith("audit:") or name.startswith("sync:")):
+            continue
+
+        # Expected agent template filename: "audit:business-logic" → "subagent-audit-business-logic.md"
+        agent_filename = "subagent-" + name.replace(":", "-") + ".md"
+        agent_path = templates_dir / agent_filename
+
+        if not agent_path.exists():
+            violations.append(ParityViolation(
+                template_name=name,
+                violation_type="missing_agent",
+                detail=f"Agent template not found: {agent_filename}",
+            ))
+            continue
+
+        # Compare variables
+        cli_vars = _extract_cli_variables(template)
+        agent_vars = _extract_agent_variables(agent_path)
+
+        missing_in_agent = cli_vars - agent_vars
+        missing_in_cli = agent_vars - cli_vars
+
+        if missing_in_agent:
+            violations.append(ParityViolation(
+                template_name=name,
+                violation_type="variable_mismatch",
+                detail=f"Variables in CLI but not Agent: {sorted(missing_in_agent)}",
+            ))
+        if missing_in_cli:
+            violations.append(ParityViolation(
+                template_name=name,
+                violation_type="variable_mismatch",
+                detail=f"Variables in Agent but not CLI: {sorted(missing_in_cli)}",
+            ))
+
+    # Check Agent → CLI direction (orphaned agent templates)
+    for md_file in sorted(templates_dir.glob("subagent-audit-*.md")):
+        # "subagent-audit-business.md" → "audit:business"
+        stem = md_file.stem  # "subagent-audit-business"
+        parts = stem.split("-", 1)  # ["subagent", "audit-business"]
+        if len(parts) < 2:
+            continue
+        cli_name = parts[1].replace("-", ":", 1)  # "audit:business"
+        if cli_name not in REGISTRY:
+            # Not a violation if CLI templates haven't been registered yet
+            # (Agent templates can exist ahead of CLI registration)
+            pass
+
+    for md_file in sorted(templates_dir.glob("subagent-sync-*.md")):
+        stem = md_file.stem
+        parts = stem.split("-", 1)
+        if len(parts) < 2:
+            continue
+        cli_name = parts[1].replace("-", ":", 1)
+        if cli_name not in REGISTRY:
+            pass
+
+    return violations
+
+
+def _extract_cli_variables(template) -> set[str]:
+    """Extract variable placeholders from a CLI PromptTemplate."""
+    variables: set[str] = set()
+    # PromptTemplate uses {variable_name} syntax
+    text = template.system + "\n" + template.user
+    for match in re.finditer(r'\{(\w+)\}', text):
+        variables.add(match.group(1))
+    return variables
+
+
+def _extract_agent_variables(agent_path: Path) -> set[str]:
+    """Extract variable placeholders from an Agent template .md file."""
+    variables: set[str] = set()
+    try:
+        content = agent_path.read_text(encoding="utf-8")
+    except OSError:
+        return variables
+
+    # Agent templates use {variable_name} syntax
+    for match in re.finditer(r'\{(\w+)\}', content):
+        var = match.group(1)
+        # Filter out common false positives (JSON examples, etc.)
+        if var not in ("json", "else", "if", "endif", "status", "dimension", "detail", "fix"):
+            variables.add(var)
+
+    return variables
+
+
+def main() -> None:
+    """CLI entry point for parity validation."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="python -m core.prompt validate-parity",
+        description="Validate CLI/Agent template parity",
+    )
+    parser.add_argument("--preset", required=True, help="Preset name")
+    args = parser.parse_args()
+
+    violations = validate_parity(args.preset)
+
+    if violations:
+        print(f"❌ {len(violations)} parity violation(s) found:\n")
+        for v in violations:
+            print(f"  [{v.violation_type}] {v.template_name}: {v.detail}")
+        sys.exit(1)
+    else:
+        print(f"✅ All templates in sync for preset '{args.preset}'")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()