claude_formatter.py

"""CLAUDE.md formatter for Claude Memory integration.

This module generates CLAUDE.md files following the Claude Memory documentation format,
using the same distributed strategy as AGENTS.md compilation. It produces a parallel
output format specifically optimized for Claude's project memory system.
"""

import builtins
from dataclasses import dataclass, field
from pathlib import Path
from typing import Dict, List, Optional, Set  # noqa: F401, UP035

from ..primitives.models import Chatmode, Instruction, PrimitiveCollection
from ..version import get_version
from .constants import BUILD_ID_PLACEHOLDER
from .constitution import read_constitution
from .template_builder import build_attributed_instructions

# CRITICAL: Shadow Click commands to prevent namespace collision
set = builtins.set
list = builtins.list
dict = builtins.dict


# Header comment for CLAUDE.md files
CLAUDE_HEADER = "<!-- Generated by APM CLI -->"


@dataclass
class ClaudePlacement:
    """Result of CLAUDE.md placement analysis."""

    claude_path: Path
    instructions: builtins.list[Instruction]
    agents: builtins.list[Chatmode] = field(default_factory=list)
    dependencies: builtins.list[str] = field(default_factory=list)  # @import paths
    coverage_patterns: builtins.set[str] = field(default_factory=set)
    source_attribution: builtins.dict[str, str] = field(default_factory=dict)
    is_root: bool = False


@dataclass
class ClaudeCompilationResult:
    """Result of CLAUDE.md compilation."""

    success: bool
    placements: builtins.list[ClaudePlacement]
    content_map: builtins.dict[Path, str]  # claude_path -> content
    warnings: builtins.list[str] = field(default_factory=list)
    errors: builtins.list[str] = field(default_factory=list)
    stats: builtins.dict[str, float] = field(default_factory=dict)


