core-runtime 0.1.1__py3-none-any.whl

body/services/cim/baselines.py

@@ -0,0 +1,102 @@
+# src/body/services/cim/baselines.py
+
+"""
+CIM Baselines - Named anchors for comparison.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from body.services.file_service import FileService
+from shared.logger import getLogger
+
+from .models import BaselineRegistry, CensusBaseline
+
+
+logger = getLogger(__name__)
+
+
+# ID: 24bc667c-43a4-48eb-ad47-53a4a82231b3
+class BaselineManager:
+    """
+    Manages named baselines for census comparison.
+
+    Baselines are named references to specific snapshots.
+    """
+
+    def __init__(
+        self,
+        registry_path: Path,
+        file_handler: FileService,
+        repo_root: Path,
+    ):
+        """Initialize baseline manager."""
+        self.registry_path = registry_path
+        self.file_handler = file_handler
+        self.repo_root = repo_root
+        self.file_handler.ensure_dir(
+            str(self.registry_path.parent.relative_to(self.repo_root))
+        )
+
+        if self.registry_path.exists():
+            content = self.registry_path.read_text(encoding="utf-8")
+            self.registry = BaselineRegistry.model_validate_json(content)
+        else:
+            self.registry = BaselineRegistry()
+
+    def _save(self):
+        """Persist registry to disk."""
+        rel_path = str(self.registry_path.relative_to(self.repo_root))
+        self.file_handler.write_file(rel_path, self.registry.model_dump_json(indent=2))
+
+    # ID: cdc3462e-f8b5-4ac6-9dcb-53f15de55528
+    def set_baseline(
+        self, name: str, snapshot_file: str, git_commit: str | None = None
+    ) -> CensusBaseline:
+        """
+        Create or update a named baseline.
+
+        Args:
+            name: Baseline name (e.g., "v2.0.0", "pre-refactor")
+            snapshot_file: Snapshot filename to reference
+            git_commit: Git commit hash (optional)
+
+        Returns:
+            Created baseline
+        """
+        baseline = CensusBaseline(
+            name=name,
+            snapshot_file=snapshot_file,
+            git_commit=git_commit,
+            created_at=datetime.utcnow(),
+        )
+
+        self.registry.baselines[name] = baseline
+        self._save()
+
+        logger.info("Set baseline '%s' → %s", name, snapshot_file)
+        return baseline
+
+    # ID: e7891b2c-1818-4ddf-8955-c1805ad1e681
+    def get_baseline(self, name: str) -> CensusBaseline | None:
+        """Get baseline by name."""
+        return self.registry.baselines.get(name)
+
+    # ID: 84268cb9-a2d3-4fbc-a93f-fa327493fafd
+    def list_baselines(self) -> list[CensusBaseline]:
+        """List all baselines in chronological order."""
+        return sorted(
+            self.registry.baselines.values(), key=lambda b: b.created_at, reverse=True
+        )
+
+    # ID: 7ebee765-dc76-4c00-b776-969fd0b86ade
+    def delete_baseline(self, name: str) -> bool:
+        """Delete a baseline by name."""
+        if name in self.registry.baselines:
+            del self.registry.baselines[name]
+            self._save()
+            logger.info("Deleted baseline '%s'", name)
+            return True
+        return False

body/services/cim/census_service.py

@@ -0,0 +1,190 @@
+# src/body/services/cim/census_service.py
+
+"""
+Census Service - Orchestrates CIM-0 repository census.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections import defaultdict
+from pathlib import Path
+
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+from .models import CensusSummary, MutationHotspot, RepoCensus, RepoCensusMetadata
+from .scanners import (
+    extract_cli_entrypoints,
+    scan_architectural_signals,
+    scan_execution_surfaces,
+    scan_git_metadata,
+    scan_mutation_surfaces,
+    scan_tree_stats,
+    should_skip_path,
+)
+
+
+logger = getLogger(__name__)
+
+_CFG = load_operational_config().misc
+
+
+# ID: 0b9a7f04-a0b2-438e-89d1-c0690c8fe2a4
+class CensusService:
+    """
+    Read-only census orchestrator for CIM-0.
+
+    Never mutates the target repository.
+    Produces deterministic RepoCensus artifact.
+    """
+
+    # ID: 062ee433-9e2b-4498-b8d2-fcc5b64150a7
+    def run_census(self, repo_path: Path) -> RepoCensus:
+        """
+        Execute full CIM-0 census on target repository.
+
+        Returns:
+            RepoCensus artifact with all collected data and actionable intelligence
+        """
+        logger.info("Starting CIM-0 census: %s", repo_path)
+
+        metadata = RepoCensusMetadata(
+            run_id=str(uuid.uuid4()),
+            core_version="2.0.0",
+        )
+
+        repo_info = scan_git_metadata(repo_path)
+        tree_stats = scan_tree_stats(repo_path)
+        signals = scan_architectural_signals(repo_path)
+        exec_surfaces, exec_errors = scan_execution_surfaces(repo_path)
+        mut_surfaces, mut_errors = scan_mutation_surfaces(repo_path)
+
+        all_errors = exec_errors + mut_errors
+        all_errors.sort(key=lambda e: e.path)
+
+        summary = self._generate_summary(
+            repo_path, exec_surfaces, mut_surfaces, all_errors
+        )
+
+        census = RepoCensus(
+            metadata=metadata,
+            repo=repo_info,
+            tree=tree_stats,
+            signals=signals,
+            summary=summary,
+            execution_surfaces=exec_surfaces,
+            mutation_surfaces=mut_surfaces,
+            errors=all_errors,
+        )
+
+        logger.info(
+            "Census complete: %d files, %d execution surfaces, %d mutation surfaces (%d allowlisted), %d errors",
+            tree_stats.total_files,
+            len(exec_surfaces),
+            len(mut_surfaces),
+            summary.allowlisted_surfaces_count,
+            len(all_errors),
+        )
+
+        return census
+
+    def _generate_summary(
+        self, repo_path: Path, exec_surfaces, mut_surfaces, errors
+    ) -> CensusSummary:
+        """Generate aggregated statistics with actionable intelligence."""
+        by_type: dict[str, int] = defaultdict(int)
+        by_operation: dict[str, int] = defaultdict(int)
+        by_lane: dict[str, int] = defaultdict(int)
+
+        # Write zone classification
+        write_ephemeral = 0
+        write_production = 0
+        write_prohibited = 0
+        write_unknown = 0
+
+        allowlisted_count = 0
+
+        for surface in mut_surfaces:
+            by_type[surface.type] += 1
+            by_operation[surface.operation] += 1
+
+            if surface.lane:
+                by_lane[surface.lane] += 1
+
+            if surface.allowlisted:
+                allowlisted_count += 1
+
+            # Classify writes by zone
+            if surface.operation == "write" and surface.write_zone:
+                if surface.write_zone == "ephemeral":
+                    write_ephemeral += 1
+                elif surface.write_zone == "production":
+                    write_production += 1
+                elif surface.write_zone == "prohibited":
+                    write_prohibited += 1
+                elif surface.write_zone == "unknown":
+                    write_unknown += 1
+
+        hotspots = self._find_mutation_hotspots(
+            mut_surfaces, limit=_CFG.census_hotspot_limit
+        )
+        cli_entrypoints = extract_cli_entrypoints(repo_path)
+
+        path_classes: dict[str, int] = defaultdict(int)
+        for py_file in repo_path.rglob("*.py"):
+            if should_skip_path(py_file, repo_path):
+                continue
+            rel_path = py_file.relative_to(repo_path)
+            if len(rel_path.parts) > 0:
+                prefix = rel_path.parts[0]
+                path_classes[prefix] += 1
+
+        return CensusSummary(
+            execution_surfaces_count=len(exec_surfaces),
+            mutation_surfaces_count_total=len(mut_surfaces),
+            write_ephemeral_count=write_ephemeral,
+            write_production_count=write_production,
+            write_prohibited_zone_count=write_prohibited,
+            write_unknown_count=write_unknown,
+            mutation_surfaces_by_type=dict(sorted(by_type.items())),
+            mutation_surfaces_by_operation=dict(sorted(by_operation.items())),
+            top_mutation_files=hotspots,
+            allowlisted_surfaces_count=allowlisted_count,
+            mutation_surfaces_by_lane=dict(sorted(by_lane.items())),
+            cli_entrypoints=cli_entrypoints,
+            errors_count=len(errors),
+            path_class_counts=dict(sorted(path_classes.items())),
+        )
+
+    def _find_mutation_hotspots(
+        self, surfaces: list, limit: int = _CFG.census_hotspot_limit
+    ) -> list[MutationHotspot]:
+        """Rank files by mutation surface density."""
+        by_file: dict[str, dict] = defaultdict(
+            lambda: {
+                "count": 0,
+                "types": defaultdict(int),
+                "operations": defaultdict(int),
+            }
+        )
+
+        for s in surfaces:
+            by_file[s.path]["count"] += 1
+            by_file[s.path]["types"][s.type] += 1
+            by_file[s.path]["operations"][s.operation] += 1
+
+        hotspots = []
+        for path, data in by_file.items():
+            dominant_type = max(data["types"].items(), key=lambda x: x[1])[0]
+            dominant_op = max(data["operations"].items(), key=lambda x: x[1])[0]
+            hotspots.append(
+                MutationHotspot(
+                    path=path,
+                    mutation_count=data["count"],
+                    dominant_type=dominant_type,
+                    dominant_operation=dominant_op,
+                )
+            )
+
+        return sorted(hotspots, key=lambda x: x.mutation_count, reverse=True)[:limit]

