codeatlas-bundle 0.1.0__tar.gz

codeatlas_bundle-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+/target
+**/*.rs.bk
+/dist
+/wheels
+/build
+*.so
+*.dylib
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.codeatlas/

codeatlas_bundle-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: codeatlas-bundle
+Version: 0.1.0
+Summary: Bundle CodeAtlas architecture maps into any repository
+Author: Mullassery
+License: MIT
+Keywords: architecture,diagrams,documentation,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Requires-Dist: codeatlas-rs>=0.1.0
+Description-Content-Type: text/markdown
+
+# codeatlas-bundle
+
+Bundle [CodeAtlas](https://github.com/Mullassery/CodeAtlas) architecture maps
+into any repository so the map is versioned alongside the code.
+
+`codeatlas-bundle` runs the deterministic CodeAtlas analysis, renders the docs
+(Markdown + HTML by default), writes them under a configured directory, and can
+commit the result. It is pure Python and works for repositories in any language
+CodeAtlas supports (Python, Rust, Go, JavaScript/TypeScript).
+
+## Install
+
+```bash
+pip install codeatlas-rs codeatlas-bundle
+```
+
+## Connect a repository
+
+```bash
+cd my-repo
+codeatlas-bundle init          # writes codeatlas.json
+codeatlas-bundle build         # generates docs/codeatlas/
+codeatlas-bundle build --commit  # generate and commit
+```
+
+`codeatlas.json`:
+
+```json
+{
+  "project_name": "my-repo",
+  "output_dir": "docs/codeatlas",
+  "formats": ["markdown", "html"],
+  "depth_cap": 3,
+  "include_analysis": false
+}
+```
+
+- `formats`: any of `markdown`, `html`, `mdx`, `rst`.
+- `include_analysis`: when `true`, also commit the raw `analysis.json`,
+  `fingerprint.json`, and `file_coverage.json` sidecars (the raw analysis
+  contains a generation timestamp, so this produces a larger diff each run).
+
+## CI: keep the map fresh
+
+```yaml
+# .github/workflows/codeatlas.yml
+name: CodeAtlas
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  bundle:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install codeatlas-rs codeatlas-bundle
+      - run: git config user.name "codeatlas" && git config user.email "codeatlas@users.noreply.github.com"
+      - run: codeatlas-bundle build --commit
+      - run: git push
+```
+
+To gate a pull request instead of committing, use `codeatlas-bundle check`,
+which exits non-zero when the committed bundle is stale.
+
+## Python API
+
+```python
+from codeatlas_bundle import bundle, check
+
+result = bundle("path/to/repo", commit=True)
+print([str(p) for p in result.files])
+
+is_current, changed = check("path/to/repo")
+```

codeatlas_bundle-0.1.0/README.md

@@ -0,0 +1,79 @@
+# codeatlas-bundle
+
+Bundle [CodeAtlas](https://github.com/Mullassery/CodeAtlas) architecture maps
+into any repository so the map is versioned alongside the code.
+
+`codeatlas-bundle` runs the deterministic CodeAtlas analysis, renders the docs
+(Markdown + HTML by default), writes them under a configured directory, and can
+commit the result. It is pure Python and works for repositories in any language
+CodeAtlas supports (Python, Rust, Go, JavaScript/TypeScript).
+
+## Install
+
+```bash
+pip install codeatlas-rs codeatlas-bundle
+```
+
+## Connect a repository
+
+```bash
+cd my-repo
+codeatlas-bundle init          # writes codeatlas.json
+codeatlas-bundle build         # generates docs/codeatlas/
+codeatlas-bundle build --commit  # generate and commit
+```
+
+`codeatlas.json`:
+
+```json
+{
+  "project_name": "my-repo",
+  "output_dir": "docs/codeatlas",
+  "formats": ["markdown", "html"],
+  "depth_cap": 3,
+  "include_analysis": false
+}
+```
+
+- `formats`: any of `markdown`, `html`, `mdx`, `rst`.
+- `include_analysis`: when `true`, also commit the raw `analysis.json`,
+  `fingerprint.json`, and `file_coverage.json` sidecars (the raw analysis
+  contains a generation timestamp, so this produces a larger diff each run).
+
+## CI: keep the map fresh
+
+```yaml
+# .github/workflows/codeatlas.yml
+name: CodeAtlas
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  bundle:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install codeatlas-rs codeatlas-bundle
+      - run: git config user.name "codeatlas" && git config user.email "codeatlas@users.noreply.github.com"
+      - run: codeatlas-bundle build --commit
+      - run: git push
+```
+
+To gate a pull request instead of committing, use `codeatlas-bundle check`,
+which exits non-zero when the committed bundle is stale.
+
+## Python API
+
+```python
+from codeatlas_bundle import bundle, check
+
+result = bundle("path/to/repo", commit=True)
+print([str(p) for p in result.files])
+
+is_current, changed = check("path/to/repo")
+```

codeatlas_bundle-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codeatlas-bundle"
+version = "0.1.0"
+description = "Bundle CodeAtlas architecture maps into any repository"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Mullassery" }]
+keywords = ["architecture", "diagrams", "static-analysis", "documentation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = ["codeatlas-rs>=0.1.0"]
+
+[project.scripts]
+codeatlas-bundle = "codeatlas_bundle.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codeatlas_bundle"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

codeatlas_bundle-0.1.0/src/codeatlas_bundle/__init__.py

@@ -0,0 +1,17 @@
+"""CodeAtlas Bundle: version CodeAtlas architecture maps inside any repository."""
+
+from codeatlas_bundle.bundle import BundleResult, bundle, check, detect_repo_root
+from codeatlas_bundle.config import Config, init_config, load_config
+
+__all__ = [
+    "BundleResult",
+    "Config",
+    "bundle",
+    "check",
+    "detect_repo_root",
+    "init_config",
+    "load_config",
+    "__version__",
+]
+
+__version__ = "0.1.0"

codeatlas_bundle-0.1.0/src/codeatlas_bundle/bundle.py

@@ -0,0 +1,179 @@
+"""Bundle CodeAtlas architecture docs into a target repository.
+
+`codeatlas-bundle` runs the deterministic analysis, renders the docs, writes
+them under the configured output directory, and (optionally) commits the result
+so the architecture map is versioned alongside the code.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import codeatlas_rs
+from codeatlas_rs.render import render
+
+from codeatlas_bundle.config import CONFIG_FILENAME, Config, load_config
+
+ANALYSIS_FILENAME = "analysis.json"
+FINGERPRINT_FILENAME = "fingerprint.json"
+FILE_COVERAGE_FILENAME = "file_coverage.json"
+DEFAULT_COMMIT_MESSAGE = "docs(codeatlas): refresh architecture map"
+
+
+@dataclass
+class BundleResult:
+    repo_root: Path
+    output_dir: Path
+    files: list[Path] = field(default_factory=list)
+    committed: bool = False
+
+
+def detect_repo_root(start: Path | str | None = None) -> Path:
+    """Walk up from `start` to the nearest directory containing `.git` or
+    `codeatlas.json`; fall back to `start` itself."""
+    current = Path(start or Path.cwd()).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".git").exists() or (candidate / CONFIG_FILENAME).exists():
+            return candidate
+    return current
+
+
+def bundle(
+    repo_root: Path | str,
+    config: Config | None = None,
+    *,
+    commit: bool = False,
+    message: str | None = None,
+) -> BundleResult:
+    """Generate the architecture bundle for `repo_root` into its output dir."""
+    root = Path(repo_root).resolve()
+    cfg = config or load_config(root)
+    out_dir = root / cfg.output_dir
+
+    files = _generate(root, cfg, out_dir)
+    result = BundleResult(repo_root=root, output_dir=out_dir, files=files)
+
+    if commit:
+        result.committed = _commit(root, out_dir, message or DEFAULT_COMMIT_MESSAGE)
+    return result
+
+
+def check(repo_root: Path | str, config: Config | None = None) -> tuple[bool, list[str]]:
+    """Return `(is_current, changed_files)` comparing the committed bundle with
+    a freshly generated one."""
+    root = Path(repo_root).resolve()
+    cfg = config or load_config(root)
+    committed_dir = root / cfg.output_dir
+
+    changed: list[str] = []
+    with tempfile.TemporaryDirectory(prefix="codeatlas-bundle-") as tmp:
+        generated_dir = Path(tmp) / "out"
+        _generate(root, cfg, generated_dir)
+
+        generated = _relative_files(generated_dir)
+        committed = _relative_files(committed_dir) if committed_dir.is_dir() else {}
+
+        for rel, path in generated.items():
+            committed_path = committed_dir / rel
+            if rel not in committed or _content(path) != _content(committed_path):
+                changed.append(rel)
+        for rel in committed:
+            if rel not in generated:
+                changed.append(rel)
+
+    return (not changed, sorted(changed))
+
+
+def _generate(root: Path, cfg: Config, out_dir: Path) -> list[Path]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    # Always exclude the repository's configured output dir from analysis, even
+    # when writing to a temporary directory (as `check` does).
+    repo_output = root / cfg.output_dir
+    analysis_json, fingerprint_json, coverage_json = codeatlas_rs.analyze(
+        str(root),
+        project_name=cfg.project_name,
+        depth_cap=cfg.depth_cap,
+        ignore_paths=[str(repo_output)],
+    )
+
+    written: list[Path] = []
+    analysis_path = out_dir / ANALYSIS_FILENAME
+    analysis_path.write_text(_pretty(analysis_json), encoding="utf-8")
+
+    if cfg.include_analysis:
+        (out_dir / FINGERPRINT_FILENAME).write_text(fingerprint_json, encoding="utf-8")
+        (out_dir / FILE_COVERAGE_FILENAME).write_text(coverage_json, encoding="utf-8")
+        written += [
+            analysis_path,
+            out_dir / FINGERPRINT_FILENAME,
+            out_dir / FILE_COVERAGE_FILENAME,
+        ]
+
+    for code in cfg.format_codes:
+        written.extend(render(code, analysis_path, out_dir))
+
+    if not cfg.include_analysis:
+        analysis_path.unlink(missing_ok=True)
+
+    return sorted({p for p in written})
+
+
+def _pretty(raw_json: str) -> str:
+    return json.dumps(json.loads(raw_json), indent=2) + "\n"
+
+
+def _relative_files(directory: Path) -> dict[str, Path]:
+    files: dict[str, Path] = {}
+    for path in sorted(directory.rglob("*")):
+        if path.is_file():
+            files[str(path.relative_to(directory))] = path
+    return files
+
+
+def _content(path: Path) -> str:
+    text = path.read_text(encoding="utf-8")
+    if path.name == ANALYSIS_FILENAME:
+        data = json.loads(text)
+        data.get("metadata", {}).pop("generated_at", None)
+        return json.dumps(data, sort_keys=True)
+    return text
+
+
+def _commit(root: Path, out_dir: Path, message: str) -> bool:
+    config_path = root / CONFIG_FILENAME
+    targets = [str(out_dir)]
+    if config_path.exists():
+        targets.append(str(config_path))
+
+    _git(root, "add", "--", *targets)
+    if _git(root, "diff", "--cached", "--quiet").returncode == 0:
+        return False
+
+    identity = _git(root, "config", "user.email").stdout.strip()
+    prefix: list[str] = []
+    if not identity:
+        prefix = [
+            "-c",
+            "user.name=codeatlas-bundle",
+            "-c",
+            "user.email=codeatlas-bundle@users.noreply.github.com",
+        ]
+    _git(root, *prefix, "commit", "-m", message, check=True)
+    return True
+
+
+def _git(root: Path, *args: str, check: bool = False) -> subprocess.CompletedProcess[str]:
+    result = subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+    )
+    if check and result.returncode != 0:
+        raise RuntimeError(
+            f"git {' '.join(args)} failed: {result.stderr.strip() or result.stdout.strip()}"
+        )
+    return result

codeatlas_bundle-0.1.0/src/codeatlas_bundle/cli.py

@@ -0,0 +1,93 @@
+"""`codeatlas-bundle` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from codeatlas_bundle import __version__
+from codeatlas_bundle.bundle import bundle, check, detect_repo_root
+from codeatlas_bundle.config import init_config, load_config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codeatlas-bundle",
+        description="Bundle CodeAtlas architecture docs into a repository",
+    )
+    parser.add_argument("--version", action="version", version=f"codeatlas-bundle {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    init = sub.add_parser("init", help="Write a codeatlas.json opt-in file")
+    init.add_argument("--repo", default=".", help="Repository root")
+    init.add_argument("--project-name")
+    init.add_argument("--output-dir")
+    init.add_argument("--formats", help="Comma-separated: markdown,html,mdx,rst")
+    init.add_argument("--depth-cap", type=int)
+    init.add_argument("--force", action="store_true")
+
+    build = sub.add_parser("build", help="Generate the bundle (and optionally commit)")
+    build.add_argument("--repo", default=".", help="Repository root")
+    build.add_argument("--commit", action="store_true", help="Commit the generated docs")
+    build.add_argument("--message", help="Commit message")
+
+    chk = sub.add_parser("check", help="Fail if the committed bundle is stale")
+    chk.add_argument("--repo", default=".", help="Repository root")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "init":
+        return _cmd_init(args)
+    if args.command == "check":
+        return _cmd_check(args)
+    return _cmd_build(args)
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    root = detect_repo_root(args.repo)
+    formats = args.formats.split(",") if args.formats else None
+    try:
+        path = init_config(
+            root,
+            force=args.force,
+            project_name=args.project_name,
+            output_dir=args.output_dir,
+            formats=formats,
+            depth_cap=args.depth_cap,
+        )
+    except (FileExistsError, ValueError) as exc:
+        print(f"codeatlas-bundle: {exc}", file=sys.stderr)
+        return 1
+    print(f"Wrote {path}")
+    print("Next: codeatlas-bundle build --commit")
+    return 0
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    root = detect_repo_root(args.repo)
+    result = bundle(root, commit=args.commit, message=args.message)
+    for path in result.files:
+        print(f"Wrote {path.relative_to(result.repo_root)}")
+    if args.commit:
+        state = "committed" if result.committed else "no changes to commit"
+        print(f"Bundle {state}")
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    root = detect_repo_root(args.repo)
+    current, changed = check(root)
+    if current:
+        print(f"Bundle is up to date ({load_config(root).output_dir})")
+        return 0
+    print("codeatlas-bundle: bundle is stale; run `codeatlas-bundle build`:")
+    for rel in changed:
+        print(f"  - {rel}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codeatlas_bundle-0.1.0/src/codeatlas_bundle/config.py

@@ -0,0 +1,101 @@
+"""Configuration for `codeatlas-bundle`.
+
+A target repository opts in by committing a `codeatlas.json` file at its root.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONFIG_FILENAME = "codeatlas.json"
+DEFAULT_OUTPUT_DIR = "docs/codeatlas"
+DEFAULT_FORMATS = ("markdown", "html")
+
+# Friendly format names -> `codeatlas.render` format codes.
+FORMAT_CODES = {
+    "markdown": "md",
+    "md": "md",
+    "html": "html",
+    "mdx": "mdx",
+    "rst": "rst",
+}
+
+
+@dataclass
+class Config:
+    """Resolved bundle configuration."""
+
+    project_name: str
+    output_dir: str = DEFAULT_OUTPUT_DIR
+    formats: list[str] = field(default_factory=lambda: list(DEFAULT_FORMATS))
+    depth_cap: int = 3
+    include_analysis: bool = False
+
+    @property
+    def format_codes(self) -> list[str]:
+        codes: list[str] = []
+        for name in self.formats:
+            code = FORMAT_CODES.get(name)
+            if code is None:
+                raise ValueError(f"unsupported format {name!r}")
+            if code not in codes:
+                codes.append(code)
+        return codes
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "project_name": self.project_name,
+            "output_dir": self.output_dir,
+            "formats": list(self.formats),
+            "depth_cap": self.depth_cap,
+            "include_analysis": self.include_analysis,
+        }
+
+
+def load_config(repo_root: Path | str) -> Config:
+    """Load `codeatlas.json` from `repo_root` (falling back to defaults)."""
+    root = Path(repo_root)
+    path = root / CONFIG_FILENAME
+    if not path.is_file():
+        return Config(project_name=root.resolve().name)
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return _from_dict(data, default_name=root.resolve().name)
+
+
+def _from_dict(data: dict[str, Any], *, default_name: str) -> Config:
+    return Config(
+        project_name=data.get("project_name") or default_name,
+        output_dir=data.get("output_dir", DEFAULT_OUTPUT_DIR),
+        formats=list(data.get("formats", DEFAULT_FORMATS)),
+        depth_cap=int(data.get("depth_cap", 3)),
+        include_analysis=bool(data.get("include_analysis", False)),
+    )
+
+
+def init_config(
+    repo_root: Path | str,
+    *,
+    force: bool = False,
+    project_name: str | None = None,
+    output_dir: str | None = None,
+    formats: list[str] | None = None,
+    depth_cap: int | None = None,
+) -> Path:
+    """Write a `codeatlas.json` opt-in file, returning its path."""
+    root = Path(repo_root).resolve()
+    path = root / CONFIG_FILENAME
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists (use --force to overwrite)")
+    config = Config(
+        project_name=project_name or root.name,
+        output_dir=output_dir or DEFAULT_OUTPUT_DIR,
+        formats=list(formats) if formats else list(DEFAULT_FORMATS),
+        depth_cap=depth_cap if depth_cap is not None else 3,
+    )
+    # Validate format names early.
+    _ = config.format_codes
+    path.write_text(json.dumps(config.to_dict(), indent=2) + "\n", encoding="utf-8")
+    return path

codeatlas_bundle-0.1.0/tests/test_bundle.py

@@ -0,0 +1,104 @@
+"""Tests for codeatlas-bundle: generation, staleness checks, and commits."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from codeatlas_bundle import bundle, check, detect_repo_root, init_config, load_config
+
+
+def _make_repo(tmp_path: Path) -> Path:
+    (tmp_path / "app").mkdir()
+    (tmp_path / "core").mkdir()
+    (tmp_path / "app" / "main.py").write_text("def run():\n    return helper()\n")
+    (tmp_path / "app" / "helper.py").write_text("def helper():\n    return 1\n")
+    (tmp_path / "core" / "engine.py").write_text("def start():\n    return 1\n")
+    return tmp_path
+
+
+def _git(repo: Path, *args: str) -> None:
+    subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True)
+
+
+def test_init_writes_config(tmp_path):
+    repo = _make_repo(tmp_path)
+    path = init_config(repo)
+    assert path == repo / "codeatlas.json"
+    data = json.loads(path.read_text())
+    assert data["output_dir"] == "docs/codeatlas"
+    assert data["formats"] == ["markdown", "html"]
+
+    with pytest.raises(FileExistsError):
+        init_config(repo)
+    assert init_config(repo, force=True).exists()
+
+
+def test_bundle_generates_docs_and_is_current(tmp_path):
+    repo = _make_repo(tmp_path)
+    init_config(repo)
+
+    result = bundle(repo)
+    rels = {p.relative_to(repo).as_posix() for p in result.files}
+    assert "docs/codeatlas/overview.md" in rels
+    assert "docs/codeatlas/overview.html" in rels
+
+    current, changed = check(repo)
+    assert current, changed
+    assert changed == []
+
+
+def test_check_detects_source_change(tmp_path):
+    repo = _make_repo(tmp_path)
+    init_config(repo)
+    bundle(repo)
+
+    # Change the code without regenerating the bundle.
+    (repo / "app" / "helper.py").write_text("def helper():\n    return 2\n")
+    (repo / "app" / "new.py").write_text("def added():\n    return 3\n")
+
+    current, changed = check(repo)
+    assert not current
+    assert changed
+
+
+def test_bundle_commits_into_repo(tmp_path):
+    repo = _make_repo(tmp_path)
+    _git(repo, "init")
+    _git(repo, "config", "user.email", "test@example.com")
+    _git(repo, "config", "user.name", "Test")
+    _git(repo, "add", "-A")
+    _git(repo, "commit", "-m", "initial")
+
+    init_config(repo)
+    result = bundle(repo, commit=True)
+    assert result.committed is True
+
+    log = subprocess.run(
+        ["git", "-C", str(repo), "log", "--oneline"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout
+    assert "codeatlas" in log
+
+    # No changes on a second run -> nothing to commit.
+    result2 = bundle(repo, commit=True)
+    assert result2.committed is False
+
+
+def test_detect_repo_root_finds_config(tmp_path):
+    repo = _make_repo(tmp_path)
+    init_config(repo)
+    nested = repo / "app"
+    assert detect_repo_root(nested) == repo
+
+
+def test_load_config_defaults_without_file(tmp_path):
+    repo = _make_repo(tmp_path)
+    config = load_config(repo)
+    assert config.project_name == repo.name
+    assert config.output_dir == "docs/codeatlas"