codd-dev 0.2.0a1__py3-none-any.whl

codd/graph.py

@@ -0,0 +1,288 @@
+"""CEG (Conditioned Evidence Graph) — JSONL file-backed dependency graph.
+
+Design: All data lives in JSONL files (one record per line).
+Files are loaded into memory on init, flushed to disk on close().
+Git-friendly: every change is a line-level diff.
+"""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+class CEG:
+    """Conditioned Evidence Graph — JSONL-backed dependency graph.
+
+    Storage:
+      {scan_dir}/nodes.jsonl  — one JSON object per line
+      {scan_dir}/edges.jsonl  — one JSON object per line
+    """
+
+    def __init__(self, scan_dir: Path):
+        self.scan_dir = Path(scan_dir)
+        self.scan_dir.mkdir(parents=True, exist_ok=True)
+
+        self.nodes_path = self.scan_dir / "nodes.jsonl"
+        self.edges_path = self.scan_dir / "edges.jsonl"
+
+        # In-memory stores
+        self.nodes: dict[str, dict] = {}   # keyed by node_id
+        self.edges: list[dict] = []         # list of edge dicts
+        self._next_edge_id = 1
+        self._dirty = False
+
+        # Load existing data
+        self._load()
+
+    def _load(self):
+        """Load JSONL files into memory."""
+        if self.nodes_path.exists():
+            for line in self.nodes_path.read_text().splitlines():
+                line = line.strip()
+                if line:
+                    node = json.loads(line)
+                    self.nodes[node["id"]] = node
+
+        if self.edges_path.exists():
+            for line in self.edges_path.read_text().splitlines():
+                line = line.strip()
+                if line:
+                    edge = json.loads(line)
+                    self.edges.append(edge)
+                    if edge.get("id", 0) >= self._next_edge_id:
+                        self._next_edge_id = edge["id"] + 1
+
+    def close(self):
+        """Flush to disk."""
+        if self._dirty:
+            self._flush()
+
+    def _flush(self):
+        """Write all data back to JSONL files."""
+        # Sort nodes by id for stable output
+        sorted_nodes = sorted(self.nodes.values(), key=lambda n: n["id"])
+        with open(self.nodes_path, "w") as f:
+            for node in sorted_nodes:
+                f.write(json.dumps(node, ensure_ascii=False) + "\n")
+
+        # Sort edges by id for stable output
+        sorted_edges = sorted(self.edges, key=lambda e: e.get("id", 0))
+        with open(self.edges_path, "w") as f:
+            for edge in sorted_edges:
+                f.write(json.dumps(edge, ensure_ascii=False) + "\n")
+
+        self._dirty = False
+
+    # ── Node operations ──
+
+    def upsert_node(self, node_id: str, node_type: str, path: str = None,
+                    name: str = None, module: str = None):
+        node = self.nodes.get(node_id, {"id": node_id})
+        node["type"] = node_type
+        if path is not None:
+            node["path"] = path
+        if name is not None:
+            node["name"] = name
+        if module is not None:
+            node["module"] = module
+        self.nodes[node_id] = node
+        self._dirty = True
+
+    def get_node(self, node_id: str) -> Optional[dict]:
+        return self.nodes.get(node_id)
+
+    def count_nodes(self) -> int:
+        return len(self.nodes)
+
+    def find_nodes_by_path(self, path: str) -> list:
+        return [n for n in self.nodes.values() if n.get("path") == path]
+
+    def get_convention_edges(self, node_id: str) -> list:
+        results = []
+        for e in self.edges:
+            if e["source_id"] == node_id and e["relation"] == "must_review" and e.get("is_active", True):
+                target = self.nodes.get(e["target_id"], {})
+                result = {**e, "target_name": target.get("name"), "target_type": target.get("type")}
+                results.append(result)
+        results.sort(key=lambda x: x.get("confidence", 0), reverse=True)
+        return results
+
+    # ── Edge operations ──
+
+    def add_edge(self, source_id: str, target_id: str, relation: str,
+                 semantic: str, confidence: float = 0.5,
+                 condition: str = None) -> int:
+        edge_id = self._next_edge_id
+        self._next_edge_id += 1
+        edge = {
+            "id": edge_id,
+            "source_id": source_id,
+            "target_id": target_id,
+            "relation": relation,
+            "semantic": semantic,
+            "confidence": confidence,
+            "is_active": True,
+            "evidence": [],
+        }
+        if condition:
+            edge["condition"] = condition
+        self.edges.append(edge)
+        self._dirty = True
+        return edge_id
+
+    def get_outgoing_edges(self, node_id: str, min_confidence: float = 0.0) -> list:
+        results = []
+        for e in self.edges:
+            if (e["source_id"] == node_id and e.get("is_active", True)
+                    and e.get("confidence", 0) >= min_confidence):
+                target = self.nodes.get(e["target_id"], {})
+                result = {**e, "target_name": target.get("name"), "target_type": target.get("type")}
+                results.append(result)
+        results.sort(key=lambda x: x.get("confidence", 0), reverse=True)
+        return results
+
+    def get_incoming_edges(self, node_id: str, min_confidence: float = 0.0) -> list:
+        results = []
+        for e in self.edges:
+            if (e["target_id"] == node_id and e.get("is_active", True)
+                    and e.get("confidence", 0) >= min_confidence):
+                source = self.nodes.get(e["source_id"], {})
+                result = {**e, "source_name": source.get("name"), "source_type": source.get("type")}
+                results.append(result)
+        results.sort(key=lambda x: x.get("confidence", 0), reverse=True)
+        return results
+
+    def count_edges(self) -> int:
+        return sum(1 for e in self.edges if e.get("is_active", True))
+
+    # ── Evidence operations ──
+
+    def add_evidence(self, edge_id: int, source_type: str, method: str,
+                     score: float, detail: str = None, is_negative: bool = False) -> int:
+        for edge in self.edges:
+            if edge["id"] == edge_id:
+                ev = {"source_type": source_type, "method": method, "score": score}
+                if detail:
+                    ev["detail"] = detail
+                if is_negative:
+                    ev["is_negative"] = True
+                edge.setdefault("evidence", []).append(ev)
+                # Recalculate confidence via Noisy-OR
+                edge["confidence"] = self._noisy_or(edge["evidence"])
+                self._dirty = True
+                return len(edge["evidence"])
+        return 0
+
+    @staticmethod
+    def _noisy_or(evidence: list) -> float:
+        """Noisy-OR: P(at least one fires) = 1 - product(1 - p_i)."""
+        positive_product = 1.0
+        negative_product = 1.0
+        for ev in evidence:
+            if ev.get("is_negative"):
+                negative_product *= (1.0 - ev["score"])
+            else:
+                positive_product *= (1.0 - ev["score"])
+        return round(max(0.0, (1.0 - positive_product) - (1.0 - negative_product)), 4)
+
+    # ── Propagation ──
+
+    def propagate_impact(self, start_node_id: str, max_depth: int = 10,
+                         min_confidence: float = 0.0) -> dict:
+        """BFS propagation from a changed node."""
+        visited = {}
+        queue = [(start_node_id, 0, [start_node_id])]
+
+        while queue:
+            current, depth, path = queue.pop(0)
+            if depth > max_depth:
+                continue
+            if current in visited:
+                continue
+            visited[current] = {"depth": depth, "path": path}
+
+            for edge in self.get_outgoing_edges(current, min_confidence):
+                target = edge["target_id"]
+                if target not in visited:
+                    queue.append((target, depth + 1, path + [target]))
+
+        if start_node_id in visited:
+            del visited[start_node_id]
+        return visited
+
+    # ── Band classification ──
+
+    def classify_band(self, confidence: float, evidence_count: int,
+                      green_threshold: float = 0.90,
+                      green_min_evidence: int = 2,
+                      amber_threshold: float = 0.50) -> str:
+        if confidence >= green_threshold and evidence_count >= green_min_evidence:
+            return "green"
+        elif confidence >= amber_threshold:
+            return "amber"
+        else:
+            return "gray"
+
+    # ── Selective refresh ──
+
+    AUTO_SOURCE_TYPES = ("static", "framework", "frontmatter", "inferred")
+    HUMAN_SOURCE_TYPES = ("human", "dynamic", "history")
+
+    def purge_auto_generated(self) -> dict:
+        """Delete auto-generated evidence/edges/nodes, preserve human knowledge."""
+        deleted_evidence = 0
+        deleted_edges = 0
+
+        # Remove auto evidence from edges
+        surviving_edges = []
+        for edge in self.edges:
+            original_count = len(edge.get("evidence", []))
+            edge["evidence"] = [
+                ev for ev in edge.get("evidence", [])
+                if ev.get("source_type") not in self.AUTO_SOURCE_TYPES
+            ]
+            deleted_evidence += original_count - len(edge["evidence"])
+
+            if edge["evidence"]:
+                edge["confidence"] = self._noisy_or(edge["evidence"])
+                surviving_edges.append(edge)
+            else:
+                deleted_edges += 1
+
+        self.edges = surviving_edges
+
+        # Remove orphan nodes
+        referenced = set()
+        for edge in self.edges:
+            referenced.add(edge["source_id"])
+            referenced.add(edge["target_id"])
+
+        orphans = [nid for nid in self.nodes if nid not in referenced]
+        for nid in orphans:
+            del self.nodes[nid]
+
+        self._dirty = True
+        return {
+            "evidence": deleted_evidence,
+            "edges": deleted_edges,
+            "nodes": len(orphans),
+        }
+
+    def count_human_evidence(self) -> int:
+        count = 0
+        for edge in self.edges:
+            for ev in edge.get("evidence", []):
+                if ev.get("source_type") in self.HUMAN_SOURCE_TYPES:
+                    count += 1
+        return count
+
+    # ── Stats ──
+
+    def stats(self) -> dict:
+        total_evidence = sum(len(e.get("evidence", [])) for e in self.edges)
+        return {
+            "nodes": self.count_nodes(),
+            "edges": self.count_edges(),
+            "evidence": total_evidence,
+            "human_evidence": self.count_human_evidence(),
+        }

