slartiarch 0.1.0__tar.gz

slartiarch-0.1.0/.adr-dir

@@ -0,0 +1 @@
+docs/adr

slartiarch-0.1.0/.github/scripts/check_radon.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# nounset: undefined variable outputs error message, and forces an exit
+set -u
+# errexit: abort script at first error
+set -e
+
+echo "Radon Cyclomatic Complexity below grade A:"
+PACKAGE="slarti"
+CC_COMMAND="uv run radon cc -n B ${PACKAGE}"
+CC=$($CC_COMMAND)
+$CC_COMMAND
+
+echo "Radon Maintainability Index below grade A:"
+MI_COMMAND="uv run radon mi -n B ${PACKAGE}"
+MI=$($MI_COMMAND)
+$MI_COMMAND
+
+echo "Lines of Code over 80 lines:"
+L=$(uv run radon cc --json "${PACKAGE}" | jq -r 'to_entries[] |
+  .key as $file |
+  .value[] |
+  select(.type == "method" or .type == "function") |
+  (.endline - .lineno + 1) as $length |
+  select($length > 80) |
+  "\($file):\(.lineno) - \(.name) (\($length) lines)"
+')
+echo "$L"
+
+
+if [[ ${#CC} -gt 0 || ${#MI} -gt 0 || ${#L} -gt 0 ]]; then
+  exit 1
+fi

slartiarch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+
+      - name: Install the pinned LikeC4
+        run: npm ci
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Sync deps (dev)
+        run: uv sync --group dev
+
+      - name: CI
+        run: make ci
+
+      - name: Architecture (slarti dogfoods itself)
+        run: make arch
+
+      - name: Upload code coverage
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: coverage-html
+          path: htmlcov/
+          if-no-files-found: ignore

slartiarch-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+
+# Coverage / test
+*.coverage
+.coverage*
+.htmlcov/
+.pytest_cache/
+
+# Node: the user's pinned LikeC4
+node_modules/
+
+# slarti: transient output
+build/

slartiarch-0.1.0/.nvimrc

@@ -0,0 +1,23 @@
+" lua << EOF
+" require('lazy-loader')()
+" EOF
+
+let g:gutentags_ctags_exclude += ['*/.venv/*']
+let g:projectionist_heuristics = {
+      \ 'pyproject.toml': {
+      \   'slarti/*.py': {
+      \     'type': 'function',
+      \     'alternate': [
+      \       'tests/{dirname}test_{basename}.py',
+      \       'tests/{dirname}/test_{basename}.py',
+      \     ]
+      \   },
+      \   'tests/**/test_*.py': {
+      \     'type': 'test',
+      \     'alternate': [
+      \       'slarti/{dirname}{basename}.py',
+      \       'slarti/{dirname}/{basename}.py',
+      \     ]
+      \   },
+      \ },
+      \ }

slartiarch-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.16.0
+  hooks:
+  - id: ruff-check
+  - id: ruff-format
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v2.3.0
+  hooks:
+  - id: mypy
+    additional_dependencies: []
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: check-merge-conflict
+  - id: end-of-file-fixer
+  - id: trailing-whitespace

slartiarch-0.1.0/AGENTS.md

@@ -0,0 +1,92 @@
+# Agent Guidelines
+
+This file provides guidance when working with code in this repository.
+
+## Project Overview
+
+See this projects README.md for an overview of the project, and ADR documents in docs/adr/ for architectural decisions.
+
+## Development Commands
+
+**IMPORTANT**: Always use the Makefile commands for development tasks.
+
+### Setup
+```bash
+make setup  # Set up venv and sync dependencies with uv
+```
+
+### Testing
+```bash
+make test                                    # Run all tests with pytest and coverage
+uv run pytest tests/test_foo.py             # Run specific test file
+uv run pytest tests/test_foo.py::test_name  # Run specific test
+uv run pytest -v                             # Verbose output
+```
+
+### Code Quality
+```bash
+make lint   # Check code with ruff
+make fix    # Auto-fix ruff issues
+make type   # Type check with mypy (strict mode)
+make radon  # Check cyclomatic complexity and maintainability
+make ci     # Run all CI checks (lint + type + test + radon)
+```
+
+**Before completing any feature**, run `make ci` to ensure all checks pass.
+
+## Code Quality Requirements
+
+Writing guidance:
+
+- Only include a brief description of the thing in docstrings (no arguments or return types)
+- Do not use docstrings at the beginning of files.
+
+## Project Structure
+
+```
+slarti/         # Main package source code
+tests/          # Test files (mirror slarti/ structure)
+model/          # The architecture model slarti checks itself against
+docs/adr/       # Architecture Decision Records
+docs/architecture.md  # Generated in part by slarti itself
+```
+
+## The architecture model (slarti dogfoods itself)
+
+This repository is checked by its own tool. Before committing a change that
+touches structure or domain entities, run:
+
+```bash
+slartiarch check        # the seams: OWN-*, REG-*, DOC-*
+slartiarch docs         # regenerate the diagrams and tables
+slartiarch docs --check # the drift gate CI runs
+```
+
+### Files you may edit
+
+- `model/arch/*.c4` — the LikeC4 model of slarti's own containers
+- `model/schema/slarti.yaml` — the LinkML schema of slarti's domain entities
+- `model/shapes/*.ttl` — hand-written SHACL
+- `model/constraints.yaml` — the rule registry
+- `model/data/valid/*`, `model/data/invalid/*` — fixtures, one per rule
+- prose **outside** generated regions in `docs/architecture.md`
+
+### Files you must never edit
+
+- anything under `docs/diagrams/`
+- anything between `<!-- slarti:begin ... -->` and `<!-- slarti:end ... -->`
+
+Those regions are regenerated by `slartiarch docs`; hand edits are reported as
+`DOC-1` / `DOC-2` and block the merge.
+
+### Rules
+
+- A new domain class needs an `owner` annotation naming a LikeC4 element, and
+  that element must list the class in its `owns` metadata (`OWN-1`..`OWN-5`).
+- A new SHACL shape needs a constraint in `model/constraints.yaml` referencing
+  it, and a fixture under `model/data/invalid/` that makes it fire
+  (`REG-2`, `REG-6`, `REG-7`).
+- A rule that cannot be mechanically enforced is written as `enforced_by: none`
+  with a `reason`. That is honest, not a failure.
+- `slartiarch report --json` describes every rule, shape, owned class and check ID,
+  each check with its remedy.

slartiarch-0.1.0/Makefile

@@ -0,0 +1,41 @@
+.PHONY: setup test lint type adr new coverage vulture fix radon treepeat ci arch docs domain
+
+setup:
+	uv venv
+	uv sync --python .venv/bin/python
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check .
+
+vulture:
+	uv run vulture --min-confidence 55 slarti
+
+fix:
+	uv run ruff check . --fix
+
+type:
+	uv run mypy
+
+radon:
+	uv run .github/scripts/check_radon.sh
+
+treepeat:
+	uv run treepeat detect . -i '**/node_modules/**,**/.venv/**,**/build/**'
+
+ci: test lint type radon treepeat vulture
+
+# The Python interfaces are a LinkML projection, not hand-written (see README).
+domain:
+	uv run gen-pydantic docs/slarti/linkml/slarti.yaml > slarti/domain.py
+
+# slarti dogfoods itself (I13): the architecture document is generated by the tool.
+arch:
+	uv run slartiarch doctor
+	uv run slartiarch check
+	uv run slartiarch docs --check
+
+docs:
+	uv run slartiarch docs

slartiarch-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: slartiarch
+Version: 0.1.0
+Summary: A coordination CLI for validated architecture documentation
+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: pydantic>=2.11
+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
+pip install linkml pyshacl
+```
+
+## 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/`.

slartiarch-0.1.0/README.md

@@ -0,0 +1,97 @@
+# 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
+pip install linkml pyshacl
+```
+
+## 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/`.

slartiarch-0.1.0/docs/adr/0001-python-project.md

@@ -0,0 +1,31 @@
+# 1. Python project
+
+Date: 2025-09-05
+
+## Status
+
+Accepted
+
+## Context
+
+A new project is being started that will be implemented in Python.
+
+## Decision
+
+Use a standard layout for the project with the following details:
+- Use [uv](https://docs.astral.sh/uv/) as the package manager.
+- Use [pytest](https://docs.pytest.org/en/stable/) as the test framework (with coverage).
+- Use [adr-tools](https://github.com/npryce/adr-tools) to document architectural decisions.
+
+Use the following layout for the python project:
+
+```plaintext
+project-root/
+├── slarti/
+├── tests/
+└── docs/
+```
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

slartiarch-0.1.0/docs/adr/0002-findings-are-the-interface.md

@@ -0,0 +1,45 @@
+# 2. Findings are the interface
+
+Date: 2026-07-25
+
+## Status
+
+Accepted
+
+## Context
+
+`slarti` has two consumers with different needs. A human wants to read what is
+wrong; an LLM agent — which has no memory of the repository between sessions —
+needs a stable identifier to reason about and a remedy it can act on. Exit codes
+alone carry neither.
+
+The tool also delegates every real validation to LikeC4, LinkML and pyshacl. Its
+own output must therefore be clearly distinguishable from theirs, and phrased in
+domain terms rather than tool terms: "class `Finding` has no owner", not
+`KeyError: 'owner'`.
+
+## Decision
+
+Findings, not exit codes, are the interface. Every finding carries a stable rule
+ID (`OWN-1`, `REG-2`, `DOC-1`, `ENV-1`), a file, a subject named in domain terms,
+a message and a remedy sentence. The same findings render as text or as JSON;
+`--json` changes the encoding, never the content. IDs are permanent — retired
+checks are never reused — and `slarti report --json` describes all of them.
+
+Because the findings are the contract, the entities they are about are modelled
+first-class: `Finding`, `Report`, `Constraint` and `Enforcer` are classes in
+`model/schema/slarti.yaml`, with SHACL shapes over them (`D1`, `D2`, `D3`) and a
+negative fixture per shape.
+
+Diagnostics from the delegated tools are passed through unaltered and never
+reformatted as findings.
+
+## Consequences
+
+- Agents can converge: run `slarti check --json`, apply the remedy, re-run.
+- Message wording is part of the contract, and is covered by tests.
+- Adding a check means adding an ID, a remedy sentence and a catalogue entry —
+  slightly more work than raising an exception, deliberately.
+- Rules that no model can enforce are recorded as `enforced_by: none` with a
+  reason and surface in the unverified-invariants table rather than being silently
+  absent.

slartiarch-0.1.0/docs/adr/0003-python-interfaces-are-a-linkml-projection.md

@@ -0,0 +1,54 @@
+# 3. The Python interfaces are a LinkML projection
+
+Date: 2026-07-25
+
+## Status
+
+Accepted
+
+## Context
+
+ADR-0002 made the findings the interface and modelled the entities they are about
+— `Finding`, `Report`, `Constraint`, `Enforcer` — as classes in
+`model/schema/slarti.yaml`. The implementation nevertheless carried its own
+hand-written dataclasses with the same names and roughly the same fields.
+
+Two definitions of one entity is exactly the drift `slarti` exists to catch. The
+schema could gain a slot the code never reads, or the code could gain a field the
+shapes never see, and nothing would fail. The seam checks could not help: they
+join LikeC4 to LinkML and the registry to the models, not the schema to the
+Python that claims to implement it.
+
+LinkML is a schema language whose point is projection: one definition, generated
+into whatever shape a consumer needs — SHACL for pyshacl, JSON Schema for an
+agent, Pydantic or TypeScript for an implementation. Hand-writing the Python was
+declining the one thing LinkML is best at.
+
+## Decision
+
+`slarti/domain.py` is generated from `model/schema/slarti.yaml` by `gen-pydantic`
+(`make domain`) and committed. It is the only definition of the domain entities;
+`findings.py`, `registry.py`, `models.py`, `inject.py` and `env.py` import from it
+rather than declaring their own.
+
+Behaviour stays hand-written. The generated classes carry shape — fields, ranges,
+cardinality, permissible values — and modules add the verbs around them
+(`Report.as_schema`, `registry.is_unenforced`, `Likec4Model.owners_of`). The
+serialised report is built as the generated `Report`, so `slarti check --json`
+emits the shape the schema declares by construction.
+
+Drift between the schema and the committed projection is a test failure
+(`tests/test_domain.py`), the same gate `slarti docs --check` applies to the
+document.
+
+## Consequences
+
+- A slot added to the schema is a field in the implementation after `make domain`;
+  a field the implementation wants must be argued for in the schema first.
+- An enforcer kind that is not in the `EnforcerKind` enum is now rejected when the
+  registry is read, with the permissible values named.
+- The generated module is excluded from ruff, mypy and vulture: the schema is
+  reviewed, its projection is not.
+- `pydantic` becomes a runtime dependency.
+- The same schema still generates SHACL, JSON Schema and TypeScript for other
+  consumers — the projection to Python is one target among several, not a fork.