Metadata-Version: 2.4
Name: archility
Version: 0.1.1
Summary: Architecture inventory and blueprint audit helpers for portfolio repositories.
Author-email: Cason Konzer <casonk@umich.edu>
License: MIT
Project-URL: Homepage, https://github.com/casonk/archility
Project-URL: Repository, https://github.com/casonk/archility
Project-URL: Changelog, https://github.com/casonk/archility/blob/main/CHANGELOG.md
Keywords: architecture,diagrams,plantuml,drawio,portfolio
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Documentation
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: dyno-lab>=0.3.0; extra == "dev"
Dynamic: license-file

# archility

Architecture toolchain bootstrap, render orchestration, inventory, deterministic starter scaffolding, supplemental code-introspection diagram generation, and agentic architecture-authoring support for portfolio repositories.

`archility` is the shared utility repo for architecture-aware maintenance across the portfolio. It owns the shared bootstrap path for PlantUML, Draw.io, Graphviz-backed PlantUML rendering, and related rendering flows, in addition to the audit CLI for architecture artifacts and documentation coverage.

The shared portfolio standards live in `./util-repos/traction-control` from the portfolio root. This repo is the implementation home for architecture-oriented tooling that supports those standards.

## Current Scope

- Bootstrap the shared local architecture toolchain in one place instead of duplicating binary download logic in feature repos.
- Render PlantUML and Draw.io architecture artifacts for target repositories through a shared entry point.
- Derive supplemental introspection diagrams for detected Python packages/modules, shell scripts, SQL/schema files, and tooling entrypoints.
- Support richer Graphviz-backed PlantUML diagrams in addition to the Smetana-based starter baseline.
- Audit one or more repositories for architecture-adjacent baseline files.
- Generate the standard deterministic architecture starter layout used across the portfolio:
  - `docs/contributor-architecture-blueprint.md`
  - `docs/diagrams/repo-architecture.puml`
  - `docs/diagrams/repo-architecture.drawio`
- Group taxonomy-heavy archive repos by stable subject prefixes when a flat "first few folders" starter would hide important structure.
- Provide the shared home for agent-authored repository architecture once an AI agent has fully inspected and understood a repo.
- Detect whether a repo looks code-focused and should likely carry a contributor architecture blueprint.
- Report missing architecture docs, workflow coverage, diagram source/render coverage, and detected architecture toolchains in either text or JSON form.
- Provide a small, dependency-free base that can grow into richer drift checks and broader portfolio orchestration.

## Portfolio Toolchain References

`archility` now tracks the architecture toolchain conventions already used elsewhere in the portfolio:

- `./util-repos/nordility`: paired PlantUML and Draw.io architecture sources with checked-in PNG/SVG renders
- `./drawio-templates`: reusable Draw.io templates for architecture and other diagram families

See `docs/portfolio-architecture-toolchain.md` for the concrete conventions and commands.

## Architecture Authoring Paths

`archility` supports two architecture-authoring paths.

1. Programmatic path

- `archility generate` creates the starter architecture strictly from repository code and layout markers.
- This path is deterministic and is meant for baseline scaffolding, refreshable starter docs, and repeatable portfolio-wide rollouts.
- `archility render` can also derive deterministic supplemental sidecars from detected Python packages/modules, shell scripts, SQL/schema files, and tooling entrypoints.

2. Agentic path

- An AI agent inspects the repository end-to-end, understands the real execution flow and boundaries, and then writes a unique architecture from that understanding.
- This path is intentionally non-deterministic. It should preserve the standard file locations, but the authored content can diverge substantially from the starter.

Use the programmatic path for consistency and the agentic path for depth.

## Repository Architecture

`archility` itself is organized around an architecture-maintenance lifecycle rather than a generic package layout.

- Public entry surface: `src/archility/cli.py` and `src/archility/__main__.py` expose `audit`, `generate`, and `render`.
- Inspection path: `src/archility/audit.py` inventories architecture assets, workflow coverage, source roots, and documented toolchain hints, then emits text or JSON reports.
- Deterministic scaffolding path: `src/archility/generate.py` derives starter blueprints and diagram sources strictly from repository structure.
- Agentic authoring path: a repository-specific AI inspection rewrites those standard files with richer architecture once the repo is actually understood.
- Render path: `src/archility/render.py` turns PlantUML and Draw.io sources into checked-in SVG and PNG artifacts for target repos, and can also derive Python import/UML sidecars plus managed PlantUML sidecars for shell flow, database schema, and tooling integration views.
- Shared bootstrap path: `setup.sh` provisions the local wrappers under `tools/bin/` for PlantUML, Draw.io, `pydeps`, `pyreverse`, and optional Graphviz-backed PlantUML rendering.
- Validation path: `tests/test_audit.py`, `tests/test_generate.py`, `tests/test_render.py`, and `.github/workflows/ci.yml` keep the lifecycle behavior aligned.