body/services/cim/cim_constants.py

@@ -0,0 +1,116 @@
+# src/body/services/cim/cim_constants.py
+"""CIM-0 Census Constants.
+
+All classification sets and maps used across CIM scanners and path utilities.
+Pure data — no logic, no imports.
+"""
+
+from __future__ import annotations
+
+
+# Directories to skip entirely during filesystem walks
+SKIP_DIRS = {
+    ".git",
+    "__pycache__",
+    "node_modules",
+    ".venv",
+    "venv",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    "var",
+    "work",
+    "backups",
+    ".tox",
+    "dist",
+    "build",
+    "scripts",
+    ".eggs",
+}
+
+DEPENDENCY_FILES = {"pyproject.toml", "requirements.txt", "setup.py", "Pipfile"}
+
+# Write zone classification
+EPHEMERAL_WRITE_ZONES = {
+    "var",
+    "work",
+    ".cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    ".pytest_cache",
+    "tmp",
+    "temp",
+    "reports",
+    "logs",
+    "backups",
+}
+
+PRODUCTION_WRITE_ZONES = {
+    "src",  # Production code
+    "tests",  # Test suite
+    "sql",  # Schema migrations
+    "docs",  # Documentation
+    ".intent",  # Constitution (with prohibited subzones)
+}
+
+PROHIBITED_WRITE_ZONES = {".intent/constitution", ".intent/META"}
+
+# Lane classification
+LANE_MAP = {
+    "body": ["body/"],
+    "mind": ["mind/"],
+    "will": ["will/"],
+    "shared": ["shared/"],
+    "features": ["features/"],
+    "tests": ["tests/"],
+}
+
+# Allowlisted mutation surfaces (known-safe)
+ALLOWLISTED_PATTERNS = [
+    "shared/infrastructure/storage/file_handler.py",
+    "shared/logger.py",
+    "shared/infrastructure/clients/",
+    "shared/infrastructure/database/",
+    "body/governance/intent_guard.py",
+]
+
+# Temp operation detection
+TEMP_FUNCTION_NAMES = {
+    "mkdtemp",
+    "mkstemp",
+    "TemporaryDirectory",
+    "TemporaryFile",
+    "NamedTemporaryFile",
+    "SpooledTemporaryFile",
+}
+
+TEMP_FIXTURE_NAMES = {
+    "tmp_path",
+    "tmpdir",
+    "tmp_path_factory",
+    "tmpdir_factory",
+}
+
+# AST mutation surface classification
+MUTATION_IMPORTS = {
+    "subprocess": ("subprocess", "execute"),
+    "requests": ("network", "connect"),
+    "httpx": ("network", "connect"),
+    "socket": ("network", "connect"),
+    "urllib": ("network", "connect"),
+    "sqlalchemy": ("database", "connect"),
+    "psycopg2": ("database", "connect"),
+    "sqlite3": ("database", "connect"),
+}
+
+FILESYSTEM_READ_OPS = {"read_text", "read_bytes", "open"}
+
+FILESYSTEM_WRITE_OPS = {
+    "write",
+    "write_text",
+    "write_bytes",
+    "mkdir",
+    "rmdir",
+    "unlink",
+    "remove",
+}

