atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/emergent_signature_extract.py

@@ -0,0 +1,242 @@
+"""Tier a1 — pure signature harvesting for the Emergent Scan.
+
+Walks a tier-organized package and emits a :class:`SymbolSignatureCard` per
+public callable.  ``inputs`` and ``output`` are the type annotation texts as
+they appear in source — we keep them as strings so the matcher can do
+loose, normalized compatibility comparisons later (no real type system).
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+from ..a0_qk_constants.emergent_types import SymbolSignatureCard
+
+_TIERS = (
+    "a0_qk_constants", "a1_at_functions", "a2_mo_composites",
+    "a3_og_features", "a4_sy_orchestration",
+)
+_PUBLIC = lambda name: not name.startswith("_") or name == "__init__"  # noqa: E731
+
+# Effects we treat as "impure" for the heuristic.  Any function whose body
+# touches one of these is marked ``is_pure=False``.
+_IMPURE_HINTS = {
+    "open", "print", "input", "exec", "eval",
+    "Path", "subprocess", "socket", "requests", "urllib",
+    "logging", "os.system", "os.environ",
+}
+
+
+def _module_for(file: Path, src_root: Path, package: str) -> str:
+    rel = file.relative_to(src_root).with_suffix("")
+    parts = list(rel.parts)
+    if parts and parts[-1] == "__init__":
+        parts.pop()
+    return ".".join([package, *parts]) if parts else package
+
+
+def _tier_of(file: Path, src_root: Path) -> str:
+    parts = file.relative_to(src_root).parts
+    for p in parts:
+        if p in _TIERS:
+            return p
+    return ""
+
+
+def _domain_of(stem: str) -> str:
+    """Heuristic domain tag: pull the last meaningful slug from the file stem.
+
+    ``a1_source_atomadic_v2_cherrypicker`` → ``cherrypicker``.
+    ``commandsmith_render`` → ``commandsmith``.  ``ingest`` → ``ingest``.
+    """
+    cleaned = re.sub(r"^a\d_(?:source_)?", "", stem)
+    cleaned = re.sub(r"^(atomadic_forge_seed_|atomadic_v2_)", "", cleaned)
+    parts = cleaned.split("_")
+    return parts[0].lower() if parts else "misc"
+
+
+def _ann_text(node: ast.AST | None) -> str:
+    if node is None:
+        return "Any"
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return "Any"
+
+
+def _is_pure(fn: ast.AST) -> bool:
+    for child in ast.walk(fn):
+        if isinstance(child, ast.Call):
+            f = child.func
+            if isinstance(f, ast.Name) and f.id in _IMPURE_HINTS:
+                return False
+            if isinstance(f, ast.Attribute):
+                root = f
+                while isinstance(root, ast.Attribute):
+                    root = root.value
+                if isinstance(root, ast.Name) and root.id in _IMPURE_HINTS:
+                    return False
+        if isinstance(child, ast.Global | ast.Nonlocal):
+            return False
+    return True
+
+
+def _docstring_first_line(node: ast.AST) -> str:
+    doc = ast.get_docstring(node) or ""
+    return (doc.strip().split("\n", 1)[0] if doc else "").strip()
+
+
+def _harvest_function(fn: ast.AST, *, module: str, tier: str, domain: str,
+                     class_qualifier: str = "") -> SymbolSignatureCard | None:
+    if not isinstance(fn, ast.FunctionDef | ast.AsyncFunctionDef):
+        return None
+    if not _PUBLIC(fn.name):
+        return None
+    name = fn.name if not class_qualifier else f"{class_qualifier}.{fn.name}"
+    inputs: list[tuple[str, str]] = []
+    for arg in fn.args.args:
+        if arg.arg in ("self", "cls"):
+            continue
+        inputs.append((arg.arg, _ann_text(arg.annotation)))
+    for arg in fn.args.kwonlyargs:
+        inputs.append((arg.arg, _ann_text(arg.annotation)))
+    output = _ann_text(fn.returns)
+    return SymbolSignatureCard(
+        name=name,
+        qualname=f"{module}.{name}",
+        module=module,
+        tier=tier,
+        domain=domain,
+        inputs=inputs,
+        output=output,
+        is_pure=_is_pure(fn),
+        docstring=_docstring_first_line(fn),
+    )
+
+
+def _harvest_one_file(py_file: Path, *, module: str, tier: str,
+                      domain: str) -> list[SymbolSignatureCard]:
+    cards: list[SymbolSignatureCard] = []
+    try:
+        tree = ast.parse(py_file.read_text(encoding="utf-8"))
+    except (SyntaxError, OSError):
+        return cards
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            card = _harvest_function(node, module=module, tier=tier, domain=domain)
+            if card:
+                cards.append(card)
+        elif isinstance(node, ast.ClassDef) and _PUBLIC(node.name):
+            for sub in node.body:
+                if isinstance(sub, ast.FunctionDef | ast.AsyncFunctionDef):
+                    card = _harvest_function(
+                        sub, module=module, tier=tier, domain=domain,
+                        class_qualifier=node.name,
+                    )
+                    if card:
+                        cards.append(card)
+    return cards
+
+
+def _flat_tier_for(py_file: Path) -> str:
+    """Best-effort tier guess for repos without a*_ folders.
+
+    Uses pure naming heuristics from :func:`atomadic_forge.a1_at_functions.ingest.\
+classify_tier` shape — but works on the file alone (good enough for the
+    composition graph; mis-tier doesn't break compatibility).
+    """
+    name = py_file.stem.lower()
+    if any(t in name for t in ("constant", "schema", "manifest", "type", "enum")):
+        return "a0_qk_constants"
+    if any(t in name for t in ("util", "helper", "validator", "parse", "format")):
+        return "a1_at_functions"
+    if any(t in name for t in ("client", "store", "registry", "manager", "core")):
+        return "a2_mo_composites"
+    if any(t in name for t in ("feature", "service", "pipeline", "gate", "tool")):
+        return "a3_og_features"
+    if any(t in name for t in ("cli", "main", "runner", "cmd", "orchestrat")):
+        return "a4_sy_orchestration"
+    return "a1_at_functions"
+
+
+def harvest_signatures(
+    src_root: Path,
+    package: str = "atomadic_forge",
+    tiers: Iterable[str] = _TIERS,
+    *,
+    skip_generated: bool = True,
+) -> list[SymbolSignatureCard]:
+    """Walk every ``a*/`` tier under ``src_root`` and harvest signatures.
+
+    Falls back to **flat mode** if no tier folder is found under
+    ``src_root/package/`` — so emergent-scan also works on legacy / non-ASS-ADE
+    repositories (atomadic-v2-style flat layouts, the ``foo/bar.py`` shape, …).
+    In flat mode each file's tier is guessed from its name and the catalogue
+    contains every public callable under ``src_root``.
+
+    ``skip_generated``: when True, skip files whose stems start with
+    ``a*_source_*`` (verbatim assimilator output).
+    """
+    src_root = Path(src_root)
+    cards: list[SymbolSignatureCard] = []
+    pkg_root = src_root / package
+    have_any_tier = pkg_root.exists() and any(
+        (pkg_root / t).exists() for t in tiers
+    )
+
+    if have_any_tier:
+        for tier in tiers:
+            tdir = pkg_root / tier
+            if not tdir.exists():
+                continue
+            for py_file in sorted(tdir.glob("*.py")):
+                if py_file.name.startswith("_"):
+                    continue
+                if skip_generated and py_file.stem.startswith((
+                        "a0_source_", "a1_source_", "a2_source_",
+                        "a3_source_", "a4_source_")):
+                    continue
+                module = _module_for(py_file, src_root, package)
+                domain = _domain_of(py_file.stem)
+                cards.extend(_harvest_one_file(py_file, module=module,
+                                               tier=tier, domain=domain))
+        return cards
+
+    # ── Flat mode — walk every .py, infer tier from filename heuristics.
+    walk_root = src_root
+    package_for_module = package
+    if not pkg_root.exists():
+        # Caller passed a repo root, not a src layout.  Use the repo as the
+        # walk root and fabricate a one-level package alias from the directory.
+        walk_root = src_root
+        package_for_module = src_root.name.replace("-", "_")
+    for py_file in sorted(walk_root.rglob("*.py")):
+        if py_file.name.startswith("_"):
+            continue
+        # Use parts RELATIVE to walk_root so a hidden parent like
+        # ``.pytest_basetemp`` doesn't accidentally exclude every test fixture.
+        try:
+            rel_parts = py_file.relative_to(walk_root).parts
+        except ValueError:
+            rel_parts = py_file.parts
+        if any(part.startswith((".", "__pycache__")) for part in rel_parts):
+            continue
+        if any(part in {"tests", "test", "build", "dist", ".venv", "venv"}
+               for part in rel_parts):
+            continue
+        try:
+            rel = py_file.relative_to(walk_root).with_suffix("")
+            module_parts = list(rel.parts)
+            if module_parts and module_parts[-1] == "__init__":
+                module_parts.pop()
+            module = ".".join([package_for_module, *module_parts]) if module_parts else package_for_module
+        except ValueError:
+            module = package_for_module
+        tier = _flat_tier_for(py_file)
+        domain = _domain_of(py_file.stem)
+        cards.extend(_harvest_one_file(py_file, module=module,
+                                       tier=tier, domain=domain))
+    return cards

atomadic_forge/a1_at_functions/emergent_synthesize.py

@@ -0,0 +1,88 @@
+"""Tier a1 — pure source synthesiser for an :class:`EmergentCandidateCard`.
+
+Renders a Python module that wires the chain's components together as a new
+feature.  The generator is conservative: it imports each step by qualname,
+calls them in order, and returns a typed result dict.  Manual review is
+expected — this is scaffolding, not a finished feature.
+"""
+
+from __future__ import annotations
+
+from ..a0_qk_constants.emergent_types import EmergentCandidateCard
+
+
+def _imports_for(chain_qualnames: list[str]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for q in chain_qualnames:
+        module, _, name = q.rpartition(".")
+        # qualnames may include a class-qualified method (``Mod.Class.method``).
+        if "." in name:  # method case
+            continue
+        line = f"from {module} import {name}"
+        if line in seen:
+            continue
+        seen.add(line)
+        out.append(line)
+    return out
+
+
+def render_emergent_feature(card: EmergentCandidateCard) -> str:
+    chain = card["chain"]
+    qualnames = chain["chain"]
+    bridges = chain["bridges"]
+    name = card["name"].replace("-", "_")
+    imports = _imports_for(qualnames)
+    summary = card["summary"].replace('"""', "'''")
+    novelty = "; ".join(card["novelty_signals"]) or "(none)"
+    score = card["score"]
+    breakdown = ", ".join(f"{k}={v:g}" for k, v in card["score_breakdown"].items())
+
+    lines: list[str] = [
+        '"""',
+        f"Auto-synthesized by ``atomadic-forge emergent synthesize {card['candidate_id']}``.",
+        "",
+        f"Suggested name: {card['name']}",
+        f"Suggested tier: {card['suggested_tier']}",
+        f"Score:          {score:.0f}  ({breakdown})",
+        f"Novelty:        {novelty}",
+        "",
+        "Composition chain:",
+    ]
+    for i, q in enumerate(qualnames):
+        lines.append(f"  {i+1}. {q}")
+        if i < len(bridges):
+            lines.append(f"     -- output: {bridges[i]} -->")
+    lines.extend([
+        '"""',
+        "",
+        "from __future__ import annotations",
+        "",
+        "from typing import Any",
+        "",
+    ])
+    lines.extend(imports)
+    lines.append("")
+    lines.append(f"def run_{name}(seed: Any) -> dict[str, Any]:")
+    lines.append(f'    """Wired composition for {card["name"]}.')
+    lines.append("")
+    lines.append(f"    Summary: {summary}")
+    lines.append('    """')
+    lines.append("    trace: list[Any] = []")
+    lines.append("    value = seed")
+    for i, q in enumerate(qualnames):
+        _module, _, callable_name = q.rpartition(".")
+        if "." in callable_name:
+            # method case — fall back to a noop trace step rather than guessing
+            # the receiver.  Manual wiring required.
+            lines.append(
+                f"    # NOTE: step {i+1} is a method ({callable_name}); "
+                "wire the receiver manually."
+            )
+            lines.append(f"    trace.append(({q!r}, 'unwired-method'))")
+            continue
+        lines.append(f"    value = {callable_name}(value)")
+        lines.append(f"    trace.append(({q!r}, value))")
+    lines.append("    return {'final': value, 'trace': trace}")
+    lines.append("")
+    return "\n".join(lines) + "\n"

atomadic_forge/a1_at_functions/enforce_planner.py

@@ -0,0 +1,208 @@
+"""Tier a1 — pure planner for ``forge enforce``.
+
+Golden Path Lane A W6 deliverable. Consumes a wire report with W5
+F-codes attached and emits a list of mechanical fix actions. Pure:
+the planner reads the wire report and inspects file paths only — it
+does NOT mutate anything. Application is a separate concern (see
+``a3/forge_enforce.py``).
+
+Action shape:
+    {
+        "f_code":      "F0042",
+        "action":      "move_file_up",
+        "src":         "a1_at_functions/helper.py",
+        "dest":        "a3_og_features/helper.py",
+        "violations":  [<wire violation dict>, ...],
+        "auto_apply":  true,
+        "warnings":    [str, ...],   # populated when the move has risks
+    }
+
+The planner today implements one action: ``move_file_up`` for the six
+canonical upward-import F-codes (F0041–F0046). F0040 (a0 importing
+anything) and F0049 (unknown-shape) are emitted as ``review_manually``
+actions with no auto_apply.
+
+Pre-flight risks the planner detects (and surfaces as warnings, not
+exceptions):
+  * the destination path already exists (would clobber)
+  * the source file has multiple distinct destination tiers across
+    its violations (ambiguous; safest is review)
+  * the source file is itself imported by other files in the package
+    (those callers' imports would need rewriting — out of scope for
+    W6 v1; W7 will own this)
+"""
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from pathlib import Path
+from typing import TypedDict
+
+
+class EnforceAction(TypedDict, total=False):
+    """One proposed mechanical fix. See module docstring."""
+    f_code: str
+    action: str             # 'move_file_up' | 'review_manually'
+    src: str                # repo-relative posix path
+    dest: str               # repo-relative posix path (move target)
+    violations: list[dict]
+    auto_apply: bool
+    warnings: list[str]
+
+
+def _file_imports_in_package(
+    package_root: Path,
+    target_relpath: str,
+) -> list[str]:
+    """Return repo-relative paths of files that import the target.
+
+    Heuristic: looks for ``from <…>.target_module_name import``
+    or ``from <…>.target_module_name`` patterns where target_module_name
+    is the file stem of ``target_relpath``. Cheap regex-quality
+    proxy for a real symbol-resolution pass; the W6 acceptance is
+    "smoke covers 7 fix paths", not "full inbound-edge analysis".
+
+    Used purely to populate ``warnings`` when a move could break
+    inbound callers — the planner does not block on this signal.
+    """
+    target = Path(target_relpath)
+    stem = target.stem
+    if not stem or stem.startswith("_"):
+        return []
+    out: list[str] = []
+    for f in package_root.rglob("*.py"):
+        if f.is_dir():
+            continue
+        rel = f.relative_to(package_root).as_posix()
+        if rel == target_relpath:
+            continue
+        try:
+            text = f.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if f"import {stem}" not in text and f".{stem}" not in text:
+            continue
+        # Confirm via AST so we don't trip on string literals.
+        try:
+            tree = ast.parse(text, filename=str(f))
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom):
+                module = (node.module or "").split(".")
+                if stem in module:
+                    out.append(rel)
+                    break
+                if any(alias.name == stem for alias in node.names):
+                    out.append(rel)
+                    break
+            elif isinstance(node, ast.Import):
+                if any(alias.name.endswith("." + stem) or alias.name == stem
+                       for alias in node.names):
+                    out.append(rel)
+                    break
+    return sorted(set(out))
+
+
+def plan_actions(
+    wire_report: dict,
+    *,
+    package_root: Path | None = None,
+) -> list[EnforceAction]:
+    """Group violations by file and emit one EnforceAction per file.
+
+    A file with multiple violations to the same higher tier yields a
+    single move action covering them all. A file with violations to
+    DIFFERENT tiers gets a review_manually action with warnings.
+
+    ``package_root`` (optional): when provided, the planner inspects
+    inbound imports across the package and adds warnings; without it
+    the action's warnings list stays empty.
+    """
+    by_file: dict[str, list[dict]] = defaultdict(list)
+    for v in wire_report.get("violations", []) or []:
+        by_file[v["file"]].append(v)
+
+    actions: list[EnforceAction] = []
+    for file_path, viols in sorted(by_file.items()):
+        f_codes = {v.get("f_code", "") for v in viols}
+        to_tiers = {v["to_tier"] for v in viols}
+        # F0040 / F0049: not auto-fixable.
+        if "F0040" in f_codes or "F0049" in f_codes or not f_codes:
+            actions.append(EnforceAction(
+                f_code=next(iter(f_codes)) if f_codes else "F0049",
+                action="review_manually",
+                src=file_path,
+                dest="",
+                violations=viols,
+                auto_apply=False,
+                warnings=[
+                    "violation requires manual review (a0 special-case "
+                    "or non-canonical tier shape)",
+                ],
+            ))
+            continue
+        # Multiple distinct destination tiers: ambiguous.
+        if len(to_tiers) > 1:
+            actions.append(EnforceAction(
+                f_code=sorted(f_codes)[0],
+                action="review_manually",
+                src=file_path,
+                dest="",
+                violations=viols,
+                auto_apply=False,
+                warnings=[
+                    f"file imports from multiple higher tiers ({sorted(to_tiers)}); "
+                    "no single mechanical destination — review manually",
+                ],
+            ))
+            continue
+        # Single canonical move.
+        target_tier = next(iter(to_tiers))
+        src = file_path
+        dest = f"{target_tier}/{Path(src).name}"
+        warnings: list[str] = []
+        if package_root is not None:
+            try:
+                inbound = _file_imports_in_package(package_root, src)
+            except OSError:
+                inbound = []
+            if inbound:
+                warnings.append(
+                    f"{len(inbound)} other file(s) import this module — "
+                    "their imports will need rewriting after the move: "
+                    + ", ".join(inbound[:5])
+                    + ("…" if len(inbound) > 5 else "")
+                )
+            dest_path = package_root / dest
+            if dest_path.exists():
+                warnings.append(
+                    f"destination {dest} already exists; move would clobber"
+                )
+        actions.append(EnforceAction(
+            f_code=sorted(f_codes)[0],
+            action="move_file_up",
+            src=src,
+            dest=dest,
+            violations=viols,
+            auto_apply=not warnings,
+            warnings=warnings,
+        ))
+    return actions
+
+
+def summarize_plan(actions: list[EnforceAction]) -> dict:
+    """Reduce a plan to summary stats. Used by CLI human + JSON output."""
+    auto = sum(1 for a in actions if a.get("auto_apply"))
+    review = sum(1 for a in actions if not a.get("auto_apply"))
+    by_fcode: dict[str, int] = defaultdict(int)
+    for a in actions:
+        by_fcode[a.get("f_code", "F????")] += 1
+    return {
+        "schema_version": "atomadic-forge.enforce.plan/v1",
+        "action_count": len(actions),
+        "auto_apply_count": auto,
+        "review_count": review,
+        "by_fcode": dict(sorted(by_fcode.items())),
+        "actions": list(actions),
+    }

