system-diff 0.1.0__tar.gz

system_diff-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.png binary

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

@@ -0,0 +1,41 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # macOS is left out for now: on this repository its runners were never assigned (cancelled after 15
+        # minutes in the queue, no step run). Add macos-latest back once they are.
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+
+  map:
+    # The README's system map is drawn from this repository's own code: it must be current.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - name: The system map is current (if not, run the two commands below and commit)
+        run: |
+          system-diff map --dir . --out docs/diagrams --check
+          system-diff readme --json docs/diagrams/system.json --check

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

@@ -0,0 +1,41 @@
+name: release
+
+# A tag vX.Y.Z publishes that version to PyPI through trusted publishing: no token is stored anywhere. PyPI accepts the
+# upload only from this workflow, in this repository, in the `pypi` environment.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: The tag is the version in pyproject.toml
+        run: |
+          v=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          [ "v$v" = "$GITHUB_REF_NAME" ] || { echo "tag $GITHUB_REF_NAME, but pyproject.toml says $v"; exit 1; }
+      - run: python -m pip install build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

system_diff-0.1.0/.github/workflows/system-diff.yml

@@ -0,0 +1,51 @@
+name: system diff
+
+# What a pull request does to the system, as a comment on it and in the run's summary; the picture is the run's
+# "system-diff" artifact. Copy this file into another repository to get the same there.
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - name: Draw what this pull request does to the system
+        run: system-diff diff --base "origin/${{ github.base_ref }}" --head HEAD --out system-diff-out
+      - name: Write the summary
+        run: |
+          {
+            echo '<!-- system-diff -->'
+            echo '### System diff'
+            echo
+            cat system-diff-out/headline.txt
+            echo
+            echo '```'
+            cat system-diff-out/plan.txt
+            echo '```'
+            echo
+            echo "The picture: the **system-diff** artifact of [this run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})."
+          } > system-diff-out/comment.md
+          cat system-diff-out/comment.md >> "$GITHUB_STEP_SUMMARY"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: system-diff
+          path: system-diff-out
+      - name: Comment on the pull request
+        # A pull request from a fork gets a read-only token: it has the summary and the artifact instead.
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh pr comment "${{ github.event.pull_request.number }}" --body-file system-diff-out/comment.md --edit-last \
+            || gh pr comment "${{ github.event.pull_request.number }}" --body-file system-diff-out/comment.md

