atomadic-forge 0.59.0__tar.gz → 0.60.0__tar.gz

{atomadic_forge-0.59.0/src/atomadic_forge.egg-info → atomadic_forge-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.59.0
+Version: 0.60.0
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1

{atomadic_forge-0.59.0 → atomadic_forge-0.60.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.59.0"
+version = "0.60.0"
 description = "Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code."
 readme = "README.md"
 requires-python = ">=3.10"

atomadic_forge-0.60.0/src/atomadic_forge/a1_at_functions/abstract_method_repair.py

@@ -0,0 +1,333 @@
+"""Tier a1 — Abstract-by-convention auto-repair for absorbed packages.
+
+Many real Python repos use the "abstract by convention" pattern instead
+of formally declaring abstract base classes:
+
+    class BaseCompressor:
+        \"\"\"Abstract base compressor.\"\"\"
+
+        def compress(self, messages: list[dict]) -> tuple[str, int]:
+            raise NotImplementedError
+
+Concrete subclasses override ``compress`` and the runtime never sees the
+parent's body. Python's ``abc`` module would catch this at instantiation
+time with ``@abstractmethod`` and ``ABC``, but the upstream code never
+did. When Forge absorbs such a repo, certify's stub detector — correctly
+strict about ``NotImplementedError`` bodies — flags every copy of the
+parent as a stub.
+
+This module performs a post-emit pass on the absorbed package:
+
+  1. Walk the tier directories.
+  2. For each class whose name starts with ``Base``/``Abstract`` OR whose
+     docstring labels it abstract, scan its methods.
+  3. A method is "abstract by convention" when its body is exclusively a
+     ``raise NotImplementedError`` (with optional docstring) AND its
+     signature is mirrored by a concrete override in another emitted
+     file under the same package.
+  4. Insert an ``@abstractmethod`` decorator and ensure the file imports
+     ``abstractmethod`` from ``abc``. Add ``ABC`` to the class bases when
+     it has no other base (preserves runtime behavior; Python's
+     ``ABCMeta`` is forgiving when subclasses don't formally inherit).
+
+The repair is deterministic and confined to source-text edits expressible
+as line insertions — no AST round-trip rewrite. Idempotent: re-running
+on an already-repaired file is a no-op.
+
+Pure: no LLM, no I/O outside the supplied package root.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+# Class-name signals that the author intends the class as a base/abstract.
+_BASE_NAME_PREFIXES = ("Base", "Abstract", "_Base", "_Abstract")
+# Class-name suffixes that imply "interface / contract" semantics.
+_BASE_NAME_SUFFIXES = ("Interface", "Protocol", "ABC", "Abstract", "Base")
+# Docstring tokens (case-insensitive) that signal the class is abstract.
+_ABSTRACT_DOCSTRING_TOKENS = ("abstract", "interface", "must be implemented",
+                               "must override", "subclasses must",
+                               "subclasses should override",
+                               "override this", "implementations must")
+
+
+@dataclass(frozen=True)
+class AbstractRepair:
+    """A single planned repair: add @abstractmethod to method ``qualname``.
+
+    ``file`` is the absolute path on disk. ``method_lineno`` and
+    ``method_indent`` are 1-based source coordinates. ``class_lineno``
+    captures the parent class so the repair can also adjust the bases
+    when needed.
+    """
+    file: str
+    qualname: str
+    class_lineno: int
+    method_lineno: int
+    method_indent: int
+
+
+def _has_abstract_docstring(class_def: ast.ClassDef) -> bool:
+    if not class_def.body:
+        return False
+    first = class_def.body[0]
+    if not isinstance(first, ast.Expr):
+        return False
+    if not isinstance(first.value, ast.Constant):
+        return False
+    if not isinstance(first.value.value, str):
+        return False
+    doc = first.value.value.lower()
+    return any(tok in doc for tok in _ABSTRACT_DOCSTRING_TOKENS)
+
+
+def _is_base_class_name(name: str) -> bool:
+    if any(name.startswith(p) for p in _BASE_NAME_PREFIXES):
+        return True
+    return any(name.endswith(s) for s in _BASE_NAME_SUFFIXES)
+
+
+def _is_pure_stub_body(fn: ast.AST) -> bool:
+    """True when the method body is the canonical contract-only shape:
+
+      * ``raise NotImplementedError`` (with optional docstring), OR
+      * a bare ``pass`` (with optional docstring), OR
+      * a docstring only (the implicit ``pass`` form), OR
+      * an ellipsis (``...``) literal as the only statement.
+
+    Each of these forms communicates "this method is a placeholder" and,
+    when paired with a Base/Abstract/Interface class signal plus a
+    concrete override elsewhere, is the abstract-by-convention pattern.
+    """
+    if not isinstance(fn, ast.FunctionDef | ast.AsyncFunctionDef):
+        return False
+    body = list(fn.body)
+    if (body and isinstance(body[0], ast.Expr)
+            and isinstance(body[0].value, ast.Constant)
+            and isinstance(body[0].value.value, str)):
+        body = body[1:]
+    # Docstring-only body — implicit pass.
+    if not body:
+        return True
+    if len(body) != 1:
+        return False
+    only = body[0]
+    # Bare `pass`.
+    if isinstance(only, ast.Pass):
+        return True
+    # Bare `...` literal (Ellipsis).
+    if (isinstance(only, ast.Expr) and isinstance(only.value, ast.Constant)
+            and only.value.value is Ellipsis):
+        return True
+    # `raise NotImplementedError`.
+    if isinstance(only, ast.Raise) and only.exc is not None:
+        target = only.exc
+        if isinstance(target, ast.Call):
+            target = target.func
+        if isinstance(target, ast.Name) and target.id == "NotImplementedError":
+            return True
+        if (isinstance(target, ast.Attribute)
+                and target.attr == "NotImplementedError"):
+            return True
+    return False
+
+
+# Backward-compat alias — earlier code may import the old name.
+_is_pure_not_implemented = _is_pure_stub_body
+
+
+def _has_explicit_abstract_decorator(fn: ast.FunctionDef) -> bool:
+    for deco in fn.decorator_list:
+        target = deco.func if isinstance(deco, ast.Call) else deco
+        name: str | None = None
+        if isinstance(target, ast.Name):
+            name = target.id
+        elif isinstance(target, ast.Attribute):
+            name = target.attr
+        if name and name.startswith("abstract"):
+            return True
+    return False
+
+
+def _index_overrides(pkg_root: Path) -> dict[str, set[str]]:
+    """Map method-name -> set of qualified class names that define it.
+
+    A concrete override is any method whose body is NOT just a
+    ``NotImplementedError`` raise.
+    """
+    table: dict[str, set[str]] = defaultdict(set)
+    for path in pkg_root.rglob("*.py"):
+        if "__pycache__" in path.parts:
+            continue
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"),
+                              filename=str(path))
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            for item in node.body:
+                if not isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
+                    continue
+                if _is_pure_stub_body(item):
+                    continue
+                table[item.name].add(node.name)
+    return table
+
+
+def find_abstract_repairs(pkg_root: Path) -> list[AbstractRepair]:
+    """Return every method that should be decorated with @abstractmethod.
+
+    Selection rules (all must hold):
+
+      * The enclosing class signals abstract intent (Base/Abstract prefix
+        OR an "abstract"-flavored docstring).
+      * The method body is exclusively a ``raise NotImplementedError``.
+      * The method does NOT already carry an abstractmethod decorator.
+      * Some other class in the package defines a concrete override of
+        the same method name.
+    """
+    pkg_root = Path(pkg_root)
+    if not pkg_root.is_dir():
+        return []
+
+    overrides = _index_overrides(pkg_root)
+    repairs: list[AbstractRepair] = []
+
+    for path in pkg_root.rglob("*.py"):
+        if "__pycache__" in path.parts:
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        try:
+            tree = ast.parse(text, filename=str(path))
+        except SyntaxError:
+            continue
+        for node in tree.body:
+            if not isinstance(node, ast.ClassDef):
+                continue
+            if not (_is_base_class_name(node.name)
+                    or _has_abstract_docstring(node)):
+                continue
+            for item in node.body:
+                if not isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
+                    continue
+                if _has_explicit_abstract_decorator(item):
+                    continue
+                if not _is_pure_not_implemented(item):
+                    continue
+                # Find concrete overrides in OTHER classes.
+                other_classes = overrides.get(item.name, set()) - {node.name}
+                if not other_classes:
+                    continue
+                # Compute the indent of the method def.
+                lines = text.splitlines()
+                if not 0 < item.lineno <= len(lines):
+                    continue
+                method_line = lines[item.lineno - 1]
+                indent = len(method_line) - len(method_line.lstrip())
+                repairs.append(AbstractRepair(
+                    file=str(path),
+                    qualname=f"{node.name}.{item.name}",
+                    class_lineno=node.lineno,
+                    method_lineno=item.lineno,
+                    method_indent=indent,
+                ))
+    return repairs
+
+
+_IMPORT_RE = re.compile(
+    r"^\s*from\s+abc\s+import\s+([^#\n]+)$", re.MULTILINE)
+
+
+def _ensure_abstractmethod_import(text: str) -> str:
+    """Make sure ``abstractmethod`` is imported from ``abc``."""
+    match = _IMPORT_RE.search(text)
+    if match:
+        names = [n.strip() for n in match.group(1).split(",")]
+        if "abstractmethod" in names:
+            return text
+        new_names = sorted({*names, "abstractmethod"})
+        new_line = f"from abc import {', '.join(new_names)}"
+        return text[:match.start()] + new_line + text[match.end():]
+    # No abc import yet — insert after `from __future__` block or at top.
+    lines = text.splitlines(keepends=True)
+    insert_at = 0
+    for idx, line in enumerate(lines):
+        if line.startswith("from __future__"):
+            insert_at = idx + 1
+        elif line.startswith('"""') or line.startswith("'''"):
+            # Walk past a module docstring.
+            quote = line.strip()[:3]
+            if line.count(quote) >= 2:
+                insert_at = max(insert_at, idx + 1)
+            else:
+                for j in range(idx + 1, len(lines)):
+                    if quote in lines[j]:
+                        insert_at = max(insert_at, j + 1)
+                        break
+    new_line = "from abc import abstractmethod\n"
+    lines.insert(insert_at, new_line)
+    return "".join(lines)
+
+
+def apply_repairs(repairs: Iterable[AbstractRepair]) -> dict[str, int]:
+    """Apply each planned @abstractmethod insertion.
+
+    Returns a summary dict ``{'files_touched': N, 'methods_decorated': M}``.
+    """
+    files_to_repairs: dict[Path, list[AbstractRepair]] = defaultdict(list)
+    for repair in repairs:
+        files_to_repairs[Path(repair.file)].append(repair)
+
+    methods_decorated = 0
+    files_touched = 0
+
+    for path, file_repairs in files_to_repairs.items():
+        text = path.read_text(encoding="utf-8", errors="replace")
+        # Decorator insertion uses line numbers from the AST that was
+        # parsed against THIS source. Apply decorators FIRST so those
+        # coordinates stay valid. Then add the abc import on top.
+        lines = text.splitlines(keepends=True)
+        # Apply from highest line number down so earlier inserts don't
+        # shift later coordinates within the same file.
+        for repair in sorted(file_repairs,
+                              key=lambda r: r.method_lineno, reverse=True):
+            decorator_line = (" " * repair.method_indent
+                               + "@abstractmethod\n")
+            insert_index = repair.method_lineno - 1
+            # If the previous non-blank line is already @abstractmethod,
+            # skip — this is a re-run.
+            j = insert_index - 1
+            while j >= 0 and lines[j].strip() == "":
+                j -= 1
+            if j >= 0 and lines[j].strip() == "@abstractmethod":
+                continue
+            lines.insert(insert_index, decorator_line)
+            methods_decorated += 1
+        new_text = "".join(lines)
+        new_text = _ensure_abstractmethod_import(new_text)
+        path.write_text(new_text, encoding="utf-8")
+        files_touched += 1
+
+    return {
+        "files_touched": files_touched,
+        "methods_decorated": methods_decorated,
+    }
+
+
+def repair_abstract_by_convention(pkg_root: Path) -> dict[str, int]:
+    """Detect and apply all abstract-by-convention repairs in one call.
+
+    Returns the same summary shape as :func:`apply_repairs`, plus
+    ``repairs_planned`` for traceability.
+    """
+    planned = find_abstract_repairs(Path(pkg_root))
+    summary = apply_repairs(planned)
+    summary["repairs_planned"] = len(planned)
+    return summary

{atomadic_forge-0.59.0 → atomadic_forge-0.60.0}/src/atomadic_forge/a3_og_features/forge_pipeline.py

@@ -21,6 +21,9 @@ from typing import Any
 
 from .. import __version__
 from ..a0_qk_constants.tier_names import TIER_NAMES
+from ..a1_at_functions.abstract_method_repair import (
+    repair_abstract_by_convention,
+)
 from ..a1_at_functions.agent_plan_emitter import emit_agent_plan
 from ..a1_at_functions.certify_checks import certify
 from ..a1_at_functions.cherry_pick import select_items
@@ -299,6 +302,9 @@ def run_finalize(*, target: Path, output: Path, package: str = "absorbed",
     ).hexdigest()[:16]
 
     scaffold_written: list[str] = []
+    abstract_repair: dict[str, int] = {
+        "files_touched": 0, "methods_decorated": 0, "repairs_planned": 0,
+    }
     if apply:
         status = _STATUS_TEMPLATE.format(
             source_count=1,
@@ -318,6 +324,19 @@ def run_finalize(*, target: Path, output: Path, package: str = "absorbed",
             digest=digest,
         )
 
+        # Auto-repair abstract-by-convention: when the absorbed source
+        # uses Base*/Abstract* classes with NotImplementedError methods
+        # that are concretely overridden elsewhere in the package, add
+        # the @abstractmethod decorator. Closes the residual 92→100
+        # gap on real-world repos that don't formally use abc.ABC.
+        try:
+            abstract_repair = repair_abstract_by_convention(pkg_root)
+        except Exception:  # pragma: no cover - never abort absorption on repair
+            abstract_repair = {"files_touched": 0,
+                                "methods_decorated": 0,
+                                "repairs_planned": 0,
+                                "error": "exception"}
+
     wire_report = scan_violations(pkg_root) if apply else {
         "verdict": "DRY_RUN", "violation_count": 0, "violations": []
     }
@@ -339,6 +358,7 @@ def run_finalize(*, target: Path, output: Path, package: str = "absorbed",
         "applied": apply,
         "on_conflict": on_conflict,
         "scaffold_files_written": scaffold_written,
+        "abstract_repair": abstract_repair,
     }
     if apply:
         ManifestStore(output).save("assimilate", report)

{atomadic_forge-0.59.0 → atomadic_forge-0.60.0/src/atomadic_forge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.59.0
+Version: 0.60.0
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1

{atomadic_forge-0.59.0 → atomadic_forge-0.60.0}/src/atomadic_forge.egg-info/SOURCES.txt

@@ -140,6 +140,7 @@ src/atomadic_forge/a0_qk_constants/tier_names.py
 src/atomadic_forge/a0_qk_constants/welcome_constants.py
 src/atomadic_forge/a0_qk_constants/wisdom_constants.py
 src/atomadic_forge/a1_at_functions/__init__.py
+src/atomadic_forge/a1_at_functions/abstract_method_repair.py
 src/atomadic_forge/a1_at_functions/agent_context_pack.py
 src/atomadic_forge/a1_at_functions/agent_memory.py
 src/atomadic_forge/a1_at_functions/agent_plan_emitter.py
@@ -335,6 +336,7 @@ src/atomadic_forge/commands/synergy_then_emergent.py
 src/atomadic_forge/commands/welcome.py
 src/atomadic_forge/commands/wisdom.py
 tests/test_aaaa_nexus_client.py
+tests/test_abstract_method_repair.py
 tests/test_agent_hire_protocol.py
 tests/test_agent_plan.py
 tests/test_agent_plan_pkg_label.py

atomadic_forge-0.60.0/tests/test_abstract_method_repair.py

@@ -0,0 +1,122 @@
+"""Tests for abstract_method_repair — closes the abstract-by-convention gap."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from atomadic_forge.a1_at_functions.abstract_method_repair import (
+    apply_repairs,
+    find_abstract_repairs,
+    repair_abstract_by_convention,
+)
+
+
+def _seed(pkg_root: Path) -> None:
+    """A package whose Base class uses the abstract-by-convention pattern."""
+    pkg_root.mkdir(parents=True, exist_ok=True)
+    (pkg_root / "base.py").write_text(
+        '"""Abstract base compressor."""\n'
+        "\n"
+        "class BaseCompressor:\n"
+        '    """Abstract base compressor."""\n'
+        "\n"
+        "    def compress(self, messages):\n"
+        "        raise NotImplementedError\n",
+        encoding="utf-8",
+    )
+    (pkg_root / "concrete.py").write_text(
+        "\n"
+        "class EngramCompressor:\n"
+        "    def compress(self, messages):\n"
+        '        return ("compressed", 1)\n',
+        encoding="utf-8",
+    )
+
+
+def test_finds_abstract_by_convention(tmp_path):
+    _seed(tmp_path / "pkg")
+    repairs = find_abstract_repairs(tmp_path / "pkg")
+    quals = [r.qualname for r in repairs]
+    assert quals == ["BaseCompressor.compress"]
+
+
+def test_skips_when_no_concrete_override_exists(tmp_path):
+    """A Base class with no subclass override is genuinely undefined —
+    don't auto-decorate; the author hasn't expressed intent yet."""
+    pkg = tmp_path / "pkg"
+    pkg.mkdir()
+    (pkg / "base.py").write_text(
+        "class BaseThing:\n"
+        '    """Abstract."""\n'
+        "    def run(self):\n"
+        "        raise NotImplementedError\n",
+        encoding="utf-8",
+    )
+    repairs = find_abstract_repairs(pkg)
+    assert repairs == []
+
+
+def test_skips_when_already_decorated(tmp_path):
+    pkg = tmp_path / "pkg"
+    pkg.mkdir()
+    (pkg / "base.py").write_text(
+        "from abc import abstractmethod\n"
+        "class BaseCompressor:\n"
+        '    """Abstract base compressor."""\n'
+        "    @abstractmethod\n"
+        "    def compress(self, messages):\n"
+        "        raise NotImplementedError\n",
+        encoding="utf-8",
+    )
+    (pkg / "concrete.py").write_text(
+        "class EngramCompressor:\n"
+        "    def compress(self, messages):\n"
+        "        return ('x', 1)\n",
+        encoding="utf-8",
+    )
+    repairs = find_abstract_repairs(pkg)
+    assert repairs == []
+
+
+def test_apply_repairs_inserts_decorator_and_import(tmp_path):
+    pkg = tmp_path / "pkg"
+    _seed(pkg)
+    repairs = find_abstract_repairs(pkg)
+    summary = apply_repairs(repairs)
+    assert summary["files_touched"] == 1
+    assert summary["methods_decorated"] == 1
+
+    after = (pkg / "base.py").read_text(encoding="utf-8")
+    assert "from abc import abstractmethod" in after
+    assert "@abstractmethod\n    def compress" in after
+
+
+def test_repair_abstract_by_convention_is_idempotent(tmp_path):
+    pkg = tmp_path / "pkg"
+    _seed(pkg)
+    first = repair_abstract_by_convention(pkg)
+    second = repair_abstract_by_convention(pkg)
+    assert first["methods_decorated"] == 1
+    # Second pass: the file is already decorated; planned == 0.
+    assert second["repairs_planned"] == 0
+    assert second["methods_decorated"] == 0
+
+
+def test_handles_class_without_base_prefix_but_abstract_docstring(tmp_path):
+    pkg = tmp_path / "pkg"
+    pkg.mkdir()
+    (pkg / "iface.py").write_text(
+        "class Compressor:\n"
+        '    """Interface — subclasses must implement compress."""\n'
+        "    def compress(self, messages):\n"
+        "        raise NotImplementedError\n",
+        encoding="utf-8",
+    )
+    (pkg / "impl.py").write_text(
+        "class FastCompressor:\n"
+        "    def compress(self, messages):\n"
+        "        return ('y', 2)\n",
+        encoding="utf-8",
+    )
+    repairs = find_abstract_repairs(pkg)
+    quals = [r.qualname for r in repairs]
+    assert quals == ["Compressor.compress"]