atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/rollback_planner.py

@@ -0,0 +1,147 @@
+"""Tier a1 — rollback_plan: reversible-move guidance (Codex #11).
+
+Codex's prescription:
+
+  > Agents need reversible moves. rollback_plan({changed_files})
+  > returns: generated files to remove, caches to clean, docs to
+  > restore, tests to rerun, risk of rollback.
+
+Pure heuristic: classifies each changed file by extension + path
+shape and returns a structured undo plan. The agent decides whether
+to apply the moves; this is advisory.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+SCHEMA_VERSION_ROLLBACK_V1 = "atomadic-forge.rollback/v1"
+
+
+_GENERATED_DIRS = (
+    "build", "dist", ".pytest_cache", "__pycache__",
+    "node_modules", ".turbo", ".next", ".nuxt",
+    ".atomadic-forge",
+)
+_CACHE_DIRS = (
+    "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+    ".tox", ".coverage",
+)
+_DOCS_DIRS = ("docs", "doc", "documentation")
+_RELEASE_FILES = (
+    "pyproject.toml", "setup.py", "setup.cfg", "package.json",
+    "Cargo.toml", "CHANGELOG.md", "VERSION",
+)
+
+
+class RollbackPlan(TypedDict, total=False):
+    schema_version: str
+    changed_files: list[str]
+    files_to_remove: list[str]
+    caches_to_clean: list[str]
+    docs_to_restore: list[str]
+    tests_to_rerun: list[str]
+    risk_level: str
+    notes: list[str]
+    suggested_commands: list[str]
+
+
+def _is_generated(path: str) -> bool:
+    return any(seg in _GENERATED_DIRS for seg in path.split("/"))
+
+
+def _is_cache(path: str) -> bool:
+    return any(seg in _CACHE_DIRS for seg in path.split("/"))
+
+
+def _is_docs(path: str) -> bool:
+    return any(seg in _DOCS_DIRS for seg in path.split("/"))
+
+
+def _is_release(path: str) -> bool:
+    return Path(path).name in _RELEASE_FILES
+
+
+def rollback_plan(
+    *,
+    changed_files: list[str],
+    project_root: Path,
+) -> RollbackPlan:
+    """Build a structured rollback plan for ``changed_files``.
+
+    Pure: walks paths only. Returns the categories the agent should
+    consider when undoing the change, with shell sketches.
+    """
+    files_to_remove: list[str] = []
+    caches: list[str] = []
+    docs: list[str] = []
+    tests: list[str] = []
+    notes: list[str] = []
+    has_release_change = False
+
+    for f in changed_files:
+        if _is_generated(f):
+            files_to_remove.append(f)
+        if _is_cache(f):
+            caches.append(f)
+        if _is_docs(f):
+            docs.append(f)
+        if "tests/" in f or "test/" in f or f.endswith("_test.py"):
+            tests.append(f)
+        if _is_release(f):
+            has_release_change = True
+            notes.append(
+                f"{f} is a release-control file — reverting it must "
+                "include a corresponding CHANGELOG note + version "
+                "decrement decision."
+            )
+
+    # If there are non-generated, non-test, non-doc src changes, those
+    # are the riskiest part of a rollback because they may have
+    # downstream consumers.
+    src_changes = [f for f in changed_files
+                   if not _is_generated(f) and not _is_cache(f)
+                   and not _is_docs(f)
+                   and "tests/" not in f and "test/" not in f]
+    if has_release_change:
+        risk = "high"
+    elif len(src_changes) > 5:
+        risk = "high"
+        notes.append(
+            f"{len(src_changes)} src files in scope — bulk rollback is "
+            "high-risk; prefer per-card reverts via plan-step rollbacks."
+        )
+    elif len(src_changes) > 0:
+        risk = "medium"
+    else:
+        risk = "low"
+
+    if not tests and src_changes:
+        tests = ["python -m pytest"]
+        notes.append(
+            "no test files in scope but src changed — re-run the full "
+            "suite to confirm the rollback didn't break a covered path."
+        )
+
+    suggested: list[str] = []
+    if files_to_remove:
+        suggested.append("rm -rf " + " ".join(sorted(set(files_to_remove))))
+    if caches:
+        suggested.append(
+            "find . -type d -name __pycache__ -exec rm -rf {} +")
+    suggested.append("git restore " + " ".join(src_changes)
+                      if src_changes else "git status")
+    if tests:
+        suggested.append("python -m pytest")
+
+    return RollbackPlan(
+        schema_version=SCHEMA_VERSION_ROLLBACK_V1,
+        changed_files=list(changed_files),
+        files_to_remove=sorted(set(files_to_remove)),
+        caches_to_clean=sorted(set(caches)),
+        docs_to_restore=sorted(set(docs)),
+        tests_to_rerun=sorted(set(tests)),
+        risk_level=risk,
+        notes=notes,
+        suggested_commands=suggested,
+    )

atomadic_forge/a1_at_functions/sbom_emitter.py

@@ -0,0 +1,155 @@
+"""Tier a1 — pure CycloneDX 1.5 SBOM emitter.
+
+Golden Path Lane G G3. Emits an ``atomadic-forge.sbom/v1`` document
+wrapping a CycloneDX 1.5 JSON SBOM derived from a project's
+``pyproject.toml`` ``[project].dependencies`` +
+``[project.optional-dependencies].dev``.
+
+Pure: no network, no file writes. Returns a dict ready for
+``json.dumps``.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from pathlib import Path
+from typing import Any
+
+from .. import __version__
+
+SCHEMA_VERSION_SBOM_V1 = "atomadic-forge.sbom/v1"
+_CYCLONEDX_FORMAT = "CycloneDX"
+_CYCLONEDX_SPEC_VERSION = "1.5"
+
+
+def _now_utc_iso() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _normalise_name(raw: str) -> str:
+    """PEP 503 canonical name: lowercase, dashes/underscores/dots -> hyphens."""
+    return re.sub(r"[-_.]+", "-", raw).lower()
+
+
+def _parse_dep(dep: str) -> tuple[str, str]:
+    """Return (canonical_name, version_spec) from a PEP 508 string."""
+    dep = dep.strip()
+    name_match = re.match(r"^([A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?)", dep)
+    name = _normalise_name(name_match.group(1)) if name_match else dep.lower()
+    ver_match = re.search(r"[><=!~]{1,3}([0-9][^,;\s\]]*)", dep)
+    ver = ver_match.group(1).rstrip(",") if ver_match else "unspecified"
+    return name, ver
+
+
+def _read_pyproject_deps(project_root: Path) -> list[str]:
+    """Return combined runtime + dev deps from ``pyproject.toml``."""
+    pyproject = project_root / "pyproject.toml"
+    if not pyproject.exists():
+        return []
+    try:
+        text = pyproject.read_text(encoding="utf-8")
+    except OSError:
+        return []
+
+    try:
+        import tomllib  # noqa: PLC0415
+    except ImportError:
+        try:
+            import tomli as tomllib  # type: ignore[no-redef]  # noqa: PLC0415
+        except ImportError:
+            tomllib = None  # type: ignore[assignment]
+
+    if tomllib is not None:
+        try:
+            data = tomllib.loads(text)
+            project = data.get("project", {})
+            deps: list[str] = list(project.get("dependencies") or [])
+            opt = project.get("optional-dependencies") or {}
+            deps.extend(opt.get("dev") or [])
+            return deps
+        except Exception:  # noqa: BLE001
+            pass
+
+    return _regex_extract_deps(text)
+
+
+def _regex_extract_deps(text: str) -> list[str]:
+    """Minimal TOML-free dep extraction."""
+    deps: list[str] = []
+    in_section = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if re.match(r"^dependencies\s*=\s*\[", stripped):
+            in_section = True
+            inner = re.search(r"\[([^\]]*)\]", stripped)
+            if inner:
+                for tok in inner.group(1).split(","):
+                    dep = tok.strip().strip("\"'")
+                    if dep:
+                        deps.append(dep)
+                in_section = False
+            continue
+        if in_section:
+            if stripped.startswith("]"):
+                in_section = False
+                continue
+            dep = stripped.strip(",").strip("\"'").strip()
+            if dep and not dep.startswith("#"):
+                deps.append(dep)
+    return deps
+
+
+def _dep_to_component(dep: str) -> dict[str, Any]:
+    name, version = _parse_dep(dep)
+    return {
+        "type": "library",
+        "name": name,
+        "version": version,
+        "purl": f"pkg:pypi/{name}@{version}",
+    }
+
+
+def emit_sbom(
+    *,
+    project_root: Path | str,
+    scout_report: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return an ``atomadic-forge.sbom/v1`` dict wrapping CycloneDX 1.5 JSON.
+
+    Pulls deps from ``pyproject.toml`` ``[project].dependencies`` +
+    ``[project.optional-dependencies].dev``.
+    """
+    project_root = Path(project_root).resolve()
+    raw_deps = _read_pyproject_deps(project_root)
+    components = [_dep_to_component(d) for d in raw_deps if d.strip()]
+
+    now = _now_utc_iso()
+    cyclonedx: dict[str, Any] = {
+        "bomFormat": _CYCLONEDX_FORMAT,
+        "specVersion": _CYCLONEDX_SPEC_VERSION,
+        "version": 1,
+        "metadata": {
+            "timestamp": now,
+            "tools": [
+                {
+                    "vendor": "Atomadic",
+                    "name": "atomadic-forge",
+                    "version": __version__,
+                }
+            ],
+        },
+        "components": components,
+    }
+
+    sbom: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION_SBOM_V1,
+        "project_root": str(project_root),
+        "generated_at_utc": now,
+        "sbom": cyclonedx,
+    }
+    if scout_report is not None:
+        sbom["scout_summary"] = {
+            "symbol_count": int(scout_report.get("symbol_count", 0)),
+            "primary_language": str(scout_report.get("primary_language", "python")),
+        }
+    return sbom

atomadic_forge/a1_at_functions/scaffold_js.py

@@ -0,0 +1,55 @@
+"""Tier a1 — pure renderers for JS/TS package scaffolds.
+
+Forge's iterate loop scaffolds the surrounding package shell so the LLM
+can focus on emitting actual code.  For Python this means ``pyproject.toml``,
+``__init__.py``, ``conftest.py``.  For JavaScript / TypeScript it means a
+minimal ``package.json`` plus a README — nothing else is required for ES
+modules to resolve.
+
+Pure: no I/O.  Each helper returns a string the caller writes to disk.
+"""
+
+from __future__ import annotations
+
+import json as _json
+
+
+def render_package_json(*, package: str, description: str = "",
+                          language: str = "javascript") -> str:
+    """Render a minimal ``package.json`` for a JS/TS evolved package.
+
+    Sets ``"type": "module"`` so ES6 ``import`` / ``export`` resolves
+    natively.  No build step, no dependencies — Forge produces source
+    that runs as-is on Node 20+ and Cloudflare Workers.
+
+    The TypeScript variant is identical except for documentation in the
+    description (``ts`` files would compile via ``tsc`` or run via
+    ``tsx``; that's a downstream concern).
+    """
+    pkg = {
+        "name": package,
+        "version": "0.0.1",
+        "description": (description or f"{package} — generated by atomadic-forge").strip(),
+        "type": "module",
+        "private": True,
+    }
+    return _json.dumps(pkg, indent=2) + "\n"
+
+
+def render_js_readme(*, package: str, intent: str, language: str) -> str:
+    """Render a README.md for a JS/TS evolved package."""
+    lang_label = "JavaScript" if language == "javascript" else "TypeScript"
+    return (
+        f"# {package}\n\n"
+        f"{lang_label} package generated by `atomadic-forge evolve`.\n\n"
+        f"## Intent\n\n"
+        f"{intent.strip() or '(unspecified)'}\n\n"
+        f"## Layout (5-tier monadic)\n\n"
+        f"- `a0_qk_constants/` — constants, no logic\n"
+        f"- `a1_at_functions/` — pure stateless functions\n"
+        f"- `a2_mo_composites/` — stateful classes / clients\n"
+        f"- `a3_og_features/` — feature orchestrators\n"
+        f"- `a4_sy_orchestration/` — entry points (Worker, CLI)\n\n"
+        f"Imports compose **upward only** — a lower tier never imports "
+        f"from a higher tier.  Forge enforces this in `forge wire`.\n"
+    )

atomadic_forge/a1_at_functions/scaffold_pyproject.py

@@ -0,0 +1,62 @@
+"""Tier a1 — pure renderer for a generated package's ``pyproject.toml``.
+
+When ``forge iterate``/``evolve`` materialises a package, it scaffolds a
+real ``pyproject.toml`` so the output is genuinely pip-installable from
+moment zero.  The LLM doesn't need to know how to build a pyproject —
+Forge does that, and the LLM just emits the ``.py`` files.
+
+The renderer is pure: it takes a name and an optional console-script
+target and returns a TOML string.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+def render_pyproject(
+    *,
+    package: str,
+    description: str = "",
+    version: str = "0.1.0",
+    python_requires: str = ">=3.10",
+    console_script_target: str | None = None,
+    extra_dependencies: Iterable[str] = (),
+) -> str:
+    """Return a PEP-621 pyproject.toml as a string.
+
+    ``console_script_target``: e.g. ``"a4_sy_orchestration.cli:main"``.
+    The script becomes ``<package> = "<package>.<target>"`` so users can
+    run ``<package>`` after install.
+    """
+    desc = (description or f"{package} — generated by atomadic-forge").replace('"', "'")
+    deps = ",\n    ".join(f'"{d}"' for d in extra_dependencies)
+    deps_block = (
+        f"dependencies = [\n    {deps},\n]\n" if deps else "dependencies = []\n"
+    )
+    scripts_block = ""
+    if console_script_target:
+        scripts_block = (
+            "\n[project.scripts]\n"
+            f'{package} = "{package}.{console_script_target}"\n'
+        )
+
+    return (
+        "# Auto-scaffolded by atomadic-forge.  Edit freely.\n"
+        "[build-system]\n"
+        'requires = ["setuptools>=68", "wheel"]\n'
+        'build-backend = "setuptools.build_meta"\n'
+        "\n"
+        "[project]\n"
+        f'name = "{package}"\n'
+        f'version = "{version}"\n'
+        f'description = "{desc}"\n'
+        f'readme = "README.md"\n'
+        f'requires-python = "{python_requires}"\n'
+        + deps_block
+        + scripts_block
+        + "\n"
+        "[tool.setuptools.packages.find]\n"
+        'where = ["src"]\n'
+        f'include = ["{package}*"]\n'
+    )

atomadic_forge/a1_at_functions/scaffold_starter.py

@@ -0,0 +1,94 @@
+"""Tier a1 — pure renderers for the surrounding package starter files.
+
+Forge scaffolds ``README.md``, ``.gitignore``, ``tests/__init__.py``, and
+``tests/conftest.py`` once at iterate Round 0 so the generated package is
+a complete, conventional Python project from the first turn.  The LLM
+never has to remember to write these — it focuses on the actual code.
+"""
+
+from __future__ import annotations
+
+
+def render_readme(*, package: str, intent: str) -> str:
+    safe_intent = intent.strip().replace("`", "'")
+    return (
+        f"# {package}\n"
+        "\n"
+        f"_Generated by [Atomadic Forge](https://atomadic.tech) from the intent below._\n"
+        "\n"
+        "## Intent\n"
+        "\n"
+        f"> {safe_intent}\n"
+        "\n"
+        "## Architecture\n"
+        "\n"
+        "This package follows the Atomadic 5-tier monadic standard:\n"
+        "\n"
+        "| Tier | Directory | Lives here |\n"
+        "|------|-----------|------------|\n"
+        "| a0 | `src/" + package + "/a0_qk_constants/` | constants, enums, TypedDicts |\n"
+        "| a1 | `src/" + package + "/a1_at_functions/` | pure functions |\n"
+        "| a2 | `src/" + package + "/a2_mo_composites/` | stateful classes |\n"
+        "| a3 | `src/" + package + "/a3_og_features/` | feature orchestrators |\n"
+        "| a4 | `src/" + package + "/a4_sy_orchestration/` | CLI / entry points |\n"
+        "\n"
+        "## Install\n"
+        "\n"
+        "```bash\n"
+        "pip install -e .\n"
+        "```\n"
+        "\n"
+        "## Run tests\n"
+        "\n"
+        "```bash\n"
+        "pytest tests/\n"
+        "```\n"
+        "\n"
+        "## Verify with Forge\n"
+        "\n"
+        "```bash\n"
+        f"forge wire src/{package}     # zero upward-import violations\n"
+        f"forge certify . --package {package}\n"
+        "```\n"
+    )
+
+
+def render_gitignore() -> str:
+    return (
+        "__pycache__/\n"
+        "*.py[cod]\n"
+        "*.egg-info/\n"
+        "build/\n"
+        "dist/\n"
+        ".venv/\n"
+        "venv/\n"
+        ".pytest_cache/\n"
+        ".ruff_cache/\n"
+        ".mypy_cache/\n"
+        ".coverage\n"
+        ".atomadic-forge/\n"
+        ".DS_Store\n"
+        ".vscode/\n"
+        ".idea/\n"
+    )
+
+
+def render_tests_conftest(*, package: str) -> str:
+    return (
+        '"""Shared fixtures for ' + package + ' tests."""\n'
+        "\n"
+        "from __future__ import annotations\n"
+        "\n"
+        "import sys\n"
+        "from pathlib import Path\n"
+        "\n"
+        "# Make the src/ layout importable when tests run before pip install.\n"
+        "ROOT = Path(__file__).resolve().parent.parent\n"
+        "SRC = ROOT / 'src'\n"
+        "if SRC.exists() and str(SRC) not in sys.path:\n"
+        "    sys.path.insert(0, str(SRC))\n"
+    )
+
+
+def render_tests_init() -> str:
+    return '"""Tests for the package."""\n'