codevigil 0.1.0__py3-none-any.whl

codevigil/privacy.py

@@ -0,0 +1,191 @@
+"""Network-egress import gate.
+
+Installs an ``importlib`` meta-path finder that refuses to load any banned
+module when the *direct* importer lives inside the ``codevigil`` package. The
+hook is active in every execution mode and is the runtime half of the privacy
+guarantee documented in ``docs/design.md`` §Privacy Enforcement.
+
+The hook is deliberately scoped to *direct* imports from codevigil: if codevigil
+imports a permitted stdlib module (e.g. ``json``) which in turn imports a
+banned module transitively, the transitive import is allowed — the importer
+frame at the point the banned module is resolved is the permitted stdlib
+module, not codevigil.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from importlib.abc import MetaPathFinder
+from importlib.machinery import ModuleSpec
+from types import FrameType
+
+# Exact fully-qualified module names that are blocked.
+_BANNED_EXACT: frozenset[str] = frozenset(
+    {
+        "socket",
+        "ssl",
+        "http",
+        "http.client",
+        "http.server",
+        "urllib",
+        "urllib.request",
+        "urllib.parse",
+        "urllib.error",
+        "urllib3",
+        "httpx",
+        "requests",
+        "aiohttp",
+        "ftplib",
+        "smtplib",
+        "poplib",
+        "imaplib",
+        "nntplib",
+        "telnetlib",
+        "xmlrpc",
+        "xmlrpc.client",
+        "xmlrpc.server",
+        "subprocess",
+        "pty",
+        "multiprocessing.popen_fork",
+        "multiprocessing.popen_forkserver",
+        "multiprocessing.popen_spawn_posix",
+        "multiprocessing.popen_spawn_win32",
+    }
+)
+
+# Top-level package names whose submodules are all blocked.
+_BANNED_ROOTS: frozenset[str] = frozenset(
+    {
+        "socket",
+        "ssl",
+        "urllib",
+        "urllib3",
+        "httpx",
+        "requests",
+        "aiohttp",
+        "ftplib",
+        "smtplib",
+        "poplib",
+        "imaplib",
+        "nntplib",
+        "telnetlib",
+        "xmlrpc",
+        "subprocess",
+        "pty",
+    }
+)
+
+_CODEVIGIL_ROOT: str = "codevigil"
+
+# Frame modules we skip when locating the direct caller of a banned import.
+# These are all Python-internal import-machinery frames.
+_SKIPPED_CALLER_PREFIXES: tuple[str, ...] = (
+    "importlib",
+    "_frozen_importlib",
+    "_frozen_importlib_external",
+)
+
+
+class PrivacyViolationError(ImportError):
+    """Raised when a codevigil module attempts to import a banned module.
+
+    Subclasses ``ImportError`` so ``find_spec`` can raise it and have the
+    traceback blame the offending import statement, and so test assertions
+    that use ``pytest.raises(ImportError)`` continue to work.
+    """
+
+
+def _is_banned(fullname: str) -> bool:
+    if fullname in _BANNED_EXACT:
+        return True
+    root = fullname.split(".", 1)[0]
+    return root in _BANNED_ROOTS
+
+
+def _direct_caller_module(start: FrameType | None) -> str | None:
+    """Return the name of the first non-import-machinery frame's module.
+
+    Walks ``frame.f_back`` until it finds a frame whose ``__name__`` does
+    not belong to the import-machinery prefixes. Returns ``None`` if no such
+    frame exists (e.g. if called at interpreter shutdown).
+    """
+
+    frame = start
+    while frame is not None:
+        raw = frame.f_globals.get("__name__", "")
+        module_name = raw if isinstance(raw, str) else ""
+        if not any(
+            module_name == prefix or module_name.startswith(prefix + ".")
+            for prefix in _SKIPPED_CALLER_PREFIXES
+        ):
+            return module_name
+        frame = frame.f_back
+    return None
+
+
+def _caller_is_codevigil(module_name: str | None) -> bool:
+    if module_name is None:
+        return False
+    return module_name == _CODEVIGIL_ROOT or module_name.startswith(_CODEVIGIL_ROOT + ".")
+
+
+class PrivacyImportHook(MetaPathFinder):
+    """Meta-path finder that blocks banned imports from inside codevigil."""
+
+    def find_spec(
+        self,
+        fullname: str,
+        path: Sequence[str] | None,
+        target: object | None = None,
+    ) -> ModuleSpec | None:
+        if not _is_banned(fullname):
+            return None
+        caller = _direct_caller_module(sys._getframe(1))
+        if _caller_is_codevigil(caller):
+            raise PrivacyViolationError(
+                f"codevigil module {caller!r} attempted to import banned module "
+                f"{fullname!r}; network and subprocess modules are disallowed "
+                "by the privacy gate (see docs/design.md §Privacy Enforcement)."
+            )
+        return None
+
+
+_HOOK_SINGLETON: PrivacyImportHook | None = None
+
+
+def install() -> PrivacyImportHook:
+    """Install the privacy import hook.
+
+    Idempotent: repeated calls return the same singleton instance without
+    registering the hook more than once.
+    """
+
+    global _HOOK_SINGLETON
+    if _HOOK_SINGLETON is None:
+        _HOOK_SINGLETON = PrivacyImportHook()
+        sys.meta_path.insert(0, _HOOK_SINGLETON)
+    elif _HOOK_SINGLETON not in sys.meta_path:
+        sys.meta_path.insert(0, _HOOK_SINGLETON)
+    return _HOOK_SINGLETON
+
+
+def uninstall() -> None:
+    """Remove the privacy import hook if installed.
+
+    Exposed for tests that need to observe the uninstalled baseline. Never
+    called by the runtime.
+    """
+
+    global _HOOK_SINGLETON
+    if _HOOK_SINGLETON is not None and _HOOK_SINGLETON in sys.meta_path:
+        sys.meta_path.remove(_HOOK_SINGLETON)
+    _HOOK_SINGLETON = None
+
+
+__all__ = [
+    "PrivacyImportHook",
+    "PrivacyViolationError",
+    "install",
+    "uninstall",
+]

codevigil/projects.py

@@ -0,0 +1,132 @@
+"""Project hash → friendly name resolution.
+
+Claude Code stores session files under
+``~/.claude/projects/<project-hash>/sessions/<session-id>.jsonl``. The hash is
+opaque to humans, so the aggregator threads every session through a
+:class:`ProjectRegistry` that maps the hash to a display name using three
+sources, highest precedence first (per ``docs/design.md`` §Project Name
+Resolution):
+
+1. A user-maintained TOML file at ``~/.config/codevigil/projects.toml`` with
+   ``{hash = "name"}`` pairs at the top level. This is the manual override
+   users reach for when the auto-resolved name is wrong or missing.
+2. The first ``cwd`` field observed inside a SYSTEM event payload for that
+   hash, stripped to the last path component via ``Path(cwd).name``. This is
+   what `claude` itself records when a user runs it from a project directory.
+3. The raw hash prefix (``hash[:8]``) as the always-available fallback. An
+   unresolved hash is *expected state*, not an error, so this branch never
+   emits a WARN.
+
+The registry is process-local: it is constructed once by the aggregator and
+mutated only via :meth:`observe_system_event`.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from codevigil.errors import CodevigilError, ErrorLevel, ErrorSource, record
+from codevigil.types import Event, EventKind, safe_get
+
+_DEFAULT_TOML_PATH: Path = Path("~/.config/codevigil/projects.toml").expanduser()
+
+
+class ProjectRegistry:
+    """Resolve Claude Code project hashes to display names.
+
+    The constructor loads the optional TOML override file synchronously; a
+    malformed or unreadable file is reported via the error channel as a WARN
+    and the registry continues with an empty user map (the cwd and hash
+    fallbacks still work). The aggregator instantiates one registry per
+    process and shares it across every session.
+    """
+
+    def __init__(self, toml_path: Path | None = None) -> None:
+        self._toml_path: Path = toml_path if toml_path is not None else _DEFAULT_TOML_PATH
+        self._user_overrides: dict[str, str] = {}
+        self._cwd_cache: dict[str, str] = {}
+        self._load_user_overrides()
+
+    # ------------------------------------------------------------------ loading
+
+    def _load_user_overrides(self) -> None:
+        path = self._toml_path
+        if not path.exists():
+            return
+        try:
+            with path.open("rb") as handle:
+                data: dict[str, Any] = tomllib.load(handle)
+        except (OSError, tomllib.TOMLDecodeError) as exc:
+            record(
+                CodevigilError(
+                    level=ErrorLevel.WARN,
+                    source=ErrorSource.AGGREGATOR,
+                    code="projects.toml_load_failed",
+                    message=(
+                        f"failed to load projects override file {str(path)!r}: {exc}; "
+                        f"continuing with empty user map"
+                    ),
+                    context={"path": str(path)},
+                )
+            )
+            return
+        for key, value in data.items():
+            if isinstance(key, str) and isinstance(value, str) and value:
+                self._user_overrides[key] = value
+            else:
+                record(
+                    CodevigilError(
+                        level=ErrorLevel.WARN,
+                        source=ErrorSource.AGGREGATOR,
+                        code="projects.toml_bad_entry",
+                        message=(f"ignoring non-string entry {key!r} in projects override file"),
+                        context={"path": str(self._toml_path), "key": str(key)},
+                    )
+                )
+
+    # ----------------------------------------------------------------- ingestion
+
+    def observe_system_event(self, project_hash: str, event: Event) -> None:
+        """Cache the first ``cwd`` value seen on a SYSTEM event for a hash.
+
+        The aggregator forwards every SYSTEM event here. We keep the *first*
+        observation rather than the latest because the resolution policy
+        wants stable display names — a session that ``cd``s mid-run should
+        still show up under the directory it started in.
+        """
+
+        if event.kind is not EventKind.SYSTEM:
+            return
+        if project_hash in self._cwd_cache:
+            return
+        cwd = safe_get(
+            event.payload,
+            "cwd",
+            default=None,
+            expected=str,
+            source=ErrorSource.AGGREGATOR,
+            event_kind="system",
+        )
+        if not isinstance(cwd, str) or not cwd:
+            return
+        name = Path(cwd).name
+        if name:
+            self._cwd_cache[project_hash] = name
+
+    # ----------------------------------------------------------------- resolution
+
+    def resolve(self, project_hash: str) -> str:
+        """Return the highest-precedence display name available for a hash."""
+
+        override = self._user_overrides.get(project_hash)
+        if override:
+            return override
+        cwd_name = self._cwd_cache.get(project_hash)
+        if cwd_name:
+            return cwd_name
+        return project_hash[:8] if project_hash else ""
+
+
+__all__ = ["ProjectRegistry"]