The paired `docs/diagrams/repo-architecture.{puml,drawio}` files describe this lifecycle from the perspective of a portfolio maintainer invoking `archility` against target repositories.

## Install

```bash
./bootstrap.sh
bash setup.sh
```

`bootstrap.sh` creates `.venv`, installs the package in editable mode, and
verifies the `archility` command actually runs. `setup.sh` then provisions the
PlantUML/Draw.io toolchain under `tools/`.

Use `./bootstrap.sh --no-dev` to skip the test and lint dependencies, or
`./bootstrap.sh --venv PATH` to build the environment somewhere else.

<details>
<summary>Why not <code>pip install -e .</code> directly?</summary>

Since [PEP 668](https://peps.python.org/pep-0668/), Debian, Ubuntu, Arch and
openSUSE mark the system Python as externally managed, and pip refuses to
install into it:

```
error: externally-managed-environment
```

Fedora still allows it, which is why the old instruction worked on some
machines and not others. Installing into a virtualenv is correct on all of
them, and on macOS and Windows too.

</details>

Or run directly from the repo root:

```bash
PYTHONPATH=src python3 -m archility --help
```

## CLI Usage

Audit the current repository:

```bash
archility audit .
```

Generate the standard architecture starter files for another repository:

```bash
archility generate ../../util-repos/nordility
```

Render architecture diagrams for another repository after bootstrapping the shared toolchain:

```bash
archility render ../../util-repos/nordility
```

Render is shared infrastructure for both paths. The source diagrams may come from deterministic scaffolding or from a deeper agent-authored architecture pass. The same render pass can also derive supplemental deterministic sidecars for Python package/module structure, shell-script flow, SQL/schema relationships, and third-party tooling entrypoints when those signals are present.

Audit multiple repositories and emit JSON:

```bash
archility audit ../auto-pass ../nordility --json
```

Example text output fields:

- whether the target looks code-focused
- whether `AGENTS.md` and `LESSONSLEARNED.md` exist
- whether `docs/contributor-architecture-blueprint.md` exists
- whether the standard `docs/diagrams/repo-architecture.{puml,drawio}` starter files were generated or already existed
- whether contributor-facing docs mention shared diagram toolchain hints such as `pydeps`, `pyreverse`, PlantUML, Draw.io, and related render tools
- how many workflow, diagram-source, and render-artifact files were found
- which diagram formats were detected
- which architecture toolchains were detected, including PlantUML, Draw.io, `pydeps`, `pyreverse`, and Inkscape hints where present
- which shared render commands `archility` will execute during a dry-run render plan
- recommended next actions

The generated starter PlantUML diagrams use Smetana, so they do not depend on a local Graphviz install. `archility` still treats Graphviz as a supported part of the shared toolchain because richer custom PlantUML diagrams may rely on `dot`.

The supplemental sidecars are deterministic introspection diagrams. The Python path uses `pydeps` and `pyreverse`; the shell, database, and tooling paths emit managed PlantUML sources/renders directly from repository content. These assets help explain code structure and operational boundaries, but they do not replace the repo-authored `docs/contributor-architecture-blueprint.md` or the paired `repo-architecture` sources.

For Draw.io diagrams, prefer plain identifier text inside diagram labels when checked-in PNG exports matter. Backticks can render inconsistently in draw.io's direct PNG export path even when the SVG looks acceptable.

Draw.io exports use Electron and need a display. On headless Linux hosts, install
`xorg-x11-server-Xvfb`; `archility render` automatically wraps draw.io export
commands with `xvfb-run -a` when `$DISPLAY` is unset. External render commands
have a default 120-second timeout, adjustable with
`ARCHILITY_RENDER_TIMEOUT_SECONDS`.

A `.drawio` file whose pages hold no shapes is skipped with a warning on
stderr. draw.io refuses to export an empty page, so rendering one would fail
the whole run; fix the generator or the file that produced it.

## Tests

```bash
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -v
```

## Contributing

See `CONTRIBUTING.md`.

## License

MIT