codd/hooks.py

@@ -0,0 +1,104 @@
+"""Git hook helpers for CoDD pre-commit enforcement."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path, PurePosixPath
+
+import yaml
+
+from codd.scanner import _extract_frontmatter
+from codd.validator import run_validate
+
+
+HOOK_SOURCE = Path(__file__).parent.parent / "hooks" / "pre-commit"
+
+
+def install_pre_commit_hook(project_root: Path) -> tuple[Path, bool]:
+    """Install the packaged pre-commit hook into a Git repository."""
+    config_path = project_root / "codd" / "codd.yaml"
+    if not config_path.exists():
+        raise FileNotFoundError(f"{config_path} not found")
+
+    git_dir = project_root / ".git"
+    if not git_dir.exists():
+        raise FileNotFoundError(f"{git_dir} not found")
+
+    if not HOOK_SOURCE.exists():
+        raise FileNotFoundError(f"{HOOK_SOURCE} not found")
+
+    destination = git_dir / "hooks" / "pre-commit"
+    source = HOOK_SOURCE.resolve()
+    source.chmod(source.stat().st_mode | 0o111)
+
+    if destination.is_symlink():
+        if destination.resolve() == source:
+            return destination, False
+        raise FileExistsError(f"{destination} already exists and points to {destination.resolve()}")
+
+    if destination.exists():
+        raise FileExistsError(f"{destination} already exists")
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.symlink_to(source)
+    return destination, True
+
+
+def run_pre_commit(project_root: Path) -> int:
+    """Validate staged CoDD documents before commit."""
+    config_path = project_root / "codd" / "codd.yaml"
+    if not config_path.exists():
+        print("ERROR: codd/codd.yaml not found.")
+        return 1
+
+    config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    try:
+        staged_docs = _get_staged_markdown_files(project_root, config)
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+    for relative_path in staged_docs:
+        if _extract_frontmatter(project_root / relative_path) is not None:
+            continue
+        print(f"ERROR: {relative_path} is missing CoDD YAML frontmatter")
+        return 1
+
+    return run_validate(project_root, project_root / "codd")
+
+
+def _get_staged_markdown_files(project_root: Path, config: dict) -> list[Path]:
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"],
+        cwd=project_root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "git diff --cached failed")
+
+    doc_dirs = ((config.get("scan") or {}).get("doc_dirs") or [])
+    staged_docs: list[Path] = []
+
+    for entry in result.stdout.splitlines():
+        relative_path = entry.strip()
+        if not relative_path.endswith(".md"):
+            continue
+        if not _is_in_doc_dirs(relative_path, doc_dirs):
+            continue
+        staged_docs.append(Path(relative_path))
+
+    return staged_docs
+
+
+def _is_in_doc_dirs(relative_path: str, doc_dirs: list[str]) -> bool:
+    rel = PurePosixPath(relative_path)
+    for doc_dir in doc_dirs:
+        base = PurePosixPath(str(doc_dir).rstrip("/"))
+        try:
+            rel.relative_to(base)
+            return True
+        except ValueError:
+            continue
+    return False