codevigil/registry.py

@@ -0,0 +1,121 @@
+"""Shared validation for the collector and renderer registries.
+
+Both ``codevigil.collectors`` and ``codevigil.renderers`` expose a registry
+dict built by calling ``register()`` at module import time. This module holds
+the validation rules that apply to both:
+
+* Duplicate ``name`` collides loudly via ``RegistryCollisionError``.
+* Third-party plugins (any module not under ``codevigil.collectors`` /
+  ``codevigil.renderers``) must use a dotted ``name`` to avoid stomping on
+  built-in names. Built-ins use bare names.
+* Each registered class is checked for the presence of the attributes and
+  methods its target protocol declares, at registration time — not at the
+  first ingest/render call.
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar, cast
+
+from codevigil.types import Collector, Renderer
+
+_CODEVIGIL_COLLECTOR_PKG: str = "codevigil.collectors"
+_CODEVIGIL_RENDERER_PKG: str = "codevigil.renderers"
+
+_COLLECTOR_REQUIRED_METHODS: tuple[str, ...] = ("ingest", "snapshot", "reset")
+_RENDERER_REQUIRED_METHODS: tuple[str, ...] = ("render", "render_error", "close")
+
+_COLLECTOR_REQUIRED_STR_ATTRS: tuple[str, ...] = ("name", "complexity")
+_RENDERER_REQUIRED_STR_ATTRS: tuple[str, ...] = ("name",)
+
+
+class RegistryCollisionError(Exception):
+    """Two classes tried to register under the same name."""
+
+
+class RegistryValidationError(Exception):
+    """A class failed protocol conformance or namespacing checks at registration."""
+
+
+def _check_str_attrs(cls: type, attrs: tuple[str, ...], kind: str) -> None:
+    for attr in attrs:
+        if not hasattr(cls, attr):
+            raise RegistryValidationError(
+                f"{kind} {cls.__qualname__!r} is missing required class attribute {attr!r}"
+            )
+        value = getattr(cls, attr)
+        if not isinstance(value, str) or not value:
+            raise RegistryValidationError(
+                f"{kind} {cls.__qualname__!r} class attribute {attr!r} must be a "
+                f"non-empty string; got {type(value).__name__}"
+            )
+
+
+def _check_methods(cls: type, methods: tuple[str, ...], kind: str) -> None:
+    for method in methods:
+        if not callable(getattr(cls, method, None)):
+            raise RegistryValidationError(
+                f"{kind} {cls.__qualname__!r} is missing required method {method!r}"
+            )
+
+
+def _check_namespace(cls: type, name: str, builtin_pkg: str, kind: str) -> None:
+    module = cls.__module__ or ""
+    is_builtin = module == builtin_pkg or module.startswith(builtin_pkg + ".")
+    if is_builtin:
+        if "." in name:
+            raise RegistryValidationError(
+                f"built-in {kind} {cls.__qualname__!r} must use a bare name "
+                f"without dots; got {name!r}"
+            )
+        return
+    if "." not in name:
+        raise RegistryValidationError(
+            f"third-party {kind} {cls.__qualname__!r} (module {module!r}) must "
+            f"register under a dotted name like 'vendor.metric'; got {name!r}"
+        )
+
+
+C = TypeVar("C", bound=type)
+
+
+def register_collector(registry: dict[str, type[Collector]], cls: C) -> C:
+    """Validate and register a collector class in the given registry dict."""
+
+    _check_str_attrs(cls, _COLLECTOR_REQUIRED_STR_ATTRS, kind="collector")
+    _check_methods(cls, _COLLECTOR_REQUIRED_METHODS, kind="collector")
+    name: str = cast(str, cls.name)  # type: ignore[attr-defined]
+    _check_namespace(cls, name, _CODEVIGIL_COLLECTOR_PKG, kind="collector")
+    if name in registry:
+        existing = registry[name]
+        raise RegistryCollisionError(
+            f"collector name {name!r} already registered by "
+            f"{existing.__qualname__!r}; {cls.__qualname__!r} cannot reuse it"
+        )
+    registry[name] = cls
+    return cls
+
+
+def register_renderer(registry: dict[str, type[Renderer]], cls: C) -> C:
+    """Validate and register a renderer class in the given registry dict."""
+
+    _check_str_attrs(cls, _RENDERER_REQUIRED_STR_ATTRS, kind="renderer")
+    _check_methods(cls, _RENDERER_REQUIRED_METHODS, kind="renderer")
+    name: str = cast(str, cls.name)  # type: ignore[attr-defined]
+    _check_namespace(cls, name, _CODEVIGIL_RENDERER_PKG, kind="renderer")
+    if name in registry:
+        existing = registry[name]
+        raise RegistryCollisionError(
+            f"renderer name {name!r} already registered by "
+            f"{existing.__qualname__!r}; {cls.__qualname__!r} cannot reuse it"
+        )
+    registry[name] = cls
+    return cls
+
+
+__all__ = [
+    "RegistryCollisionError",
+    "RegistryValidationError",
+    "register_collector",
+    "register_renderer",
+]

codevigil/renderers/__init__.py

@@ -0,0 +1,20 @@
+"""Renderer registry package.
+
+Built-in renderers import themselves into ``RENDERERS`` at module import
+time via ``register_renderer``. v0.1 ships the terminal and json_file
+renderers; third-party renderers register under dotted names.
+"""
+
+from __future__ import annotations
+
+from codevigil.registry import register_renderer
+from codevigil.renderers import json_file as _json_file
+from codevigil.renderers import terminal as _terminal
+from codevigil.types import Renderer
+
+RENDERERS: dict[str, type[Renderer]] = {}
+
+register_renderer(RENDERERS, _terminal.TerminalRenderer)
+register_renderer(RENDERERS, _json_file.JsonFileRenderer)
+
+__all__ = ["RENDERERS", "register_renderer"]

codevigil/renderers/json_file.py

@@ -0,0 +1,105 @@
+"""NDJSON file renderer backed by the rotating JSONL writer.
+
+Emits one JSON record per ``render()`` call into a rotating file under an
+output directory. The directory must resolve inside ``$HOME``; attempts to
+write outside are rejected at construction with ``PrivacyViolationError``,
+matching the scope check the watcher enforces on its walk root.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from codevigil.errors import (
+    CodevigilError,
+    ErrorLevel,
+    ErrorSource,
+    RotatingJsonlWriter,
+    record,
+)
+from codevigil.privacy import PrivacyViolationError
+from codevigil.types import MetricSnapshot, SessionMeta
+
+
+class JsonFileRenderer:
+    """Appends NDJSON snapshot records to a rotating file under ``output_dir``."""
+
+    name: str = "json_file"
+
+    def __init__(
+        self,
+        *,
+        output_dir: Path,
+        filename: str = "snapshots.jsonl",
+        max_bytes: int = 10 * 1024 * 1024,
+        backups: int = 3,
+    ) -> None:
+        resolved_dir = self._validate_dir(output_dir)
+        self._output_dir: Path = resolved_dir
+        self._filename: str = filename
+        self._path: Path = resolved_dir / filename
+        self._writer: RotatingJsonlWriter = RotatingJsonlWriter(
+            self._path, max_bytes=max_bytes, backups=backups
+        )
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @staticmethod
+    def _validate_dir(output_dir: Path) -> Path:
+        resolved_dir = output_dir.expanduser().resolve()
+        home = Path.home().resolve()
+        if not resolved_dir.is_relative_to(home):
+            err = CodevigilError(
+                level=ErrorLevel.CRITICAL,
+                source=ErrorSource.RENDERER,
+                code="json_file.path_scope_violation",
+                message=(
+                    f"json_file output directory {str(resolved_dir)!r} is outside "
+                    f"the user home directory {str(home)!r}; refusing to write"
+                ),
+                context={"output_dir": str(resolved_dir), "home": str(home)},
+            )
+            record(err)
+            raise PrivacyViolationError(err.message)
+        return resolved_dir
+
+    def render(self, snapshots: list[MetricSnapshot], meta: SessionMeta) -> None:
+        record_payload: dict[str, Any] = {
+            "timestamp": datetime.now(tz=UTC).isoformat(),
+            "kind": "snapshot",
+            "session_id": meta.session_id,
+            "project_hash": meta.project_hash,
+            "project_name": meta.project_name,
+            "state": meta.state.value,
+            "parse_confidence": meta.parse_confidence,
+            "snapshots": [_snapshot_to_dict(s) for s in snapshots],
+        }
+        self._writer.write(record_payload)
+
+    def render_error(self, err: CodevigilError, meta: SessionMeta | None) -> None:
+        payload: dict[str, Any] = err.to_json_record()
+        payload["kind"] = "error"
+        if meta is not None:
+            payload["session_id"] = meta.session_id
+            payload["project_hash"] = meta.project_hash
+        self._writer.write(payload)
+
+    def close(self) -> None:
+        """No-op. ``RotatingJsonlWriter`` opens and closes per write."""
+
+
+def _snapshot_to_dict(snap: MetricSnapshot) -> dict[str, Any]:
+    return {
+        "name": snap.name,
+        "value": snap.value,
+        "label": snap.label,
+        "severity": snap.severity.value,
+        "detail": snap.detail,
+    }
+
+
+__all__ = ["JsonFileRenderer"]