class ClaudeFormatter:
    """Formatter for generating CLAUDE.md files from APM primitives.

    Generates CLAUDE.md files following Claude's Memory format with:
    - @import syntax for dependencies
    - Grouped project standards from instructions

    Note: Agents/workflows are handled separately as .github/agents/ files,
    not included in CLAUDE.md (same as AGENTS.md behavior).
    """

    def __init__(self, base_dir: str = "."):
        """Initialize the Claude formatter.

        Args:
            base_dir (str): Base directory for compilation.
        """
        try:
            self.base_dir = Path(base_dir).resolve()
        except (OSError, FileNotFoundError):
            self.base_dir = Path(base_dir).absolute()

        self.warnings: builtins.list[str] = []
        self.errors: builtins.list[str] = []

    def format_distributed(
        self,
        primitives: PrimitiveCollection,
        placement_map: builtins.dict[Path, builtins.list[Instruction]],
        config: dict | None = None,
    ) -> ClaudeCompilationResult:
        """Format primitives into distributed CLAUDE.md files.

        Args:
            primitives (PrimitiveCollection): Collection of primitives to compile.
            placement_map (Dict[Path, List[Instruction]]): Directory to instructions mapping.
            config (Optional[dict]): Configuration options.

        Returns:
            ClaudeCompilationResult: Result of the CLAUDE.md compilation.
        """
        self.warnings.clear()
        self.errors.clear()

        try:
            config = config or {}
            source_attribution = config.get("source_attribution", True)
            skip_instructions = config.get("skip_instructions", False)

            # Generate Claude placements from the placement map
            placements = self._generate_placements(
                placement_map, primitives, source_attribution=source_attribution
            )

            # Generate content for each placement.
            # When instructions are skipped (already in .claude/rules/), only
            # emit root CLAUDE.md if it has other content (constitution or
            # dependencies); subdirectory placements are omitted entirely.
            has_constitution = bool(read_constitution(self.base_dir))
            content_map = {}
            for placement in placements:
                if skip_instructions:
                    if not placement.is_root:
                        continue
                    if not placement.dependencies and not has_constitution:
                        continue
                content = self._generate_claude_content(
                    placement, primitives, skip_instructions=skip_instructions
                )
                content_map[placement.claude_path] = content

            # Filter placements to only those that produced content so stats
            # and downstream consumers see an accurate picture.
            emitted_placements = [p for p in placements if p.claude_path in content_map]

            # Compile statistics
            stats = self._compile_stats(emitted_placements, primitives)

            return ClaudeCompilationResult(
                success=len(self.errors) == 0,
                placements=emitted_placements,
                content_map=content_map,
                warnings=self.warnings.copy(),
                errors=self.errors.copy(),
                stats=stats,
            )

        except Exception as e:
            self.errors.append(f"CLAUDE.md formatting failed: {e!s}")
            return ClaudeCompilationResult(
                success=False,
                placements=[],
                content_map={},
                warnings=self.warnings.copy(),
                errors=self.errors.copy(),
                stats={},
            )

    def _generate_placements(
        self,
        placement_map: builtins.dict[Path, builtins.list[Instruction]],
        primitives: PrimitiveCollection,
        source_attribution: bool = True,
    ) -> builtins.list[ClaudePlacement]:
        """Generate CLAUDE.md file placements from the placement map.

        Args:
            placement_map (Dict[Path, List[Instruction]]): Directory to instructions mapping.
            primitives (PrimitiveCollection): Full primitive collection.
            source_attribution (bool): Whether to include source attribution.

        Returns:
            List[ClaudePlacement]: List of placement results.
        """
        placements = []

        # Handle empty placement map with constitution or dependencies
        if not placement_map:
            constitution = read_constitution(self.base_dir)
            dependencies = self._collect_dependencies()
            if constitution or dependencies:
                root_path = self.base_dir / "CLAUDE.md"
                placement = ClaudePlacement(
                    claude_path=root_path,
                    instructions=[],
                    agents=list(primitives.chatmodes),
                    dependencies=dependencies,
                    coverage_patterns=set(),
                    source_attribution={},
                    is_root=True,
                )
                placements.append(placement)
        else:
            # Determine which directories get which agents (chatmodes)
            # Root directory gets all agents
            root_agents = list(primitives.chatmodes)

            for dir_path, instructions in placement_map.items():
                claude_path = dir_path / "CLAUDE.md"

                # Build source attribution map if enabled
                source_map = {}
                if source_attribution:
                    for instruction in instructions:
                        source_info = getattr(instruction, "source", "local")
                        source_map[str(instruction.file_path)] = source_info

                # Extract coverage patterns
                patterns = set()
                for instruction in instructions:
                    if instruction.apply_to:
                        patterns.add(instruction.apply_to)

                # Root directory gets agents and dependencies
                is_root = dir_path == self.base_dir

                placement = ClaudePlacement(
                    claude_path=claude_path,
                    instructions=instructions,
                    agents=root_agents if is_root else [],
                    dependencies=self._collect_dependencies() if is_root else [],
                    coverage_patterns=patterns,
                    source_attribution=source_map,
                    is_root=is_root,
                )

                placements.append(placement)

        return placements

    def _collect_dependencies(self) -> builtins.list[str]:
        """Collect @import paths for apm_modules dependencies.

        Returns:
            List[str]: List of @import paths for dependencies.
        """
        dependencies = []
        apm_modules_dir = self.base_dir / "apm_modules"

        if not apm_modules_dir.is_dir():
            return dependencies

        # Scan for CLAUDE.md files in apm_modules
        # Structure: apm_modules/{owner}/{package}/CLAUDE.md
        for owner_dir in apm_modules_dir.iterdir():
            if not owner_dir.is_dir() or owner_dir.name.startswith("."):
                continue

            for package_dir in owner_dir.iterdir():
                if not package_dir.is_dir() or package_dir.name.startswith("."):
                    continue

                claude_md_path = package_dir / "CLAUDE.md"
                if not claude_md_path.is_file():
                    continue

                # Build the @import path
                import_path = f"@apm_modules/{owner_dir.name}/{package_dir.name}/CLAUDE.md"
                dependencies.append(import_path)

        return sorted(dependencies)

    def _generate_claude_content(
        self,
        placement: ClaudePlacement,
        primitives: PrimitiveCollection,
        *,
        skip_instructions: bool = False,
    ) -> str:
        """Generate CLAUDE.md content for a specific placement.

        Args:
            placement (ClaudePlacement): Placement result with instructions.
            primitives (PrimitiveCollection): Full primitive collection.
            skip_instructions (bool): If True, omit the Project Standards section.

        Returns:
            str: Generated CLAUDE.md content.
        """
        sections = []

        # Header
        sections.append("# CLAUDE.md")
        sections.append(CLAUDE_HEADER)
        sections.append(BUILD_ID_PLACEHOLDER)
        sections.append(f"<!-- APM Version: {get_version()} -->")
        sections.append("")

        # Dependencies section (only for root CLAUDE.md)
        if placement.dependencies:
            sections.append("# Dependencies")
            for dep in placement.dependencies:
                sections.append(dep)
            sections.append("")

        # Constitution section (only for root CLAUDE.md)
        if placement.is_root:
            constitution = read_constitution(self.base_dir)
            if constitution:
                sections.append("# Constitution")
                sections.append("")
                sections.append(constitution.strip())
                sections.append("")

        # Project Standards section (grouped by pattern).
        # Skipped when instructions are already deployed to .claude/rules/ by
        # `apm install`, since Claude Code reads both locations and would see
        # duplicate content.
        if placement.instructions and not skip_instructions:
            sections.append("# Project Standards")
            sections.append("")

            sections.extend(
                build_attributed_instructions(
                    placement.instructions,
                    placement.source_attribution,
                    self.base_dir,
                )
            )

        # Agents/workflows go to .github/agents/ as separate files, not here.

        # Footer
        sections.append("---")
        sections.append("*This file was generated by APM CLI. Do not edit manually.*")
        sections.append("*To regenerate: `apm compile`*")
        sections.append("")

        return "\n".join(sections)

    def _compile_stats(
        self, placements: builtins.list[ClaudePlacement], primitives: PrimitiveCollection
    ) -> builtins.dict[str, float]:
        """Compile statistics about the CLAUDE.md compilation.

        Args:
            placements (List[ClaudePlacement]): Generated placements.
            primitives (PrimitiveCollection): Full primitive collection.

        Returns:
            Dict[str, float]: Compilation statistics.
        """
        total_instructions = sum(len(p.instructions) for p in placements)
        total_patterns = sum(len(p.coverage_patterns) for p in placements)
        total_deps = sum(len(p.dependencies) for p in placements)

        return {
            "claude_files_generated": len(placements),
            "total_instructions_placed": total_instructions,
            "total_patterns_covered": total_patterns,
            "total_dependencies": total_deps,
            "primitives_found": primitives.count(),
        }


def format_claude_md(
    primitives: PrimitiveCollection,
    placement_map: builtins.dict[Path, builtins.list[Instruction]],
    base_dir: str = ".",
    config: dict | None = None,
) -> ClaudeCompilationResult:
    """Convenience function to format CLAUDE.md files.

    Args:
        primitives (PrimitiveCollection): Collection of primitives.
        placement_map (Dict[Path, List[Instruction]]): Directory to instructions mapping.
        base_dir (str): Base directory for compilation.
        config (Optional[dict]): Configuration options.

    Returns:
        ClaudeCompilationResult: Result of the CLAUDE.md compilation.
    """
    formatter = ClaudeFormatter(base_dir)
    return formatter.format_distributed(primitives, placement_map, config)