awgit 0.1.0__py3-none-any.whl

awgit/oplog.py

@@ -0,0 +1,221 @@
+"""Durable append-only op-log for the semantic-VCS layer.
+
+An ``EditOp`` is one commit's semantic annotation. The log is append-only
+JSONL — each line one ``EditOp.to_dict()`` — under an OS-level exclusive lock
+with an fsync on every append. It is NOT recomputable (ops carry summaries), so
+``export`` is the durability story; a fresh machine clones + reindexes and
+optionally imports a shipped export.
+
+The post-commit hook runs as its own sync process, so ``FileLock`` below is a
+plain blocking call reached only from sync code (PQ010 escape, see comment).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from pathlib import Path
+from threading import RLock
+from typing import Dict, Iterable, List, Optional
+
+from awgit.data_root import vcs_data_root
+from awgit.schema import EditOp
+
+_HEADER = "# vcs-oplog v1"
+
+
+def _lock_path(data_root: Path) -> Path:
+    return data_root / "oplog.lock"
+
+
+# Per-path process-local mutexes guarding the cross-process file locks.
+# Windows msvcrt ``LK_LOCK`` retries ~10x then raises EDEADLK under dense
+# INTRA-process thread contention (20 threads, one process, one lock byte) —
+# cross-process locking works (separate processes block), but threads in ONE
+# process trip the retry limit. The mutex serializes threads in-process; the
+# file lock still serializes across processes (the real post-commit-hook case:
+# concurrent captures from separate hook processes). Caught by the M6
+# concurrent-put test; M1's threaded append test passed only by looser
+# contention.
+_PROCESS_LOCKS: Dict[str, "threading.Lock"] = {}
+_PROCESS_LOCKS_GUARD = threading.Lock()
+
+
+def _process_lock(path: Path) -> "threading.Lock":
+    key = str(path.resolve())
+    with _PROCESS_LOCKS_GUARD:
+        return _PROCESS_LOCKS.setdefault(key, threading.Lock())
+
+
+class FileLock:
+    """Cross-process exclusive lock (msvcrt on Windows, fcntl on POSIX),
+    serialized within the process by a per-path mutex.
+
+    blocking-ok: OS-level advisory lock; reached only from the sync CLI/hook
+    path, never from an event loop (PQ010).
+    """
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._fh = None
+        self._plock = _process_lock(path)
+
+    def __enter__(self) -> "FileLock":
+        self._plock.acquire()
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._fh = open(self._path, "a+b")
+            if self._fh.seek(0, os.SEEK_END) == 0:
+                self._fh.write(b"\0")
+                self._fh.flush()
+            self._fh.seek(0)
+            try:
+                import msvcrt
+
+                msvcrt.locking(self._fh.fileno(), msvcrt.LK_LOCK, 1)
+            except ImportError:
+                import fcntl
+
+                fcntl.flock(self._fh.fileno(), fcntl.LOCK_EX)
+        except BaseException:
+            self._plock.release()
+            raise
+        return self
+
+    def __exit__(self, *exc) -> bool:
+        try:
+            if self._fh is not None:
+                try:
+                    import msvcrt
+
+                    self._fh.seek(0)
+                    msvcrt.locking(self._fh.fileno(), msvcrt.LK_UNLCK, 1)
+                except ImportError:
+                    import fcntl
+
+                    fcntl.flock(self._fh.fileno(), fcntl.LOCK_UN)
+                self._fh.close()
+                self._fh = None
+        finally:
+            self._plock.release()
+        return False
+
+
+class OpLog:
+    """Append-only semantic op log backed by one JSONL file."""
+
+    def __init__(self, data_root: Optional[Path] = None) -> None:
+        self._data_root = data_root or vcs_data_root()
+        self.path = self._data_root / "oplog.jsonl"
+        self._lock = RLock()
+        self._ops: Dict[str, EditOp] = {}
+        self._load()
+
+    # ── persistence ────────────────────────────────────────────────────
+
+    def _load(self) -> None:
+        if not self.path.exists():
+            return
+        with FileLock(_lock_path(self._data_root)):
+            with open(self.path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    op = EditOp.from_dict(json.loads(line))
+                    self._ops[op.op_id] = op
+
+    def append(self, op: EditOp) -> None:
+        """Append one op durably. Idempotent by op_id (callers may retry)."""
+        with self._lock:
+            if op.op_id in self._ops:
+                return
+            with FileLock(_lock_path(self._data_root)):
+                self._data_root.mkdir(parents=True, exist_ok=True)
+                fresh = not self.path.exists()
+                with open(self.path, "a", encoding="utf-8") as f:
+                    if fresh:
+                        f.write(_HEADER + "\n")
+                    f.write(json.dumps(op.to_dict()) + "\n")
+                    f.flush()
+                    os.fsync(f.fileno())
+            self._ops[op.op_id] = op
+
+    # ── queries ────────────────────────────────────────────────────────
+
+    def all_ops(self) -> List[EditOp]:
+        return list(self._ops.values())
+
+    def ops_for_commit(self, git_sha: str) -> List[EditOp]:
+        return [op for op in self._ops.values() if op.git_sha == git_sha]
+
+    def ops_for_node(self, node_id: str) -> List[EditOp]:
+        return [
+            op for op in self._ops.values()
+            if any(nc.node_id == node_id for nc in op.node_changes)
+        ]
+
+    def ops_since(self, ts: str) -> List[EditOp]:
+        return [op for op in self._ops.values() if op.ts >= ts]
+
+    def ops_by(self, actor: str) -> List[EditOp]:
+        return [op for op in self._ops.values() if op.actor == actor]
+
+    def sha_index(self) -> Dict[str, str]:
+        return {op.git_sha: op.op_id for op in self._ops.values()}
+
+    def has_commit(self, git_sha: str) -> bool:
+        return any(op.git_sha == git_sha for op in self._ops.values())
+
+    def get(self, op_id: str) -> Optional[EditOp]:
+        return self._ops.get(op_id)
+
+    def linearize(self, op_ids: Iterable[str]) -> List[EditOp]:
+        """Order ops so causal parents precede their children (stable)."""
+        want = {oid for oid in op_ids if oid in self._ops}
+        if not want:
+            return []
+        indeg: Dict[str, int] = {oid: 0 for oid in want}
+        children: Dict[str, List[str]] = {oid: [] for oid in want}
+        for oid in want:
+            for p in self._ops[oid].parent_ops:
+                if p in want:
+                    indeg[oid] += 1
+                    children.setdefault(p, []).append(oid)
+        ready = sorted(oid for oid, d in indeg.items() if d == 0)
+        out: List[EditOp] = []
+        while ready:
+            oid = ready.pop(0)
+            out.append(self._ops[oid])
+            for c in children[oid]:
+                indeg[c] -= 1
+                if indeg[c] == 0:
+                    ready.append(c)
+        done = {op.op_id for op in out}
+        for oid in sorted(want):
+            if oid not in done:
+                out.append(self._ops[oid])
+        return out
+
+    def export(self, dest_path: Path) -> int:
+        """Write the full log to ``dest_path`` (for backup / shipping)."""
+        dest_path = Path(dest_path)
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(dest_path, "w", encoding="utf-8") as f:
+            f.write(_HEADER + "\n")
+            for op in self.all_ops():
+                f.write(json.dumps(op.to_dict()) + "\n")
+        return len(self._ops)
+
+    def import_log(self, src_path: Path) -> int:
+        """Load ops from an exported log; returns count imported."""
+        count = 0
+        with open(src_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                self.append(EditOp.from_dict(json.loads(line)))
+                count += 1
+        return count

awgit/parser.py

@@ -0,0 +1,186 @@
+"""Minimal Python source parser for standalone awgit.
+
+Replicates the chunk shape of ``lib.faculties.CodeGraph.parse_source_bytes``
+that awgit's capture/diff/merge consume — a ``ParseResult.chunks`` list whose
+members expose ``name``, ``chunk_type`` (a ``.value`` in
+``function|class|method|module``), ``signature``, ``start_line`` (1-indexed),
+``end_line`` (inclusive). Built on Python's ``ast`` — no AitherOS dependency.
+
+Fidelity notes (each verified against the reference so node ids stay stable
+across the monorepo and the standalone package):
+- Method chunks are named ``Class.method``. The stable node id is keyed on
+  ``(name, path, type)``, so an unqualified method name would mint a different
+  id than the reference parser and break cross-repo id stability.
+- The MODULE chunk is emitted only when the file has a docstring or top-level
+  constant assignments (the reference skips empty module chunks, so an
+  unconditional one would mint a spurious module node on every file and turn
+  every capture into a module rewrite). Its range is ``1..1`` like the
+  reference.
+- Function/method signatures replicate ``get_signature``: positional args with
+  annotations + return annotation, ``async def`` prefix; defaults, ``*args``/
+  ``**kwargs`` and ``/``/``*`` separators are deliberately omitted (matching
+  the reference) so a signature change flags the same way.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+_MODULE_CONST_LIMIT = 60
+_MODULE_VALUE_CHARS = 120
+
+
+class ChunkType(Enum):
+    MODULE = "module"
+    CLASS = "class"
+    METHOD = "method"
+    FUNCTION = "function"
+
+
+@dataclass
+class Chunk:
+    name: str
+    chunk_type: ChunkType
+    signature: str = ""
+    start_line: int = 0
+    end_line: int = 0
+
+
+@dataclass
+class ParseResult:
+    chunks: List[Chunk] = field(default_factory=list)
+
+
+def _get_signature(node: ast.AST) -> str:
+    """Full function signature — mirrors CodeGraph's ``get_signature``."""
+    args: List[str] = []
+    for arg in node.args.args:
+        arg_str = arg.arg
+        if arg.annotation:
+            try:
+                arg_str += f": {ast.unparse(arg.annotation)}"
+            except Exception as e:  # malformed annotation: keep the bare arg
+                logger.debug("awgit parser: annotation unparse failed: %s", e)
+        args.append(arg_str)
+    returns = ""
+    if node.returns:
+        try:
+            returns = f" -> {ast.unparse(node.returns)}"
+        except Exception as e:  # malformed return annotation: omit it
+            logger.debug("awgit parser: return annotation unparse failed: %s", e)
+    prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+    return f"{prefix} {node.name}({', '.join(args)}){returns}"
+
+
+def _module_chunk(tree: ast.Module, path: str) -> Optional[Chunk]:
+    """One chunk at module scope — ONLY when there is something to index."""
+    docstring = ast.get_docstring(tree)
+    consts: List[str] = []
+    for node in ast.iter_child_nodes(tree):
+        targets: List[str] = []
+        value = None
+        if isinstance(node, ast.Assign):
+            targets = [t.id for t in node.targets if isinstance(t, ast.Name)]
+            value = node.value
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            targets = [node.target.id]
+            value = node.value
+        if not targets or value is None:
+            continue
+        try:
+            rendered = ast.unparse(value)
+        except Exception as e:  # un-unparseable const value: skip it
+            logger.debug("awgit parser: const unparse failed: %s", e)
+            continue
+        if len(rendered) > _MODULE_VALUE_CHARS:
+            rendered = rendered[:_MODULE_VALUE_CHARS] + "..."
+        for t in targets:
+            if t.startswith("__"):
+                continue
+            consts.append(f"{t} = {rendered}")
+        if len(consts) >= _MODULE_CONST_LIMIT:
+            break
+    if not docstring and not consts:
+        return None
+    name = Path(path).stem
+    return Chunk(
+        name=name,
+        chunk_type=ChunkType.MODULE,
+        signature=f"module {name}",
+        start_line=1,
+        end_line=1,
+    )
+
+
+def _class_chunk(node: ast.ClassDef) -> Chunk:
+    bases: List[str] = []
+    for b in node.bases:
+        try:
+            bases.append(ast.unparse(b))
+        except Exception as e:  # un-unparseable base: omit it from the header
+            logger.debug("awgit parser: class base unparse failed: %s", e)
+    signature = f"class {node.name}"
+    if bases:
+        signature += f"({', '.join(bases)})"
+    return Chunk(
+        name=node.name,
+        chunk_type=ChunkType.CLASS,
+        signature=signature,
+        start_line=node.lineno,
+        end_line=node.end_lineno or node.lineno,
+    )
+
+
+def _func_chunk(node: ast.AST, chunk_type: ChunkType) -> Chunk:
+    return Chunk(
+        name=node.name,
+        chunk_type=chunk_type,
+        signature=_get_signature(node),
+        start_line=node.lineno,
+        end_line=node.end_lineno or node.lineno,
+    )
+
+
+def _method_chunk(class_name: str, node: ast.AST) -> Chunk:
+    return Chunk(
+        name=f"{class_name}.{node.name}",
+        chunk_type=ChunkType.METHOD,
+        signature=_get_signature(node),
+        start_line=node.lineno,
+        end_line=node.end_lineno or node.lineno,
+    )
+
+
+def parse_source_bytes(content: bytes, path: str) -> ParseResult:
+    """Parse Python source bytes into chunks (no disk, no AitherOS deps).
+
+    One chunk per top-level function, class, and class method, plus a module
+    chunk when the file carries a docstring or top-level constants. Mirrors the
+    reference extractor's traversal depth exactly (methods live one level below
+    classes; nested classes/functions are not indexed).
+    """
+    source = content.decode("utf-8", errors="ignore")
+    try:
+        tree = ast.parse(source, filename=path)
+    except SyntaxError:
+        return ParseResult(chunks=[])
+    result = ParseResult()
+    module = _module_chunk(tree, path)
+    if module is not None:
+        result.chunks.append(module)
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            result.chunks.append(_class_chunk(node))
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    result.chunks.append(_method_chunk(node.name, item))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            result.chunks.append(_func_chunk(node, ChunkType.FUNCTION))
+    return result