system_diff-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv*/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+/out/
+docs/diagrams/*.png

system_diff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 simplifiedmachine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

system_diff-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: system-diff
+Version: 0.1.0
+Summary: Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or removes. No dependencies; SVG pictures for PRs and READMEs.
+Project-URL: Homepage, https://github.com/simplifiedmachine/system-diff
+Project-URL: Documentation, https://github.com/simplifiedmachine/system-diff/wiki
+Project-URL: Issues, https://github.com/simplifiedmachine/system-diff/issues
+Author: simplifiedmachine
+License-Expression: MIT
+License-File: LICENSE
+Keywords: architecture,code-review,code-visualization,developer-tools,diagrams,pull-requests,system-design
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mcp>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
+Provides-Extra: png
+Requires-Dist: playwright>=1.40; extra == 'png'
+Description-Content-Type: text/markdown
+
+# system-diff
+
+Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or
+removes. No dependencies; SVG pictures for PRs and READMEs.
+
+<!-- system-map:begin -->
+![System map, generated from the code](https://raw.githubusercontent.com/simplifiedmachine/system-diff/main/docs/diagrams/system.svg)
+
+<details><summary>How this map is made</summary>
+
+Regenerated by `system-diff` from the code: the parts and their columns from `system-diff.toml`, the connections from imports, API calls and the settings each part reads, the outside systems from the settings a deploy configuration sets, and the tables from the migrations. Parts used everywhere are drawn without the arrows into them, and each part keeps only its strongest connections; `system-diff map` writes all of them to `system.json`.
+
+Read by the code but set by no deploy configuration, so not drawn: Headless Chromium (Docker or Playwright) (png).
+
+</details>
+<!-- system-map:end -->
+
+## What it does
+
+- **`map`**: reads a commit straight from git (no checkout) or a folder, and writes `system.json` (everything it
+  found) and `system.svg` (the picture): a column per role, from what people use through entry points, logic and data
+  access to stored data and outside systems.
+- **`diff`**: the typed difference between two commits, or a commit and your working tree: parts, endpoints,
+  connections, outside systems, tables, settings and deployment files added, changed or removed. One sentence
+  (`headline.txt`), the exact list (`plan.txt`, like `terraform plan`), and a picture of only what changed, with the
+  parts it touches beside it (`diff.svg`). `--narrate` adds a plain-words summary from your own LLM.
+- **`readme`**: keeps a generated system map in your README, between two markers.
+- **`draw`**: hand-made pictures in the same look, from small JSON specs: maps, stages of a process, sequences.
+
+Deterministic: the same code gives the same picture, byte for byte, and a part that did not change keeps its place.
+
+## Install
+
+```sh
+pipx install system-diff
+```
+
+Python 3.11 or newer, nothing else. `pip install "system-diff[png]"` adds PNG output through Playwright; `system-diff
+png` also uses Docker when it is there.
+
+## Use
+
+```sh
+system-diff map --dir . --out docs/diagrams          # the system as it is now
+system-diff diff --base origin/main --out out        # what this branch does to it
+system-diff diff --base HEAD --head . --out out      # what your uncommitted work does to it
+system-diff readme --json docs/diagrams/system.json  # refresh the map in README.md
+```
+
+With no config, every folder of code is a part named by its path. A `system-diff.toml` at the repository root names the
+parts and says what is what:
+
+```toml
+tests = ["tests/**"]
+
+[code]
+roots = ["app/", "web/src/"]
+
+[[components]]
+id = "api"
+label = "API"
+kind = "interface"          # ui | interface | logic | data: the column it is drawn in
+paths = ["app/api/**"]
+
+[[externals]]
+id = "postgres"
+label = "PostgreSQL"
+shape = "db"
+env = ["DATABASE_URL"]      # the settings that reach it
+```
+
+Every key, and how the code is read: [the wiki](https://github.com/simplifiedmachine/system-diff/wiki).
+
+## In pull requests
+
+This repository runs system-diff on itself: the map above is regenerated from its own code, CI fails when it is out of
+date, and every pull request gets its system diff as a comment (`.github/workflows/system-diff.yml`, which you can
+copy).
+
+## With AI coding agents
+
+When an agent changes the code with you, the question is what it did to the system. system-diff answers it as you go:
+
+```sh
+pipx install system-diff
+pipx inject system-diff mcp  # the MCP server's one dependency
+system-diff setup claude     # the hook, a skill and the MCP server, in one step (--scope project, --undo)
+system-diff watch            # http://127.0.0.1:8765/ : the system diff since you last marked it seen
+```
+
+- **After every Claude Code turn**, one line says what changed in the system since your checkpoint ("Adds 1 endpoint
+  (DELETE /api/orders/{id}); changes 1 table (public.orders)."), or nothing when nothing structural did.
+- **The live page** redraws as files change. Press **Mark as seen** once you have understood it: the next diff then
+  shows only what is new to you. `system-diff checkpoint` does the same from the terminal.
+- **The MCP server** gives the agent `system_diff` (the exact plan to explain from, and the picture), `system_map`,
+  `draw` (pictures of processes and sequences in the same look) and `checkpoint`.
+- The working tree is read as a snapshot (untracked files included) without touching your index, HEAD or branches,
+  and the checkpoint lives under `refs/system-diff/`, in your clone only.
+
+## License
+
+MIT

system_diff-0.1.0/README.md

@@ -0,0 +1,102 @@
+# system-diff
+
+Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or
+removes. No dependencies; SVG pictures for PRs and READMEs.
+
+<!-- system-map:begin -->
+![System map, generated from the code](https://raw.githubusercontent.com/simplifiedmachine/system-diff/main/docs/diagrams/system.svg)
+
+<details><summary>How this map is made</summary>
+
+Regenerated by `system-diff` from the code: the parts and their columns from `system-diff.toml`, the connections from imports, API calls and the settings each part reads, the outside systems from the settings a deploy configuration sets, and the tables from the migrations. Parts used everywhere are drawn without the arrows into them, and each part keeps only its strongest connections; `system-diff map` writes all of them to `system.json`.
+
+Read by the code but set by no deploy configuration, so not drawn: Headless Chromium (Docker or Playwright) (png).
+
+</details>
+<!-- system-map:end -->
+
+## What it does
+
+- **`map`**: reads a commit straight from git (no checkout) or a folder, and writes `system.json` (everything it
+  found) and `system.svg` (the picture): a column per role, from what people use through entry points, logic and data
+  access to stored data and outside systems.
+- **`diff`**: the typed difference between two commits, or a commit and your working tree: parts, endpoints,
+  connections, outside systems, tables, settings and deployment files added, changed or removed. One sentence
+  (`headline.txt`), the exact list (`plan.txt`, like `terraform plan`), and a picture of only what changed, with the
+  parts it touches beside it (`diff.svg`). `--narrate` adds a plain-words summary from your own LLM.
+- **`readme`**: keeps a generated system map in your README, between two markers.
+- **`draw`**: hand-made pictures in the same look, from small JSON specs: maps, stages of a process, sequences.
+
+Deterministic: the same code gives the same picture, byte for byte, and a part that did not change keeps its place.
+
+## Install
+
+```sh
+pipx install system-diff
+```
+
+Python 3.11 or newer, nothing else. `pip install "system-diff[png]"` adds PNG output through Playwright; `system-diff
+png` also uses Docker when it is there.
+
+## Use
+
+```sh
+system-diff map --dir . --out docs/diagrams          # the system as it is now
+system-diff diff --base origin/main --out out        # what this branch does to it
+system-diff diff --base HEAD --head . --out out      # what your uncommitted work does to it
+system-diff readme --json docs/diagrams/system.json  # refresh the map in README.md
+```
+
+With no config, every folder of code is a part named by its path. A `system-diff.toml` at the repository root names the
+parts and says what is what:
+
+```toml
+tests = ["tests/**"]
+
+[code]
+roots = ["app/", "web/src/"]
+
+[[components]]
+id = "api"
+label = "API"
+kind = "interface"          # ui | interface | logic | data: the column it is drawn in
+paths = ["app/api/**"]
+
+[[externals]]
+id = "postgres"
+label = "PostgreSQL"
+shape = "db"
+env = ["DATABASE_URL"]      # the settings that reach it
+```
+
+Every key, and how the code is read: [the wiki](https://github.com/simplifiedmachine/system-diff/wiki).
+
+## In pull requests
+
+This repository runs system-diff on itself: the map above is regenerated from its own code, CI fails when it is out of
+date, and every pull request gets its system diff as a comment (`.github/workflows/system-diff.yml`, which you can
+copy).
+
+## With AI coding agents
+
+When an agent changes the code with you, the question is what it did to the system. system-diff answers it as you go:
+
+```sh
+pipx install system-diff
+pipx inject system-diff mcp  # the MCP server's one dependency
+system-diff setup claude     # the hook, a skill and the MCP server, in one step (--scope project, --undo)
+system-diff watch            # http://127.0.0.1:8765/ : the system diff since you last marked it seen
+```
+
+- **After every Claude Code turn**, one line says what changed in the system since your checkpoint ("Adds 1 endpoint
+  (DELETE /api/orders/{id}); changes 1 table (public.orders)."), or nothing when nothing structural did.
+- **The live page** redraws as files change. Press **Mark as seen** once you have understood it: the next diff then
+  shows only what is new to you. `system-diff checkpoint` does the same from the terminal.
+- **The MCP server** gives the agent `system_diff` (the exact plan to explain from, and the picture), `system_map`,
+  `draw` (pictures of processes and sequences in the same look) and `checkpoint`.
+- The working tree is read as a snapshot (untracked files included) without touching your index, HEAD or branches,
+  and the checkpoint lives under `refs/system-diff/`, in your clone only.
+
+## License
+
+MIT

system_diff-0.1.0/docs/diagrams/system.json

@@ -0,0 +1,236 @@
+{
+ "ref": "working tree",
+ "components": {
+  "cli": {
+   "label": "Command line",
+   "layer": "",
+   "kind": "interface",
+   "order": 0,
+   "container": "",
+   "declared": true,
+   "files": 3,
+   "lines": 227,
+   "hub": false,
+   "quiet": false
+  },
+  "agent": {
+   "label": "Claude Code hook and setup",
+   "layer": "",
+   "kind": "interface",
+   "order": 2,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 197,
+   "hub": false,
+   "quiet": false
+  },
+  "compare": {
+   "label": "Checkpoints and snapshots",
+   "layer": "",
+   "kind": "logic",
+   "order": 4,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 105,
+   "hub": false,
+   "quiet": false
+  },
+  "config": {
+   "label": "Config",
+   "layer": "",
+   "kind": "logic",
+   "order": 5,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 106,
+   "hub": false,
+   "quiet": false
+  },
+  "diff": {
+   "label": "Typed diff",
+   "layer": "",
+   "kind": "logic",
+   "order": 7,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 171,
+   "hub": false,
+   "quiet": false
+  },
+  "extract": {
+   "label": "Extraction",
+   "layer": "",
+   "kind": "logic",
+   "order": 6,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 279,
+   "hub": false,
+   "quiet": false
+  },
+  "graph": {
+   "label": "Map layout",
+   "layer": "",
+   "kind": "logic",
+   "order": 8,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 209,
+   "hub": false,
+   "quiet": false
+  },
+  "mcp": {
+   "label": "MCP server",
+   "layer": "",
+   "kind": "interface",
+   "order": 1,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 206,
+   "hub": false,
+   "quiet": false
+  },
+  "narrate": {
+   "label": "LLM summary",
+   "layer": "",
+   "kind": "logic",
+   "order": 11,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 141,
+   "hub": false,
+   "quiet": false
+  },
+  "pictures": {
+   "label": "SVG pictures",
+   "layer": "",
+   "kind": "logic",
+   "order": 9,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 550,
+   "hub": true,
+   "quiet": false
+  },
+  "png": {
+   "label": "PNG rendering",
+   "layer": "",
+   "kind": "logic",
+   "order": 12,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 121,
+   "hub": false,
+   "quiet": false
+  },
+  "readme": {
+   "label": "README section",
+   "layer": "",
+   "kind": "logic",
+   "order": 10,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 39,
+   "hub": false,
+   "quiet": false
+  },
+  "sources": {
+   "label": "Git and folder sources",
+   "layer": "",
+   "kind": "data",
+   "order": 13,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 76,
+   "hub": false,
+   "quiet": false
+  },
+  "watch": {
+   "label": "Live page",
+   "layer": "",
+   "kind": "interface",
+   "order": 3,
+   "container": "",
+   "declared": true,
+   "files": 1,
+   "lines": 177,
+   "hub": false,
+   "quiet": false
+  }
+ },
+ "flows": {
+  "agent>compare": 1,
+  "agent>sources": 1,
+  "cli>agent": 2,
+  "cli>compare": 1,
+  "cli>config": 2,
+  "cli>diff": 1,
+  "cli>extract": 2,
+  "cli>graph": 2,
+  "cli>mcp": 1,
+  "cli>narrate": 1,
+  "cli>pictures": 1,
+  "cli>png": 1,
+  "cli>readme": 1,
+  "cli>sources": 1,
+  "cli>watch": 1,
+  "compare>config": 1,
+  "compare>diff": 1,
+  "compare>extract": 1,
+  "compare>sources": 1,
+  "diff>extract": 1,
+  "diff>sources": 1,
+  "extract>config": 1,
+  "graph>diff": 1,
+  "graph>pictures": 1,
+  "mcp>compare": 1,
+  "mcp>config": 1,
+  "mcp>extract": 1,
+  "mcp>graph": 1,
+  "mcp>pictures": 1,
+  "mcp>sources": 1,
+  "readme>pictures": 1,
+  "watch>compare": 1,
+  "watch>graph": 1
+ },
+ "api": {},
+ "routes": {},
+ "externals": {},
+ "dormant": {
+  "chromium": {
+   "label": "Headless Chromium (Docker or Playwright)",
+   "shape": "",
+   "used_by": [
+    "png"
+   ]
+  }
+ },
+ "internal": {},
+ "env": {
+  "png": [
+   "SYSTEM_DIFF_RENDER_IMAGE"
+  ]
+ },
+ "containers": {},
+ "container_labels": {},
+ "tables": {},
+ "store": "postgres",
+ "migrations": [],
+ "tests": {
+  "tests/conftest.py": 1,
+  "tests/test_checkpoint_watch_mcp.py": 1,
+  "tests/test_system_diff.py": 1
+ }
+}