body/services/cim/cim_path_utils.py

@@ -0,0 +1,123 @@
+# src/body/services/cim/cim_path_utils.py
+"""CIM-0 Path Classification Utilities.
+
+Pure, deterministic functions for path and AST node classification.
+No I/O, no side effects.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from .cim_constants import (
+    ALLOWLISTED_PATTERNS,
+    EPHEMERAL_WRITE_ZONES,
+    LANE_MAP,
+    PRODUCTION_WRITE_ZONES,
+    PROHIBITED_WRITE_ZONES,
+    SKIP_DIRS,
+    TEMP_FIXTURE_NAMES,
+    TEMP_FUNCTION_NAMES,
+)
+
+
+# ID: 19e21116-67e8-43fc-9f19-cd4691ee37b0
+def should_skip_path(path: Path, repo_root: Path) -> bool:
+    """Determine if a path should be skipped during scanning.
+
+    Skip rules:
+    - All hidden directories EXCEPT .intent
+    - Known junk directories (var/, work/, backups/, etc.)
+    """
+    try:
+        rel_path = path.relative_to(repo_root)
+    except ValueError:
+        return True
+
+    for part in rel_path.parts:
+        if part in SKIP_DIRS:
+            return True
+        if part.startswith(".") and part != ".intent":
+            return True
+
+    return False
+
+
+# ID: 662ece26-5c53-4cef-9ab2-6fcd392061e5
+def classify_write_zone(path: str) -> str:
+    """Classify write operation by target zone.
+
+    Returns:
+        "ephemeral" | "production" | "prohibited" | "unknown"
+    """
+    parts = Path(path).parts
+    if not parts:
+        return "unknown"
+
+    first = parts[0]
+
+    if first in EPHEMERAL_WRITE_ZONES:
+        return "ephemeral"
+    if first in PRODUCTION_WRITE_ZONES:
+        return "production"
+
+    full_path = "/".join(parts)
+    for prohibited in PROHIBITED_WRITE_ZONES:
+        if full_path.startswith(prohibited):
+            return "prohibited"
+
+    return "unknown"
+
+
+# ID: c796fef3-36eb-4e39-a38e-b0758d97e4be
+def classify_lane(path: str) -> str:
+    """Map file path to architectural lane.
+
+    Returns:
+        "body" | "mind" | "will" | "shared" | "features" | "tests" | "other"
+    """
+    for lane, prefixes in LANE_MAP.items():
+        for prefix in prefixes:
+            if path.startswith(prefix):
+                return lane
+
+    if path.startswith("src/"):
+        parts = Path(path).parts
+        if len(parts) > 1 and parts[1] in LANE_MAP:
+            return parts[1]
+
+    return "other"
+
+
+# ID: 7e904c77-2189-4e75-bb9a-f472a13d77ee
+def is_allowlisted(path: str) -> bool:
+    """Check if mutation surface is in the known-safe allowlist."""
+    return any(pattern in path for pattern in ALLOWLISTED_PATTERNS)
+
+
+# ID: a582546d-384a-41ff-92f8-3355212695f4
+def is_temp_write_operation(node: ast.Call, file_content: str) -> bool:
+    """Detect if a write operation targets a temporary location.
+
+    Strategies:
+    1. Function name indicates temp (mkdtemp, TemporaryFile, etc.)
+    2. First argument is a /tmp/ path literal
+    3. Source file uses pytest temp fixtures
+    """
+    func_name = None
+    if isinstance(node.func, ast.Name):
+        func_name = node.func.id
+    elif isinstance(node.func, ast.Attribute):
+        func_name = node.func.attr
+
+    if func_name in TEMP_FUNCTION_NAMES:
+        return True
+
+    if node.args:
+        first_arg = node.args[0]
+        if isinstance(first_arg, ast.Constant) and isinstance(first_arg.value, str):
+            if first_arg.value.startswith(("/tmp/", "/var/tmp/", "tmp/", "temp/")):
+                return True
+
+    return any(fixture in file_content for fixture in TEMP_FIXTURE_NAMES)

body/services/cim/diff.py

@@ -0,0 +1,152 @@
+# src/body/services/cim/diff.py
+
+"""
+CIM Diff Engine - Compare census runs.
+"""
+
+from __future__ import annotations
+
+from shared.logger import getLogger
+
+from .models import CensusDelta, CensusDiff, HotspotChange, RepoCensus
+
+
+logger = getLogger(__name__)
+
+
+# ID: 9e531ca2-1356-43dd-b28a-88e9c7a9bffb
+class DiffEngine:
+    """Generate diffs between census runs."""
+
+    # ID: 9cc0cac7-7efc-4317-b28c-84f24930cfaa
+    def compute_diff(
+        self,
+        baseline: RepoCensus,
+        current: RepoCensus,
+        baseline_name: str | None = None,
+    ) -> CensusDiff:
+        """
+        Compute diff: current - baseline.
+
+        Positive deltas = increase
+        Negative deltas = decrease
+        """
+        diff = CensusDiff(
+            baseline_name=baseline_name,
+            baseline_commit=baseline.repo.git_commit,
+            current_commit=current.repo.git_commit,
+            execution_surfaces=self._delta(
+                baseline.summary.execution_surfaces_count,
+                current.summary.execution_surfaces_count,
+            ),
+            mutation_surfaces_total=self._delta(
+                baseline.summary.mutation_surfaces_count_total,
+                current.summary.mutation_surfaces_count_total,
+            ),
+            write_ephemeral=self._delta(
+                baseline.summary.write_ephemeral_count,
+                current.summary.write_ephemeral_count,
+            ),
+            write_production=self._delta(
+                baseline.summary.write_production_count,
+                current.summary.write_production_count,
+            ),
+            write_prohibited_zone=self._delta(
+                baseline.summary.write_prohibited_zone_count,
+                current.summary.write_prohibited_zone_count,
+            ),
+        )
+
+        # By type
+        all_types = set(baseline.summary.mutation_surfaces_by_type.keys()) | set(
+            current.summary.mutation_surfaces_by_type.keys()
+        )
+        for mut_type in all_types:
+            old_val = baseline.summary.mutation_surfaces_by_type.get(mut_type, 0)
+            new_val = current.summary.mutation_surfaces_by_type.get(mut_type, 0)
+            diff.by_type[mut_type] = self._delta(old_val, new_val)
+
+        # By lane
+        all_lanes = set(baseline.summary.mutation_surfaces_by_lane.keys()) | set(
+            current.summary.mutation_surfaces_by_lane.keys()
+        )
+        for lane in all_lanes:
+            old_val = baseline.summary.mutation_surfaces_by_lane.get(lane, 0)
+            new_val = current.summary.mutation_surfaces_by_lane.get(lane, 0)
+            diff.by_lane[lane] = self._delta(old_val, new_val)
+
+        # Hotspot changes
+        self._compute_hotspot_changes(baseline, current, diff)
+
+        # Critical: new prohibited writes
+        diff.new_prohibited_writes = max(
+            0,
+            current.summary.write_prohibited_zone_count
+            - baseline.summary.write_prohibited_zone_count,
+        )
+
+        return diff
+
+    def _delta(self, old_value: int, new_value: int) -> CensusDelta:
+        """Compute delta with percent change."""
+        delta = new_value - old_value
+        percent = None
+        if old_value > 0:
+            percent = (delta / old_value) * 100.0
+
+        return CensusDelta(
+            old_value=old_value,
+            new_value=new_value,
+            delta=delta,
+            percent_change=percent,
+        )
+
+    def _compute_hotspot_changes(
+        self, baseline: RepoCensus, current: RepoCensus, diff: CensusDiff
+    ):
+        """Detect hotspot additions/removals/changes."""
+        # Build hotspot maps
+        baseline_hotspots = {h.path: h for h in baseline.summary.top_mutation_files}
+        current_hotspots = {h.path: h for h in current.summary.top_mutation_files}
+
+        # Added hotspots
+        for path in current_hotspots.keys() - baseline_hotspots.keys():
+            diff.hotspots_added.append(
+                HotspotChange(
+                    path=path,
+                    old_count=None,
+                    new_count=current_hotspots[path].mutation_count,
+                    delta=current_hotspots[path].mutation_count,
+                    status="added",
+                )
+            )
+
+        # Removed hotspots
+        for path in baseline_hotspots.keys() - current_hotspots.keys():
+            diff.hotspots_removed.append(
+                HotspotChange(
+                    path=path,
+                    old_count=baseline_hotspots[path].mutation_count,
+                    new_count=None,
+                    delta=-baseline_hotspots[path].mutation_count,
+                    status="removed",
+                )
+            )
+
+        # Changed hotspots
+        for path in baseline_hotspots.keys() & current_hotspots.keys():
+            old_count = baseline_hotspots[path].mutation_count
+            new_count = current_hotspots[path].mutation_count
+            delta = new_count - old_count
+
+            if delta != 0:
+                status = "increased" if delta > 0 else "decreased"
+                diff.hotspots_changed.append(
+                    HotspotChange(
+                        path=path,
+                        old_count=old_count,
+                        new_count=new_count,
+                        delta=delta,
+                        status=status,
+                    )
+                )