atomadic_forge/a1_at_functions/error_hints.py

@@ -0,0 +1,105 @@
+"""Tier a1 — named error-message templates with concrete recovery commands.
+
+Audit pain point (Lane B4): every CLI error should end with a suggested
+next step. ``GEMINI_API_KEY not set`` becomes ``GEMINI_API_KEY not set
+— here are three ways to recover``. The point is: a developer who
+just installed Forge should never have to alt-tab to Stack Overflow.
+
+This module is pure: it returns formatted strings. The CLI layer
+decides whether to ``typer.echo`` them, fold them into a
+``typer.BadParameter``, or pipe them through structured JSON output.
+
+Templates are looked up by stable name (e.g. ``provider_missing_key``)
+so call sites can pass a dict of substitutions and we centralize wording
+without touching every command. Adding a hint:
+
+    HINT_TEMPLATES["my_new_hint"] = '''… {var} …'''
+    format_hint("my_new_hint", var="x")
+"""
+from __future__ import annotations
+
+HINT_TEMPLATES: dict[str, str] = {
+    # ----- LLM provider errors -------------------------------------------
+    "provider_missing_key": (
+        "{provider!s} is selected but its API key is not set.\n"
+        "\n"
+        "Recovery options:\n"
+        "  1. Set the key:           export {env_var!s}=<your-key>\n"
+        "  2. Get a free Gemini key: https://aistudio.google.com/apikey\n"
+        "  3. Use local Ollama:      export FORGE_OLLAMA=1 && "
+        "ollama pull qwen2.5-coder:7b\n"
+        "  4. Use the offline stub:  --provider stub  (for tests / CI)\n"
+        "\n"
+        "Verify with: forge config test --provider {provider!s}"
+    ),
+    # ----- Wire / tier errors --------------------------------------------
+    "no_tier_dirs": (
+        "No tier directories were found at {path!s}.\n"
+        "\n"
+        "Expected at least three of:\n"
+        "  a0_qk_constants/   a1_at_functions/   a2_mo_composites/\n"
+        "  a3_og_features/    a4_sy_orchestration/\n"
+        "\n"
+        "Did you forget to materialize? Try:\n"
+        "  forge auto <source-repo> {path!s} --apply --package <name>\n"
+    ),
+    "wire_fail_with_violations": (
+        "Wire scan found {count} upward-import violation(s).\n"
+        "\n"
+        "Recovery options:\n"
+        "  1. Get repair suggestions: forge wire {path!s} --suggest-repairs\n"
+        "  2. Get a JSON report:      forge wire {path!s} --json > wire.json\n"
+        "  3. Gate this in CI:        forge wire {path!s} --fail-on-violations\n"
+    ),
+    # ----- Certify errors -------------------------------------------------
+    "certify_below_threshold": (
+        "Certify score {score}/100 is below the {threshold}/100 gate.\n"
+        "\n"
+        "Inspect what failed and the cheapest path to recover:\n"
+        "  forge certify {path!s} --json | python -m json.tool\n"
+        "\n"
+        "Common quick wins:\n"
+        "  - documentation: add a README.md (free 25 points)\n"
+        "  - tests:         add tests/test_*.py (free 25 points)\n"
+        "  - imports:       forge wire {path!s} --suggest-repairs\n"
+    ),
+    "fail_under_out_of_range": (
+        "--fail-under must be between 0 and 100. Got: {value!r}\n"
+        "\n"
+        "Common values:\n"
+        "  --fail-under 75   # team-grade target\n"
+        "  --fail-under 90   # release-grade target\n"
+    ),
+    # ----- Manifest / file errors ----------------------------------------
+    "not_a_forge_manifest": (
+        "{path!s}: not a Forge JSON manifest.\n"
+        "\n"
+        "Expected a JSON object whose top-level `schema_version` field "
+        "starts with `atomadic-forge.` (e.g. `atomadic-forge.scout/v1`, "
+        "`atomadic-forge.wire/v1`, etc.).\n"
+        "\n"
+        "Forge manifests are written under .atomadic-forge/ when you run\n"
+        "  forge auto / forge recon / forge cherry / forge finalize\n"
+        "with --apply or pass through ManifestStore."
+    ),
+}
+
+
+def format_hint(name: str, /, **fmt: object) -> str:
+    """Return the named hint template with ``fmt`` substituted in.
+
+    Raises KeyError on unknown hint names so typos surface in tests
+    rather than at runtime in front of users.
+    """
+    if name not in HINT_TEMPLATES:
+        raise KeyError(f"unknown hint template: {name!r}")
+    return HINT_TEMPLATES[name].format(**fmt)
+
+
+def hint_lines(name: str, /, **fmt: object) -> list[str]:
+    """Same as ``format_hint`` but returns the lines as a list.
+
+    Useful when a caller wants to prepend ``    `` to indent the hint
+    inside a larger error block.
+    """
+    return format_hint(name, **fmt).splitlines()