sin-code-bundle 0.9.2__py3-none-any.whl

sin_code_bundle/__init__.py

@@ -0,0 +1,6 @@
+"""SIN-Code Bundle - Unified SOTA Agent-Engineering Stack.
+
+Docs: __init__.doc.md
+"""
+
+__version__ = "0.8.1"

sin_code_bundle/agents_md.py

@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: MIT
+"""Generator fuer eine AGENTS.md (WS4, Issue #4).
+
+OpenCode und Codex lesen automatisch eine ``AGENTS.md`` im Repo-Root. Dieser
+Generator schreibt einen SIN-Code-Block, der dem Agenten erklaert, *wann*
+welches SIN-Tool aufzurufen ist. Der Block ist zwischen Markern eingefasst und
+wird idempotent ersetzt -- der restliche Inhalt der Datei bleibt unangetastet.
+
+Docs: agents_md.doc.md
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+START_MARKER = "<!-- sin:start -->"
+END_MARKER = "<!-- sin:end -->"
+
+# ── Playbooks (situation → tool) ───────────────────────────────────────────
+# Mapping: wann welches Tool. Bewusst knapp und handlungsorientiert.
+_PLAYBOOK = [
+    (
+        "Before refactoring or deleting a symbol",
+        "impact",
+        "Get the blast radius (downstream dependents) before you change a shared symbol.",
+    ),
+    (
+        "After producing a diff / before committing",
+        "semantic_review",
+        "Summarize the intent and risk of the change instead of eyeballing line diffs.",
+    ),
+    (
+        "Before merging or marking a task done",
+        "verify_tests",
+        "Run independent, execution-based verification. Never trust a self-reported 'done'.",
+    ),
+    (
+        "When you need correctness guarantees",
+        "prove",
+        "Generate and check properties/proofs for pure functions.",
+    ),
+    (
+        "When code needs external services in tests",
+        "mock_env",
+        "Spin up an ephemeral full-stack mock environment, then tear it down.",
+    ),
+    (
+        "To understand overall code health",
+        "architectural_debt",
+        "Check the current architectural debt score before large changes.",
+    ),
+]
+
+# Memory playbook — only surfaced when SIN-Brain is installed (BR-2, Issue #15).
+_MEMORY_PLAYBOOK = [
+    (
+        "Before starting a task",
+        "recall",
+        "Pull prior decisions, conventions and known pitfalls for this area first.",
+    ),
+    (
+        "After making a non-obvious decision",
+        "remember",
+        "Persist the decision/convention/fix so future turns do not relitigate it.",
+    ),
+    (
+        "When a subsystem returns a verdict",
+        "link_evidence",
+        "Attach the oracle/poc/ibd/sckg/adw verdict to the affected code entity.",
+    ),
+    (
+        "When a memory is stale or wrong",
+        "forget",
+        "Remove outdated memories; `pin` the ones that must never be evicted.",
+    ),
+]
+
+
+# Red-zones: hard "do not" constraints. Negative constraints reliably steer
+# agents away from anti-patterns far better than positive guidance alone.
+_NEGATIVE_CONSTRAINTS = [
+    "Do **not** mark a task done or merge without a passing `verify_tests` run.",
+    "Do **not** refactor or delete a shared symbol before checking `impact`.",
+    "Do **not** invent file paths, APIs or symbols — confirm via `recall` / graph context.",
+    "Do **not** discard a memory verdict to make a change look clean.",
+    "Do **not** weaken or delete tests to get them to pass.",
+    "Do **not** commit secrets, tokens or credentials.",
+]
+
+
+# ── Block Builder + Public Renderers ───────────────────────────────────────
+def _build_block(memory_available: bool = False, inject_text: str = "") -> str:
+    """Baut den Inhalt zwischen den Markern (ohne die Marker selbst).
+
+    ``memory_available`` schaltet die Memory-Playbook-Zeilen frei; ``inject_text``
+    ist der von SIN-Brain gelieferte Kontext-Block (SB-4), der unveraendert
+    eingebettet wird.
+    """
+    lines = [
+        "## SIN-Code Agent Tooling",
+        "",
+        "This repository is wired to the SIN-Code verification stack via MCP",
+        "(`sin serve`). Use these tools proactively -- they are cheap signals that",
+        "prevent shipping broken code.",
+        "",
+        "### SIN-Brain Memory Protocol",
+        "",
+        "The project uses a 4-tier memory system:",
+        "- **Core**: Critical conventions (always recalled)",
+        "- **Recall**: Recent context (last 7 days)",
+        "- **Episodic**: Task history (last 30 days)",
+        "- **Consolidated**: Long-term knowledge (summaries)",
+        "",
+        "Call `recall` before starting work. Call `remember` after completing.",
+        "",
+        "### Memory Rules",
+        "",
+        "1. **Always recall first.** Check for existing context.",
+        "2. **Remember conventions.** Store patterns that caused bugs.",
+        "3. **Pin critical rules.** Use `pin` for must-remember items.",
+        "4. **Link evidence.** Connect related memories with `link_evidence`.",
+        "",
+        "### When to call which tool",
+        "",
+        "| Situation | Tool | Why |",
+        "| --- | --- | --- |",
+    ]
+    playbook = list(_PLAYBOOK)
+    if memory_available:
+        playbook += _MEMORY_PLAYBOOK
+    for situation, tool, why in playbook:
+        lines.append(f"| {situation} | `{tool}` | {why} |")
+
+    lines += [
+        "",
+        "### Rules",
+        "",
+        "1. **Do not claim success without `verify_tests`.** A green compile is not proof.",
+        "2. **Run `impact` before touching shared code** to avoid silent breakage.",
+        "3. **Prefer `semantic_review` over raw diffs** when assessing your own changes.",
+        "4. If a tool is unavailable, continue gracefully and say so explicitly.",
+        "5. **Recall before you code.** Always check SIN-Brain for relevant context.",
+        "6. **Remember after you learn.** Store conventions and pitfalls in memory.",
+    ]
+    if memory_available:
+        lines += [
+            "5. **Start with `recall` and persist decisions with `remember`** so the",
+            "   project's memory compounds across sessions.",
+        ]
+
+    lines += [
+        "",
+        "### Negative constraints (red-zones)",
+        "",
+    ]
+    lines += [f"- {c}" for c in _NEGATIVE_CONSTRAINTS]
+
+    if inject_text.strip():
+        lines += [
+            "",
+            "### Project memory (SIN-Brain)",
+            "",
+            "<!-- Injected by `sin agents-md` from SIN-Brain; regenerated each run. -->",
+            inject_text.strip(),
+        ]
+
+    return "\n".join(lines)
+
+
+def _memory_context() -> tuple[bool, str]:
+    """Return (sin-brain available?, inject text) from the memory adapter.
+
+    Defensive: any failure degrades to (False, "") so `sin agents-md` always
+    produces a valid file even without SIN-Brain installed.
+    """
+    try:
+        from sin_code_bundle import memory
+
+        env = memory.detect_env()
+        if not env.available:
+            return False, ""
+        inject = ""
+        getter = getattr(memory, "inject", None)
+        if callable(getter):
+            try:
+                inject = getter() or ""
+            except Exception:  # noqa: BLE001 - inject must never break generation
+                inject = ""
+        return True, inject
+    except Exception:  # noqa: BLE001
+        return False, ""
+
+
+def render_block(memory_available: bool | None = None, inject_text: str | None = None) -> str:
+    """Vollstaendiger, markierter SIN-Block (inkl. Marker)."""
+    if memory_available is None or inject_text is None:
+        detected_available, detected_inject = _memory_context()
+        memory_available = detected_available if memory_available is None else memory_available
+        inject_text = detected_inject if inject_text is None else inject_text
+    body = _build_block(memory_available=memory_available, inject_text=inject_text)
+    return f"{START_MARKER}\n{body}\n{END_MARKER}"
+
+
+def render_full_document(
+    memory_available: bool | None = None, inject_text: str | None = None
+) -> str:
+    """Eine komplette AGENTS.md fuer den Fall, dass noch keine existiert."""
+    header = "# AGENTS.md\n\nGuidance for AI coding agents working in this repository.\n"
+    block = render_block(memory_available=memory_available, inject_text=inject_text)
+    return f"{header}\n{block}\n"
+
+
+def upsert(path: Path) -> str:
+    """Schreibt/aktualisiert die AGENTS.md idempotent.
+
+    - Datei fehlt        -> komplette Vorlage mit SIN-Block anlegen.
+    - Datei ohne Block   -> SIN-Block am Ende anhaengen.
+    - Datei mit Block    -> nur den Bereich zwischen den Markern ersetzen.
+
+    Gibt eine kurze Statusmeldung zurueck.
+    """
+    mem_available, inject_text = _memory_context()
+    block = render_block(memory_available=mem_available, inject_text=inject_text)
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            render_full_document(memory_available=mem_available, inject_text=inject_text)
+        )
+        return f"Created {path} with SIN-Code block"
+
+    content = path.read_text()
+    if START_MARKER in content and END_MARKER in content:
+        start = content.index(START_MARKER)
+        end = content.index(END_MARKER) + len(END_MARKER)
+        new_content = content[:start] + block + content[end:]
+        if new_content == content:
+            path.write_text(new_content)
+            return f"{path} already up to date (no change)"
+        path.write_text(new_content)
+        return f"Updated SIN-Code block in {path}"
+
+    # Block fehlt: anhaengen, mit sauberem Abstand.
+    sep = "" if content.endswith("\n\n") else ("\n" if content.endswith("\n") else "\n\n")
+    path.write_text(content + sep + block + "\n")
+    return f"Appended SIN-Code block to {path}"

sin_code_bundle/ast_edit.py

@@ -0,0 +1,323 @@
+# SPDX-License-Identifier: MIT
+"""AST-based code editing with lazy tree-sitter + POC verification.
+
+Docs: ast_edit.doc.md
+
+Tree-sitter is **optional**. If it isn't installed, :class:`SINASTEdit`
+falls back to a no-op state where :meth:`is_available` returns ``False``
+and :meth:`edit` returns a clear install-hint error. This keeps the
+bundle importable without tree-sitter as a hard dep.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# ── Lazy Tree-sitter Loader ────────────────────────────────────────
+# Tree-sitter is a heavy native dep; we never want to force it on
+# users who only want to import :mod:`sin_code_bundle` for tooling.
+# Lazy import = the bundle works even when tree-sitter is missing
+# (graceful degradation via the ImportError catch below).
+def _try_import_tree_sitter() -> Optional[Any]:
+    try:
+        import tree_sitter  # type: ignore  # noqa: F401
+
+        return tree_sitter
+    except ImportError:
+        return None
+
+
+def _try_import_tree_sitter_languages() -> Optional[Any]:
+    try:
+        from tree_sitter_languages import get_parser  # type: ignore  # noqa: F401
+
+        return get_parser
+    except ImportError:
+        return None
+
+
+# ── ASTEditResult: Edit Outcome ────────────────────────────────────
+class ASTEditResult:
+    """Result of an AST edit operation.
+
+    Attributes:
+        success: True if the proposal phase succeeded.
+        proposed_changes: List of change dicts ready to be applied
+            via :meth:`SINASTEdit.resolve`.
+        poc_verified: True if a POC verification call succeeded.
+        poc_report: The raw POC report (or ``None``).
+        error: Human-readable error message on failure.
+    """
+
+    def __init__(
+        self,
+        success: bool,
+        proposed_changes: Optional[List[Dict[str, Any]]] = None,
+        poc_verified: bool = False,
+        poc_report: Optional[Dict[str, Any]] = None,
+        error: Optional[str] = None,
+    ) -> None:
+        self.success = success
+        self.proposed_changes = proposed_changes or []
+        self.poc_verified = poc_verified
+        self.poc_report = poc_report
+        self.error = error
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to a JSON-safe dict for transport/storage.
+
+        Round-trips through ``json.dumps``/``json.loads``. Strips no
+        fields — every public attribute appears in the dict verbatim
+        (including ``None`` values for unset optional fields).
+        """
+        return {
+            "success": self.success,
+            "proposed_changes": self.proposed_changes,
+            "poc_verified": self.poc_verified,
+            "poc_report": self.poc_report,
+            "error": self.error,
+        }
+
+
+# ── SINASTEdit: Tree-sitter-Powered Edits ───────────────────────────
+class SINASTEdit:
+    """AST-based code editing with tree-sitter and POC verification.
+
+    Usage:
+        ast = SINASTEdit()
+        result = ast.edit(Path("foo.py"), "def old_func():", "def new_func():")
+        if result.success:
+            ast.resolve(Path("foo.py"), result.proposed_changes)
+
+    Tree-sitter must be installed for any real editing::
+
+        pip install tree-sitter tree-sitter-languages
+    """
+
+    # 5 languages we know tree-sitter-languages supports reliably
+    # (this list is conservative — adding a language here is cheap,
+    # but adding one that the installed tree-sitter-languages doesn't
+    # ship just means it silently drops out in _init_parsers below).
+    SUPPORTED_LANGS = {"python", "javascript", "typescript", "go", "rust"}
+
+    def __init__(self, repo_root: Optional[Path] = None) -> None:
+        self.repo_root = repo_root or Path.cwd()
+        self.ts: Optional[Any] = _try_import_tree_sitter()
+        self.get_parser: Optional[Any] = _try_import_tree_sitter_languages()
+        self.parsers: Dict[str, Any] = {}
+        if self.ts is not None and self.get_parser is not None:
+            self._init_parsers()
+
+    def _init_parsers(self) -> None:
+        """Initialize tree-sitter parsers for :data:`SUPPORTED_LANGS`.
+
+        Missing or broken language bindings are skipped silently — the
+        affected language simply won't appear in :attr:`parsers`.
+        """
+        if self.get_parser is None:
+            return
+        for lang in self.SUPPORTED_LANGS:
+            try:
+                self.parsers[lang] = self.get_parser(lang)
+            except Exception:
+                # Individual language failures don't break the whole
+                # module: tree-sitter-languages may not ship every
+                # grammar for every wheel. The user just loses one
+                # language from `is_available()`.
+                pass
+
+    @staticmethod
+    def _detect_language(file_path: Path) -> Optional[str]:
+        # Static because there's no instance state needed — just a
+        # simple extension-to-language mapping table.
+        ext_map = {
+            ".py": "python",
+            ".js": "javascript",
+            ".ts": "typescript",
+            ".go": "go",
+            ".rs": "rust",
+        }
+        return ext_map.get(file_path.suffix)
+
+    def is_available(self, language: Optional[str] = None) -> bool:
+        """Return whether AST editing is available.
+
+        With no ``language`` argument, returns True if *any* supported
+        parser loaded successfully. With a ``language``, returns True
+        only if that specific parser is ready.
+
+        This method intentionally does NOT raise — callers need a
+        safe way to probe support without try/except around every
+        edit attempt.
+        """
+        if self.ts is None or self.get_parser is None:
+            return False
+        if language is None:
+            return bool(self.parsers)
+        return language in self.parsers
+
+    def edit(
+        self,
+        file_path: Path,
+        old_substring: str,
+        replacement: str,
+        verify_with_poc: bool = True,
+    ) -> ASTEditResult:
+        """Propose an AST-based edit.
+
+        Tree-sitter is used to parse the file and confirm the language
+        is supported, but the actual replacement is line-based (the
+        line containing ``old_substring`` is swapped for ``replacement``).
+        That keeps the v1 simple while still validating syntax.
+
+        Install for full AST-precise edits::
+
+            pip install tree-sitter tree-sitter-languages
+        """
+        file_path = Path(file_path)
+        if not file_path.exists():
+            return ASTEditResult(success=False, error=f"File not found: {file_path}")
+        if not self.is_available():
+            return ASTEditResult(
+                success=False,
+                error=(
+                    "tree-sitter not installed. Run: pip install tree-sitter tree-sitter-languages"
+                ),
+            )
+        language = self._detect_language(file_path)
+        if not language or language not in self.parsers:
+            return ASTEditResult(
+                success=False,
+                error=f"Unsupported or unparsed language for: {file_path}",
+            )
+        parser = self.parsers[language]
+
+        code = file_path.read_text()
+        # Parse the whole file — throws away the tree after, but proves
+        # the file is syntactically valid for the chosen language
+        # (tree-sitter's parse() raises on invalid syntax for supported
+        # languages; for our loose mode we just rely on it not raising).
+        parser.parse(bytes(code, "utf-8"))
+
+        if old_substring not in code:
+            return ASTEditResult(
+                success=False,
+                error=f"old_substring not found in {file_path}",
+            )
+        # Line-based replacement (not byte-range): tree-sitter's query
+        # API for surgical byte-range edits is complex and varies by
+        # grammar. For the v1 we use a line-based fallback that still
+        # validates AST context (the parse above) before applying.
+        lines = code.splitlines(keepends=True)
+        target_line: Optional[int] = None
+        for i, line in enumerate(lines):
+            if old_substring in line:
+                target_line = i
+                break
+        if target_line is None:
+            return ASTEditResult(success=False, error="Could not locate line")
+
+        # Preserve line ending of the original line
+        new_line = replacement + ("\n" if lines[target_line].endswith("\n") else "")
+        proposed: List[Dict[str, Any]] = [
+            {
+                "type": "ast_replacement",
+                "line": target_line,
+                "old": lines[target_line],
+                "new": new_line,
+                "language": language,
+            }
+        ]
+
+        poc_verified = False
+        poc_report: Optional[Dict[str, Any]] = None
+        if verify_with_poc:
+            poc_report, poc_verified = self._verify_with_poc()
+        else:
+            poc_report = {"verified": "skipped", "note": "verify_with_poc=False"}
+
+        return ASTEditResult(
+            success=True,
+            proposed_changes=proposed,
+            poc_verified=poc_verified,
+            poc_report=poc_report,
+        )
+
+    def _verify_with_poc(self) -> tuple[Dict[str, Any], bool]:
+        """Best-effort POC verification using the optional ``sin_code_poc``.
+
+        Returns ``(report, verified)``. Never raises; on ImportError
+        reports ``verified: skipped``. On any other failure reports
+        ``verified: failed`` with the error string.
+
+        Note: this is intentionally lenient — POC's exact API may vary
+        across versions, so we capture *presence* (is it installed?)
+        and *size* (how many properties does it expose?) rather than
+        strict semantic verification. Callers needing strict checks
+        should call POC directly.
+        """
+        try:
+            from sin_code_poc import property_metadata  # type: ignore
+
+            props: Any = property_metadata() if callable(property_metadata) else {}
+            n = len(props) if hasattr(props, "__len__") else 0
+            return (
+                {
+                    "verified": "ok",
+                    "note": f"POC available, {n} properties",
+                },
+                True,
+            )
+        except ImportError:
+            return ({"verified": "skipped", "error": "POC not installed"}, False)
+        except Exception as e:  # noqa: BLE001
+            return ({"verified": "failed", "error": str(e)}, False)
+
+    def resolve(self, file_path: Path, changes: List[Dict[str, Any]]) -> bool:
+        """Apply accepted AST changes to a file.
+
+        Changes are applied in reverse line order so earlier line
+        numbers stay valid. The write is atomic via a sibling
+        ``tempfile.NamedTemporaryFile`` + ``Path.replace``.
+
+        Returns True on success, False on any I/O failure.
+        """
+        file_path = Path(file_path)
+        if not file_path.exists():
+            return False
+        code = file_path.read_text()
+        lines = code.splitlines(keepends=True)
+        # Apply changes in reverse order so line numbers stay valid
+        # (editing line 100 first would shift line 50's index if we
+        # went forward — reversing avoids that bookkeeping).
+        sorted_changes = sorted(changes, key=lambda c: c["line"], reverse=True)
+        for change in sorted_changes:
+            idx = change["line"]
+            if 0 <= idx < len(lines):
+                lines[idx] = change["new"]
+        modified = "".join(lines)
+        # Atomic write: tmp in same dir, then replace (sibling-file
+        # rename is atomic on POSIX; same pattern as hashline.py).
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                dir=file_path.parent,
+                delete=False,
+                suffix=".tmp",
+            ) as tmp:
+                tmp.write(modified)
+                tmp_path = Path(tmp.name)
+        except OSError:
+            return False
+        try:
+            tmp_path.replace(file_path)
+            return True
+        except OSError:
+            tmp_path.unlink(missing_ok=True)
+            return False
+
+
+__all__ = ["SINASTEdit", "ASTEditResult"]