seamcheck 0.1.0__tar.gz

seamcheck-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+node_modules/
+.ruff_cache/
+.pytest_cache/

seamcheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dardameiz
+
+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.

seamcheck-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: seamcheck
+Version: 0.1.0
+Summary: Find the code your project no longer connects to - and the connections it only thinks it has.
+Project-URL: Source, https://github.com/dardameiz/seamcheck
+Project-URL: Issues, https://github.com/dardameiz/seamcheck/issues
+Author: dardameiz
+License-Expression: MIT
+License-File: LICENSE
+Keywords: connectivity,dead-code,django,mcp,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: django>=5.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: models
+Requires-Dist: django-extensions>=4.0; extra == 'models'
+Provides-Extra: node
+Requires-Dist: nodejs-wheel-binaries>=20; extra == 'node'
+Description-Content-Type: text/markdown
+
+# Seamcheck
+
+**Your AI wrote 400 lines. Which of them are actually wired to anything?**
+
+Seamcheck reads a Django + JavaScript project and tells you what connects to what — which
+`fetch()` lands on which view, which template element the JS is reaching for, which CSS
+rule nothing has referenced since 2023. Then it tells you what it *couldn't* work out,
+which turns out to be the part that matters.
+
+No SaaS. No upload. One command, one HTML file, and an exit code for CI.
+
+## The four answers
+
+Every dead-code tool ever written has told you something was unused and been wrong, and
+you stopped trusting it. Seamcheck has a fourth answer:
+
+| | |
+|---|---|
+| `connected` | something reaches this — here's the file and line |
+| `unresolved` | something reaches for this and it isn't there |
+| `unused` | both ends are observable and nothing uses it |
+| **`uncertain`** | **no evidence either way. Not a claim it's dead.** |
+
+That last row is the whole product. A page reached by an `<a href>` looks exactly like a
+dead one if you only parse `fetch()` calls. Seamcheck says so instead of guessing. On a
+700-URL project that's the difference between a report you act on and 668 lies.
+
+It also reports **its own coverage** — how much of each file it actually reasoned about.
+No other tool I've found will tell you where it wasn't looking.
+
+## What it found in the project it was built on
+
+Not hypotheticals. Real bugs, in a real 36,000-symbol codebase, found while writing this:
+
+- Five CSS custom properties in a **loaded** stylesheet that resolve to nothing —
+  `--text-primary`, `--border-color` and friends. Those declarations render nothing today.
+- An endpoint reported missing that turned out to be **`<str:division_id>` matching a
+  deliberate `'all'` sentinel** — so I fixed the matcher instead of "fixing" the code.
+- 65 API routes whose path appears in no source file at all.
+- 46 DOM elements written by more than one module — the reason a display bug survives
+  being "fixed" in one of them.
+
+## Install
+
+```bash
+pip install seamcheck
+```
+
+Then two things in `settings.py`:
+
+```python
+INSTALLED_APPS = [..., "seamcheck"]
+
+SEAMCHECK_CONFIG = {
+    "urlconf_module": "myproject.urls",
+    "templates_root": "myapp/templates",
+    "js_source_root": "myapp/static/js",
+    "css_source_root": "myapp/static/css",
+    "first_party_prefixes": ["myapp", "myproject"],
+}
+```
+
+Every project-specific path lives in that dict. Nothing is hardcoded anywhere in the
+extractors — which is how this was lifted out of the project it grew in without touching
+a line of it.
+
+**You need Node on PATH.** The JS and CSS parsers run on it. You do *not* need npm or
+`node_modules` — acorn and postcss ship inlined in the wheel. If Node is missing,
+Seamcheck says so and gives you the Python half rather than dying.
+
+## Use
+
+```bash
+python manage.py seamcheck                 # scan, summary, write the map
+python manage.py seamcheck --check         # exit 1 on new findings. This is the CI one.
+python manage.py seamcheck --format map    # the UI, one self-contained HTML file
+python manage.py seamcheck --explain <id>  # one symbol, with the code around it
+```
+
+### The UI
+
+One file, no network, opens on a phone. A left rail of views; a canvas that draws
+**every symbol a page touches at once** — 1,366 of them on the biggest page here — with
+the broken ones filled in red so they find you rather than the other way round.
+
+Click any node and it lights the line through it: page → module → `fetch()` → URL →
+view, each hop with the real source, and a button to show the whole enclosing function.
+Or isolate that one chain and drop everything else.
+
+There's a **Files** view too — your actual folder tree, with a bar per file showing how
+many of its declarations Seamcheck reasoned about. Because "no findings" and "never
+looked" are not the same sentence.
+
+```bash
+python manage.py seamcheck --format map --serve            # open it from your phone
+python manage.py seamcheck --format map --serve --tunnel   # ...from anywhere
+```
+
+Nothing is uploaded. `--serve` is a socket on your machine that dies with the command.
+
+### Per-commit
+
+```bash
+python manage.py seamcheck --backfill 20     # scan the last 20 commits
+```
+
+Now the map has a commit picker. Pick one and see what *that commit* changed — added,
+removed, status flipped — including things it deleted, which no longer exist to be drawn
+and get named instead.
+
+### CI
+
+```bash
+python manage.py seamcheck --check --since $BASE_SHA
+```
+
+`1` = new findings. `2` = no baseline, so the gate didn't run. `0` = clean. That
+distinction matters: a gate that never ran is not a gate that passed.
+
+### Agents
+
+`seamcheck_check`, `seamcheck_report`, `seamcheck_explain`, `seamcheck_triage` over MCP,
+and an `AGENTS.md` that tells your agent the one rule that matters: **never delete
+something because it's `uncertain`.**
+
+## What it can't do
+
+Written down because a tool that hides its blind spots is worse than no tool:
+
+- **Django + vanilla JS.** No React, Vue, or TypeScript yet.
+- **Celery, Redis, WebSockets and Stripe aren't traced.** Anything reached only through
+  those is invisible, and the UI says so rather than showing a confident zero.
+- **A URL built at runtime** stays `uncertain`. The prefix is recorded, never a guess.
+- **It has been run against one real project.** Mine. That's one more than most tools at
+  this stage and far fewer than you'd want.
+
+## Contributing
+
+Issues and PRs welcome. One house rule, and it's the reason the tool is worth anything:
+**never make a claim the scan can't evidence.** If you can't prove it, it's `uncertain`,
+and the note says which evidence source was missing.
+
+## License
+
+MIT.

