Metadata-Version: 2.4
Name: slartiarch
Version: 0.6.0
Summary: A coordination CLI for validated architecture documentation
Project-URL: Repository, https://github.com/dsummersl/slartiarch
Author-email: Dane Summers <dsummersl@gmail.com>
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: linkml-runtime>=1.11.1
Requires-Dist: linkml<2,>=1.11
Requires-Dist: pydantic>=2.11
Requires-Dist: pyshacl>=0.25
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rdflib>=7.6
Requires-Dist: tomli-w>=1.2
Requires-Dist: typer>=0.27
Description-Content-Type: text/markdown

# slartiarch

<div align="center">
  <img src="https://static.wikia.nocookie.net/hitchhikers/images/f/f9/Slartibartfast_comics.png/revision/latest?cb=20230703161559" width="200" alt="Slartibartfast">
</div>

Slartibartfast: the architect. From *The Hitchhiker's Guide to the Galaxy*, the curmudgeonly designer of Norway's fjords — and the namesake of this tool.

slartiarch is a coordination CLI that checks consistency between [LikeC4](https://likec4.dev) architecture
diagrams, [LinkML](https://linkml.io) schemas, and [SHACL](https://www.w3.org/TR/shacl/) shapes.
It also regenerates the diagrams in your architecture document so the prose never drifts.

Each tool is useful on its own with no slartiarch involved. slartiarch adds the seams — rules that span
two tools, and checks that the answers still agree.

## Install

```bash
uv tool install slartiarch
npm install likec4
```

## Use

```bash
slartiarch init          # scaffold docs/slarti/ and a config
slartiarch doctor        # resolved paths and tool versions
slartiarch check         # run all validations (CI command)
slartiarch check --json  # structured output for automation
slartiarch docs          # regenerate diagrams and tables into your docs
slartiarch docs --check  # fail if committed output is stale
slartiarch report        # every rule, shape, and check ID
slartiarch report --json # fully detailed, for agents
```

Run `slartiarch` with no arguments for a full reference. `slartiarch report --json` describes every
rule, enforcer kind, check ID, and remedy.

## Layout

```
docs/
  architecture.md      prose with generated diagram and table regions
  diagrams/            GENERATED — never hand-edited
  slarti/
    likec4/*.c4        LikeC4 architecture model
    linkml/*.yaml      LinkML domain schemas
    shacl/*.ttl        hand-written SHACL shapes
    constraints.yaml   rule registry
    data/valid/*       fixtures that must pass validation
    data/invalid/*     one fixture per SHACL rule; each must fail
```

## How the tools work together

LikeC4 draws the system. LinkML defines the entities. SHACL validates instances. Each
works standalone:

```bash
likec4 start docs/slarti/likec4                  # live architecture browser
gen-pydantic docs/slarti/linkml/slarti.yaml       # Python interfaces from schema
pyshacl -s docs/slarti/shacl/invariants.ttl ...   # validate RDF against shapes
```

A constraint in the registry ties them together:

```yaml
# docs/slarti/constraints.yaml
- id: D8
  statement: A subtask belongs to the same list as its parent.
  enforced_by:
    kind: shacl_shape
    ref: "todo:SubtaskSharesListWithParent"
    fixture: docs/slarti/data/invalid/D8.yaml
```

Running `slartiarch check` walks the seams: it verifies the shape exists, the fixture
fails (proving the shape fires), both halves of the ownership claim agree, and the
constraint table in your document still matches. `slartiarch docs` regenerates the Mermaid
diagrams and tables so the architecture document never goes stale.

## Dogfooding

This repository's [docs/architecture.md](docs/architecture.md) is generated by slartiarch from
`docs/slarti/`. CI runs `slartiarch check` and `slartiarch docs --check`.

## Dev

```bash
make setup   # uv venv + sync
npm ci       # pinned LikeC4
make domain  # regenerate slarti/domain.py from the LinkML schema
make ci      # tests, lint, types, complexity, duplication, dead code
```

Architecture decisions live in `docs/adr/`.
