spinagram 0.1.0__tar.gz

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

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  UV_VERSION: "0.10.4"
+  BUN_VERSION: "1.4.2"
+
+jobs:
+  web:
+    name: UI bundle (bun)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: bun install --frozen-lockfile
+        working-directory: web
+      - run: bun run build # tsc -b && vite build -> src/spinagram/ui/static
+        working-directory: web
+      - name: Committed bundle matches web/
+        run: |
+          if [ -n "$(git status --porcelain -- src/spinagram/ui/static)" ]; then
+            git status --short -- src/spinagram/ui/static
+            echo "::error::src/spinagram/ui/static is stale: run 'bun run build' in web/ and commit it"
+            exit 1
+          fi
+
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+      - run: uv run --locked --only-group dev ruff check src tests examples
+
+  test:
+    name: Tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - run: uv sync --locked --all-extras
+      - run: uv run pytest -q
+
+  build:
+    name: Build sdist + wheel (uv)
+    needs: [web, lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+      - run: uv build
+      - name: Wheel ships the UI bundle
+        run: unzip -l dist/*.whl | grep -q 'spinagram/ui/static/index.html'
+      - name: Smoke test the built wheel
+        run: |
+          uv run --isolated --no-project --with "$(ls dist/*.whl)[ui]" spinagram --help
+          uv run --isolated --no-project --with "$(ls dist/*.whl)" spinagram render examples/decision.yaml -f svg -o /tmp/out
+          test -n "$(ls /tmp/out/*.svg)"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error

spinagram-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build site (Fumadocs)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.4.2"
+      - run: bun install --frozen-lockfile
+      - name: Static export with the search index
+        run: bun run build
+        env:
+          NEXT_PUBLIC_BASE_PATH: /spinagram # served at https://dangerousplay.github.io/spinagram/
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/out/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

spinagram-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+# Push a tag that matches the version in pyproject.toml, with the changelog regenerated for it:
+#   uv version --bump minor
+#   uvx git-cliff --tag "v$(uv version --short)" -o CHANGELOG.md
+#   git commit -am "chore(release): v$(uv version --short)"
+#   git tag "v$(uv version --short)" && git push --follow-tags
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: ci
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/spinagram/
+    permissions:
+      id-token: write # PyPI trusted publishing (OIDC), no API token stored
+      contents: write # GitHub release
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # git-cliff reads the whole history and the tags
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.10.4"
+      - name: Tag matches project version
+        run: |
+          v="$(uv version --short)"
+          if [ "v$v" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject version $v"
+            exit 1
+          fi
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: uv publish --trusted-publishing always
+      # The newest section of the committed changelog. `git-cliff --latest` would split at the
+      # last pre-release tag even though cliff.toml ignores it, leaving a final release almost empty.
+      - name: Release notes (CHANGELOG.md)
+        run: awk '/^## \[/ { n++ } n == 1' CHANGELOG.md > RELEASE_NOTES.md
+      - name: GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          pre=""
+          case "$GITHUB_REF_NAME" in *a[0-9]*|*b[0-9]*|*rc[0-9]*|*.dev[0-9]*) pre="--prerelease" ;; esac
+          gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md $pre

spinagram-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+out/
+.pytest_cache/

spinagram-0.1.0/.specs/LESSONS.md

@@ -0,0 +1,153 @@
+# LESSONS - auto-maintained by scripts/lessons.py
+
+> Machine-owned. Do NOT hand-edit. Changes are overwritten on the next `lessons.py` write.
+> Canonical state lives in `.specs/lessons.json`. Edit lessons only via the script.
+> promote_threshold=2 distinct features · window_days=45 · quarantine_threshold=2
+
+## Confirmed (load these at Specify/Design)
+
+Corroborated across multiple features. Safe to apply as guidance.
+
+_none_
+
+## Candidates (under observation - do NOT load as guidance yet)
+
+Seen once or not yet corroborated. Tracked, not trusted.
+
+### L-001 - Pin determinism with a golden output hash checked across many PYTHONHASHSEED values, not a few in-process runs.
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: layered-layout
+- evidence: M9b (hash tie-break) (tests)
+- last seen: 2026-10-12T04:39:39Z
+
+### L-002 - Give placement ACs a measurable bound (e.g. pill within 6 px of its segment) before writing the test.
+- signal: `spec_precision_gap` · recurrence: 1 feature(s) · scope: `spec` · harmful: 0
+- features: layered-layout
+- evidence: LAY-12 (spec)
+- last seen: 2026-10-12T04:39:39Z
+
+### L-003 - Guard output-unchanged-without-the-feature with a golden render captured before the feature, not an identity check.
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: css-styling
+- evidence: M15 (CSS-27) (tests)
+- last seen: 2026-10-12T04:39:39Z
+
+### L-004 - When an AC describes geometry that depends on layout (bars spanning branches), test the laid-out result, not the default size.
+- signal: `ac_gap` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: behavior-diagrams
+- evidence: BHV-02 / G1 (tests)
+- last seen: 2026-10-12T04:39:39Z
+
+### L-005 - Never pipe the test command into tail before chaining a commit; check pytest's own exit code.
+- signal: `gate_fail` · recurrence: 1 feature(s) · scope: `process` · harmful: 0
+- features: layered-layout
+- evidence: 99549c5 (process)
+- last seen: 2026-10-12T04:39:39Z
+
+### L-006 - Parse value formats with a full match; lenient prefix parsing hides upstream bugs from tests.
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `src` · harmful: 0
+- features: css-styling
+- evidence: F9 / R3 (CSS-16) (src)
+- last seen: 2026-10-12T04:41:36Z
+
+### L-007 - Check optional spec keys with is-None, not truthiness, so falsy wrong-typed values like 0, false or {} still fail validation
+- signal: `ac_gap` · recurrence: 1 feature(s) · scope: `yaml-loaders` · harmful: 0
+- features: diagram-catalog
+- evidence: META-03 src/spinagram/yaml_io.py:55 (yaml-loaders)
+- last seen: 2026-10-12T17:25:04Z
+
+### L-008 - Keep every data transformation an AC names (sorting, filtering, sampling) in the unit-tested pure-logic module, not inline in a component
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `web-ui` · harmful: 0
+- features: catalog-previews
+- evidence: M16 web/src/PacksPage.tsx:45 (PREV-07) (web-ui)
+- last seen: 2026-10-12T17:38:46Z
+
+### L-009 - When an AC requires an error response to carry the error message, assert the message text, not just that an error field is present
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `routes` · harmful: 0
+- features: catalog-previews
+- evidence: M17 tests/test_ui.py:161 (PREV-03) (routes)
+- last seen: 2026-10-12T17:38:46Z
+
+### L-010 - Assert that styled values reach the rendered scene shapes, not only the computed style map
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `css` · harmful: 0
+- features: annotations
+- evidence: validation.md M35/M36 src/spinagram/annotate.py:207,228 (css)
+- last seen: 2026-10-12T18:18:23Z
+
+### L-011 - Derive expected geometry independently instead of reusing the function under test
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: annotations
+- evidence: validation.md M07 tests/test_annotations.py:330 (tests)
+- last seen: 2026-10-12T18:18:23Z
+
+### L-012 - Assert the exact numeric value in diagnostic messages, not just the message prefix
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `qa` · harmful: 0
+- features: annotations
+- evidence: validation.md M37 tests/test_annotations.py:726 (qa)
+- last seen: 2026-10-12T18:18:23Z
+
+### L-013 - Cover first-match rules with a fixture that has at least two candidates
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: annotations
+- evidence: validation.md M38 src/spinagram/model.py:492 (tests)
+- last seen: 2026-10-12T18:18:23Z
+
+### L-014 - Give every clause of a multi-clause acceptance criterion its own assertion
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: annotations
+- evidence: validation.md M21/M39/M40 ANN-03 ANN-10 ANN-22 (tests)
+- last seen: 2026-10-12T18:18:23Z
+
+### L-015 - When a spec says first-use order over mixed element types, state the order across types
+- signal: `spec_precision_gap` · recurrence: 1 feature(s) · scope: `spec` · harmful: 0
+- features: annotations
+- evidence: validation.md ANN-01 src/spinagram/annotate.py:84 (spec)
+- last seen: 2026-10-12T18:18:23Z
+
+### L-016 - Copy fixture paths from the real upstream source so every naming form it actually uses, including optional-group branches, is exercised
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: selfhosted-icons
+- evidence: validation.md M02 src/spinagram/icon_packs/network.yaml:13 tests/test_icon_packs.py:51 (ICON-09) (tests)
+- last seen: 2026-10-12T19:04:51Z
+
+### L-017 - Test each layout property on every band side or branch it applies to, not only the default side
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: legend-css
+- evidence: validation.md M12/M13 src/spinagram/annotate.py:187,370 (LCSS-08) (tests)
+- last seen: 2026-10-12T20:03:34Z
+
+### L-018 - When an explicit setting overrides an automatic rule, test it under the condition that triggers the rule
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: legend-css
+- evidence: validation.md M15 src/spinagram/annotate.py:354 (LCSS-08) (tests)
+- last seen: 2026-10-12T20:03:34Z
+
+### L-019 - When a default moves from code to the stylesheet, test that every loader path, including YAML, leaves the value unset
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `yaml-loaders` · harmful: 0
+- features: legend-css
+- evidence: validation.md M30 src/spinagram/yaml_io.py:140 (LCSS-04) (yaml-loaders)
+- last seen: 2026-10-12T20:03:34Z
+
+### L-020 - When new enum values are added, cover each one in every consumer that branches on it, including qa checks
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: legend-css
+- evidence: validation.md M20/M21 src/spinagram/annotate.py:525-526 (ANN-12 for left/top) (tests)
+- last seen: 2026-10-12T20:03:34Z
+
+### L-021 - Give every clause of a multi-clause acceptance criterion its own assertion
+- signal: `ac_gap` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: legend-css
+- evidence: validation.md LCSS-05 clause 2 tests/test_legend_css.py:42 (tests)
+- last seen: 2026-10-12T20:03:34Z
+
+### L-022 - When one function reserves space and another draws into it, assert both against the same independently derived size
+- signal: `surviving_mutant` · recurrence: 1 feature(s) · scope: `tests` · harmful: 0
+- features: legend-css
+- evidence: validation.md iter2 M12 src/spinagram/annotate.py:187 (LCSS-08) (tests)
+- last seen: 2026-10-12T20:09:01Z
+
+## Quarantined (failed when applied - ignore)
+
+A confirmed lesson that recurred alongside failure. Kept for the maintainer to review.
+
+_none_

spinagram-0.1.0/.specs/features/annotations/design.md

@@ -0,0 +1,140 @@
+# Annotations Design
+
+**Spec**: `.specs/features/annotations/spec.md`
+**Status**: Approved
+
+---
+
+## Architecture Overview
+
+Annotations are model data (`Diagram.annotations`) turned into ordinary scene primitives by one new module,
+`spinagram/annotate.py`. Because the scene already renders natively in SVG, PNG, PowerPoint and Figma (rect and
+pill shapes with labels, icons and shadows; connectors with markers; text), every annotation is native in every
+backend without backend changes. CSS reaches annotations through new elements in the style tree.
+
+```mermaid
+graph TD
+    API[Python: add_legend / step / callout / note variant] --> M[model.Annotations]
+    YAML[YAML: annotations:, kind: note + variant] --> M
+    M --> CSS[css.tree: legend, step, callout elements]
+    M --> BAND[annotate.band: side + size]
+    BAND --> AREA[autolayout._area minus band]
+    AREA --> LAYOUT[engines place content]
+    LAYOUT --> B[layout._Builder.build]
+    B --> ANN[annotate.Annotator: panels, badges, callouts]
+    CSS --> ANN
+    ANN --> SCENE[Shapes, Connectors, Text in the scene]
+    SCENE --> SVG & PPTX & FIGMA
+    ANN --> QA[qa.check: legend unused, steps duplicate, band overflow/overlap, callout overlap]
+```
+
+Order inside `build`: zones → nodes → tables → edges → **step badges** → **panels** → **callouts** → chrome.
+Callouts come last among content so they are placed against every other shape.
+
+---
+
+## Code Reuse Analysis
+
+| Component | Location | How to Use |
+| --------- | -------- | ---------- |
+| `_Builder.pill`, `_decorate`, `_css`, `_text` | `src/spinagram/layout.py:58-96` | Badges are pills (w = h → circle); panels and bubbles are rect shapes decorated with computed CSS |
+| `Connector` with markers | `src/spinagram/scene.py:110` | Legend edge samples, callout leader lines (`marker_end="circle"`) |
+| `Label`/`TextBlock`/`wrap_paragraphs` | `src/spinagram/scene.py`, `text.py` | Panel rows, step texts, bubble text |
+| `_area` | `src/spinagram/autolayout/__init__.py:236` | Subtract the band |
+| `css.tree` / `compute` | `src/spinagram/css.py:521` | Add annotation elements; computed styles under keys `legend`, `step`, `callout:<i>` |
+| `qa.check` / `Issue` | `src/spinagram/qa.py:49` | New checks fed by `scene.annotation_issues` |
+| Node kind `note` | `src/spinagram/model.py:315` | Variants as a node attribute; CSS class added |
+
+---
+
+## Components
+
+### model: Annotations
+
+- **Location**: `src/spinagram/model.py`
+- **Interfaces**:
+  - `LegendSpec(title="Legend", items: dict[str, str] | None, position="right")`
+  - `Step(n: int, text: str, edge: int | None, node: str | None)`
+  - `Callout(target: str, text: str, title: str | None, kind="info", side="auto", cls=None, css=None)`
+  - `Annotations(legend: LegendSpec | None, steps: list[Step], callouts: list[Callout])` as `Diagram.annotations`
+  - `Diagram.add_legend(items=None, *, title="Legend", position="right")`
+  - `Diagram.step(text, *, on, n=None)`; `on` = `Edge`, `Node`, node id, or `(src, dst)`; `Edge.step(text, n=None)`
+  - `Diagram.callout(target, text, *, title=None, kind="info", side="auto", class_=None, css=None)`
+  - `Diagram.note(..., variant="sticky")`; validated against `NOTE_VARIANTS`
+
+### annotate module
+
+- **Location**: `src/spinagram/annotate.py`
+- **Interfaces**:
+  - `legend_entries(d) -> list[Entry]` (key, label, kind node|edge|style|icon, element key or None)
+  - `band(d, theme) -> tuple[str, float] | None` side and thickness before layout
+  - `class Annotator(builder)`: `badges(connectors) -> list[Item]`, `panels() -> list[Item]`, `callouts(obstacles) -> list[Item]`, `issues -> list[tuple[str, str, str]]`
+- **Constants**: `BAND_WIDTH = 360`, `BAND_GAP = 32`, `BADGE = 30`, `CALLOUT_W = 320`, `KINDS = {info: primary, tip: success, warning: warning, risk: alert}`
+
+### Theme
+
+- **Location**: `src/spinagram/themes/default/theme.yaml`
+- **Adds**: colours `success`, `success-bg`, `success-text`; `defaults.annotations: {band: 360, gap: 32, badge: 30, callout_width: 320, title_size: 20, text_size: 16}`
+
+### CSS elements
+
+- **Location**: `src/spinagram/css.py`
+- **Adds** under the root: `legend` (key `legend`), `step` (key `step:<n>`), `callout` (classes = kind + `class_`, key `callout:<i>`); note nodes get the variant as a class.
+
+---
+
+## Data Models
+
+```python
+@dataclass
+class Annotations:
+    legend: LegendSpec | None = None
+    steps: list[Step] = field(default_factory=list)
+    callouts: list[Callout] = field(default_factory=list)
+```
+
+YAML:
+
+```yaml
+annotations:
+  legend: {title: Legend, position: right, items: {".security": Security control, "edge.async": Async}}
+  steps: [{on: "users -> dns", text: Users resolve the domain}, {on: alb, n: 3, text: ...}]
+  callouts: [{on: pvc, text: Snapshots every 6 h, kind: warning, side: auto}]
+nodes:
+  - {id: n1, kind: note, variant: card, title: Why, text: ...}
+```
+
+---
+
+## Error Handling Strategy
+
+| Error Scenario | Handling | User Impact |
+| -------------- | -------- | ----------- |
+| Unknown callout kind / note variant | `ValueError` naming allowed values | Spec load / build error |
+| Step `on` matches no edge or node | `ValueError` naming the reference | Spec load error |
+| Callout target from another diagram | `ValueError` | Build error |
+| Legend key unused | Drawn from theme default; `check` issue | Warning in check |
+| Panels exceed the band | Drawn clipped to content; `check` overflow | Warning in check |
+| Callout has no free side | Placed on first side; `check` overlap | Warning in check |
+
+---
+
+## Risks & Concerns
+
+| Concern | Location (file:line) | Impact | Mitigation |
+| ------- | -------------------- | ------ | ---------- |
+| `_Builder.build` is long and order-sensitive | `src/spinagram/layout.py:304` | New steps could disturb chrome/z-order | Annotations live in `annotate.py`; build only calls three methods at fixed points |
+| `build_scene` is `lru_cache`d on the diagram | `src/spinagram/layout.py:441` | Mutable annotation lists must hash/compare like other fields | Dataclasses with `eq=True` default; covered by existing cache behaviour (diagram is copied in apply_layout) |
+| Manual-layout diagrams have no area to shrink | `src/spinagram/autolayout/__init__.py:236` | Band can overlap content | Spec ANN-12: draw the band at the edge and report overlap |
+| Golden SVG tests for unannotated diagrams | `tests/` | Accidental output change | No annotations → no new items; full suite gates every task |
+| PowerPoint circle badges | `src/spinagram/backends/pptx.py` | Pill with w = h must stay a circle | Integration test inspects the PPTX shape geometry |
+
+---
+
+## Tech Decisions
+
+| Decision | Choice | Rationale |
+| -------- | ------ | --------- |
+| Render path | Compose existing scene primitives | Native in all four backends with no backend code |
+| Module boundary | One `annotate.py` | Keeps `layout.py` from growing further |
+| Placement of callouts | Greedy side order with rectangle overlap tests | Deterministic, explainable, cheap |