awgit/schema.py

@@ -0,0 +1,190 @@
+"""Edit-op schema — the contract every semantic-VCS component shares.
+
+SCHEMA_VERSION gates ``from_dict``: a record written by a NEWER version is
+refused loudly rather than silently misparsed (a future record is a hard
+error, never a guess).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+SCHEMA_VERSION = 1
+
+CHANGE_TYPES = (
+    "body_rewrite",
+    "added",
+    "deleted",
+    "renamed",
+    "moved",
+    "signature_changed",
+)
+
+
+@dataclass
+class NodeChange:
+    """One node (function/class/method) changed by an edit-op."""
+
+    node_id: str
+    change_type: str
+    old_body_sha: Optional[str] = None
+    new_body_sha: Optional[str] = None
+    symbol: str = ""
+    path: str = ""
+    renamed_from: Optional[str] = None
+    moved_from: Optional[str] = None
+    semantic_note: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "node_id": self.node_id,
+            "change_type": self.change_type,
+            "old_body_sha": self.old_body_sha,
+            "new_body_sha": self.new_body_sha,
+            "symbol": self.symbol,
+            "path": self.path,
+            "renamed_from": self.renamed_from,
+            "moved_from": self.moved_from,
+            "semantic_note": self.semantic_note,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "NodeChange":
+        return cls(
+            node_id=d["node_id"],
+            change_type=d["change_type"],
+            old_body_sha=d.get("old_body_sha"),
+            new_body_sha=d.get("new_body_sha"),
+            symbol=d.get("symbol", ""),
+            path=d.get("path", ""),
+            renamed_from=d.get("renamed_from"),
+            moved_from=d.get("moved_from"),
+            semantic_note=d.get("semantic_note", ""),
+        )
+
+
+@dataclass
+class EditOp:
+    """One commit's semantic annotation."""
+
+    op_id: str
+    parent_ops: List[str]
+    actor: str
+    ts: str
+    git_sha: str
+    git_parent_sha: str
+    file_paths: List[str]
+    node_changes: List[NodeChange]
+    summary: str = ""
+    leased: bool = False
+    schema_version: int = SCHEMA_VERSION
+    # Actor provenance (added additively — old ops parse with these defaults).
+    # `actor` is the CLAIMED attribution (explicit arg / AITHER_ACTOR / git
+    # author); `actor_verified` + `verified_actor` record the box's VERIFIED
+    # identity (the Aitherium GitHub OAuth app / GitHub App login via `gh`)
+    # INDEPENDENTLY, so a session claiming `AITHER_ACTOR=lyra` on a box verified
+    # as `wizzense` records both. The verified half is the authoritative
+    # attribution; self-asserted actor is forgeable and the op-log now says so
+    # explicitly.
+    actor_verified: bool = False
+    actor_source: str = "env"
+    verified_actor: str = ""
+    # Durable attribution handle — a stable id for this op that replays/exports
+    # can point at. Minted deterministically from (op_id, git_sha) — see
+    # ledger.py. The op-log only RECORDS; it never gates a commit.
+    ledger_ref: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "op_id": self.op_id,
+            "parent_ops": list(self.parent_ops),
+            "actor": self.actor,
+            "ts": self.ts,
+            "git_sha": self.git_sha,
+            "git_parent_sha": self.git_parent_sha,
+            "file_paths": list(self.file_paths),
+            "node_changes": [nc.to_dict() for nc in self.node_changes],
+            "summary": self.summary,
+            "leased": self.leased,
+            "schema_version": self.schema_version,
+            "actor_verified": self.actor_verified,
+            "actor_source": self.actor_source,
+            "verified_actor": self.verified_actor,
+            "ledger_ref": self.ledger_ref,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "EditOp":
+        sv = d.get("schema_version", 0)
+        if not isinstance(sv, int) or sv > SCHEMA_VERSION:
+            raise ValueError(
+                f"EditOp schema_version {sv!r} is newer than supported "
+                f"{SCHEMA_VERSION} — refusing to misparse. Rebuild the reader "
+                "or upgrade the exporter."
+            )
+        for key in ("op_id", "git_sha", "git_parent_sha"):
+            if key not in d:
+                raise ValueError(f"EditOp missing required field {key!r}")
+        return cls(
+            op_id=d["op_id"],
+            parent_ops=list(d.get("parent_ops", [])),
+            actor=d.get("actor", "unknown"),
+            ts=d.get("ts", ""),
+            git_sha=d["git_sha"],
+            git_parent_sha=d["git_parent_sha"],
+            file_paths=list(d.get("file_paths", [])),
+            node_changes=[NodeChange.from_dict(x) for x in d.get("node_changes", [])],
+            summary=d.get("summary", ""),
+            leased=bool(d.get("leased", False)),
+            schema_version=sv,
+            actor_verified=bool(d.get("actor_verified", False)),
+            actor_source=d.get("actor_source", "env"),
+            verified_actor=d.get("verified_actor", ""),
+            ledger_ref=d.get("ledger_ref", ""),
+        )
+
+
+@dataclass
+class MergeConflict:
+    """A collision the merge engine could not resolve and escalated."""
+
+    conflict_id: str
+    node_id: str
+    symbol: str
+    path: str = ""
+    base_body: Optional[str] = None
+    a_body: Optional[str] = None
+    b_body: Optional[str] = None
+    blast_radius: Dict[str, Any] = field(default_factory=dict)
+    suggested: Optional[str] = None
+    status: str = "escalated"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "conflict_id": self.conflict_id,
+            "node_id": self.node_id,
+            "symbol": self.symbol,
+            "path": self.path,
+            "base_body": self.base_body,
+            "a_body": self.a_body,
+            "b_body": self.b_body,
+            "blast_radius": self.blast_radius,
+            "suggested": self.suggested,
+            "status": self.status,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "MergeConflict":
+        return cls(
+            conflict_id=d["conflict_id"],
+            node_id=d["node_id"],
+            symbol=d.get("symbol", ""),
+            path=d.get("path", ""),
+            base_body=d.get("base_body"),
+            a_body=d.get("a_body"),
+            b_body=d.get("b_body"),
+            blast_radius=d.get("blast_radius", {}),
+            suggested=d.get("suggested"),
+            status=d.get("status", "escalated"),
+        )