seamcheck-0.1.0/README.md

@@ -0,0 +1,145 @@
+# Seamcheck
+
+**Your AI wrote 400 lines. Which of them are actually wired to anything?**
+
+Seamcheck reads a Django + JavaScript project and tells you what connects to what — which
+`fetch()` lands on which view, which template element the JS is reaching for, which CSS
+rule nothing has referenced since 2023. Then it tells you what it *couldn't* work out,
+which turns out to be the part that matters.
+
+No SaaS. No upload. One command, one HTML file, and an exit code for CI.
+
+## The four answers
+
+Every dead-code tool ever written has told you something was unused and been wrong, and
+you stopped trusting it. Seamcheck has a fourth answer:
+
+| | |
+|---|---|
+| `connected` | something reaches this — here's the file and line |
+| `unresolved` | something reaches for this and it isn't there |
+| `unused` | both ends are observable and nothing uses it |
+| **`uncertain`** | **no evidence either way. Not a claim it's dead.** |
+
+That last row is the whole product. A page reached by an `<a href>` looks exactly like a
+dead one if you only parse `fetch()` calls. Seamcheck says so instead of guessing. On a
+700-URL project that's the difference between a report you act on and 668 lies.
+
+It also reports **its own coverage** — how much of each file it actually reasoned about.
+No other tool I've found will tell you where it wasn't looking.
+
+## What it found in the project it was built on
+
+Not hypotheticals. Real bugs, in a real 36,000-symbol codebase, found while writing this:
+
+- Five CSS custom properties in a **loaded** stylesheet that resolve to nothing —
+  `--text-primary`, `--border-color` and friends. Those declarations render nothing today.
+- An endpoint reported missing that turned out to be **`<str:division_id>` matching a
+  deliberate `'all'` sentinel** — so I fixed the matcher instead of "fixing" the code.
+- 65 API routes whose path appears in no source file at all.
+- 46 DOM elements written by more than one module — the reason a display bug survives
+  being "fixed" in one of them.
+
+## Install
+
+```bash
+pip install seamcheck
+```
+
+Then two things in `settings.py`:
+
+```python
+INSTALLED_APPS = [..., "seamcheck"]
+
+SEAMCHECK_CONFIG = {
+    "urlconf_module": "myproject.urls",
+    "templates_root": "myapp/templates",
+    "js_source_root": "myapp/static/js",
+    "css_source_root": "myapp/static/css",
+    "first_party_prefixes": ["myapp", "myproject"],
+}
+```
+
+Every project-specific path lives in that dict. Nothing is hardcoded anywhere in the
+extractors — which is how this was lifted out of the project it grew in without touching
+a line of it.
+
+**You need Node on PATH.** The JS and CSS parsers run on it. You do *not* need npm or
+`node_modules` — acorn and postcss ship inlined in the wheel. If Node is missing,
+Seamcheck says so and gives you the Python half rather than dying.
+
+## Use
+
+```bash
+python manage.py seamcheck                 # scan, summary, write the map
+python manage.py seamcheck --check         # exit 1 on new findings. This is the CI one.
+python manage.py seamcheck --format map    # the UI, one self-contained HTML file
+python manage.py seamcheck --explain <id>  # one symbol, with the code around it
+```
+
+### The UI
+
+One file, no network, opens on a phone. A left rail of views; a canvas that draws
+**every symbol a page touches at once** — 1,366 of them on the biggest page here — with
+the broken ones filled in red so they find you rather than the other way round.
+
+Click any node and it lights the line through it: page → module → `fetch()` → URL →
+view, each hop with the real source, and a button to show the whole enclosing function.
+Or isolate that one chain and drop everything else.
+
+There's a **Files** view too — your actual folder tree, with a bar per file showing how
+many of its declarations Seamcheck reasoned about. Because "no findings" and "never
+looked" are not the same sentence.
+
+```bash
+python manage.py seamcheck --format map --serve            # open it from your phone
+python manage.py seamcheck --format map --serve --tunnel   # ...from anywhere
+```
+
+Nothing is uploaded. `--serve` is a socket on your machine that dies with the command.
+
+### Per-commit
+
+```bash
+python manage.py seamcheck --backfill 20     # scan the last 20 commits
+```
+
+Now the map has a commit picker. Pick one and see what *that commit* changed — added,
+removed, status flipped — including things it deleted, which no longer exist to be drawn
+and get named instead.
+
+### CI
+
+```bash
+python manage.py seamcheck --check --since $BASE_SHA
+```
+
+`1` = new findings. `2` = no baseline, so the gate didn't run. `0` = clean. That
+distinction matters: a gate that never ran is not a gate that passed.
+
+### Agents
+
+`seamcheck_check`, `seamcheck_report`, `seamcheck_explain`, `seamcheck_triage` over MCP,
+and an `AGENTS.md` that tells your agent the one rule that matters: **never delete
+something because it's `uncertain`.**
+
+## What it can't do
+
+Written down because a tool that hides its blind spots is worse than no tool:
+
+- **Django + vanilla JS.** No React, Vue, or TypeScript yet.
+- **Celery, Redis, WebSockets and Stripe aren't traced.** Anything reached only through
+  those is invisible, and the UI says so rather than showing a confident zero.
+- **A URL built at runtime** stays `uncertain`. The prefix is recorded, never a guess.
+- **It has been run against one real project.** Mine. That's one more than most tools at
+  this stage and far fewer than you'd want.
+
+## Contributing
+
+Issues and PRs welcome. One house rule, and it's the reason the tool is worth anything:
+**never make a claim the scan can't evidence.** If you can't prove it, it's `uncertain`,
+and the note says which evidence source was missing.
+
+## License
+
+MIT.

seamcheck-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+# Paths here are relative to the repo root this file sits at AFTER extraction
+# (see PACKAGING.md). Inside the pointlessbutton repo this file is metadata only:
+# nothing builds it, and the host project's own pyproject.toml is untouched.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seamcheck"
+version = "0.1.0"
+description = "Find the code your project no longer connects to - and the connections it only thinks it has."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "dardameiz" }]
+keywords = ["django", "static-analysis", "dead-code", "connectivity", "mcp"]
+# No "License :: OSI Approved ::" classifier: PEP 639 replaced it with the
+# License-Expression field above, and PyPI rejects a distribution carrying both.
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Django",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = ["django>=5.0"]
+
+[project.optional-dependencies]
+# Model extraction shells out to django-extensions' graph_models --json.
+models = ["django-extensions>=4.0"]
+# Exposes the scan to an agent over MCP.
+mcp = ["mcp>=1.0"]
+# Bundles a Node runtime so `pip install` alone is enough on a machine without one
+# (the pyright precedent). The npm parsers still have to be present - see README.
+node = ["nodejs-wheel-binaries>=20"]
+
+[project.urls]
+Source = "https://github.com/dardameiz/seamcheck"
+Issues = "https://github.com/dardameiz/seamcheck/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["seamcheck"]
+# The parser bundles are the wheel's whole reason for working: a pip install has no
+# node_modules to resolve acorn or postcss against, so they ship inlined.
+artifacts = ["seamcheck/js_tools/*.bundle.mjs", "seamcheck/css_tools/*.bundle.mjs"]
+# Fixtures, tests and the host project's own triage file are not part of what an
+# installing user needs; they stay in the sdist for contributors.
+exclude = ["seamcheck/tests", "seamcheck/triage.json"]
+
+[tool.hatch.build.targets.sdist]
+include = ["seamcheck", "README.md", "LICENSE"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120  # matches the host project this is developed inside
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4"]
+
+
+[tool.pytest.ini_options]
+# Django's own runner needs a project; pytest plus conftest.py does not, which is what
+# lets someone clone this repo and run the suite without one.
+testpaths = ["seamcheck/tests"]

seamcheck-0.1.0/seamcheck/AGENTS.md

@@ -0,0 +1,96 @@
+# Seamcheck — instructions for an AI agent
+
+Seamcheck is a static-analysis tool that maps what a Django + JavaScript project connects
+to what: which URLs exist, which views they route to, which `fetch()` calls resolve to
+them, which DOM elements the JavaScript writes, and which CSS rules and design tokens
+anything still references.
+
+You are likely reading this because someone wants you to use it before committing, or to
+act on something it reported. Read the four statuses first — the whole tool turns on them.
+
+## The four statuses, and the one that matters most
+
+| Status | Means | What you should do |
+|---|---|---|
+| `connected` | Something reaches it, and the evidence is attached | Nothing |
+| `unused` | **Both** sides of the contract are observable and nothing uses it | Safe to investigate for removal |
+| `unresolved` | Something reaches for it and it does not exist | Usually a real bug — fix it |
+| `uncertain` | The scan found **no evidence either way** | **Do not act on it** |
+
+**`uncertain` is not a soft `unused`.** It means the scan cannot see the evidence that
+would settle the question — a page URL reached by `<a href>`, a class applied by code the
+extractor does not read. Deleting something because it is `uncertain` is the single most
+damaging thing you can do with this tool's output. If a human asks you to "clean up
+everything Seamcheck found", ask them whether they mean the `unused` and `unresolved`
+findings, and say plainly that `uncertain` is not a finding.
+
+Every symbol carries the file, the line, and the snippet that produced it. **Quote that
+evidence when you report a finding.** A claim without its snippet is not actionable.
+
+## Commands
+
+```bash
+python manage.py seamcheck                       # scan + human summary
+python manage.py seamcheck --check               # exit 1 on blocking findings
+python manage.py seamcheck --check --format markdown   # digest AND exit code
+python manage.py seamcheck --format markdown     # digest for a chat or PR
+python manage.py seamcheck --format map          # the UI: the map plus the
+                                                             # review sections, one file
+python manage.py seamcheck --format map --since REF    # what changed
+python manage.py seamcheck --format map --serve          # open it from a phone on this wifi
+python manage.py seamcheck --format map --serve --tunnel  # ... or off it
+python manage.py seamcheck --backfill 20   # scan the last 20 commits, so the
+                                                       # map's commit picker has history
+python manage.py seamcheck --backfill 20 --backfill-ref development
+python manage.py seamcheck --format json         # the whole graph
+python manage.py seamcheck --explain <symbol-id> # one symbol's evidence
+python manage.py seamcheck --triage <symbol-id> --status approved --reason "..."
+```
+
+A full scan takes roughly 15 seconds. `--check` is the CI gate: it exits 1 only on
+`unresolved`/`unused` findings that are untriaged or explicitly confirmed, and never on
+`uncertain`.
+
+## Over MCP
+
+If the MCP server is attached, prefer these over shelling out:
+
+- `seamcheck_check(repo_root)` — `{passed, new_unresolved, new_unused, triage_invalidated, counts}`
+- `seamcheck_report(fmt, repo_root)` — the rendered digest (`terminal`, `markdown`, `html`)
+- `seamcheck_explain(symbol_id, repo_root)` — one symbol's evidence as markdown
+- `seamcheck_triage(symbol_id, status, repo_root, reason)` — record a disposition
+
+## The workflow you are probably being asked to run
+
+1. `--check` before the commit. If it exits 0, say so in one line and stop.
+2. If it exits 1, `--explain` each reported id and decide, per finding:
+   - **a real defect** → fix it, quoting the evidence in your explanation
+   - **correct detection, deliberate code** → `--triage <id> --status approved --reason "..."`
+   - **the tool is wrong** → say so and why; that is a bug report worth making
+3. A `triage invalidated` line means a human dispositioned that finding earlier and the
+   underlying evidence has since changed. **Re-read the code before re-approving it.**
+
+## Known gaps — do not over-trust these
+
+The tool is honest about what it cannot see, and so should you be:
+
+- **CSS selectors reported `uncertain`** are not dead code. Class-applying JavaScript is
+  read (`className`, `classList`, `setAttribute`, markup strings), but coverage is not
+  proven complete.
+- **Response fields** are matched one view against a whole consuming module, so a field can
+  be proven read but never proven unread.
+- **WebSocket payloads, Celery tasks, Redis keys and Stripe hooks are not traced at all.**
+  Anything reached only through those is invisible to the scan.
+- **A commit that changed no connection reports nothing.** The graph holds URLs, views,
+  calls, selectors and tokens - not values. A commit that adds an entry to a constant
+  correctly shows no change; that is not the picker failing.
+- **Selectors and fetch targets built at runtime** are `uncertain` by design, never guessed.
+
+## Rules for you specifically
+
+- Never delete code because a symbol is `uncertain`.
+- Never report a finding without its `file:line` and snippet.
+- Never claim the scan is clean because a command exited 0 — check that it actually ran and
+  what it counted.
+- If you are asked to fix a multi-writer element, the fix is to pick one canonical owner and
+  route the others through it, not to patch the writer you happened to find first.