documate 0.2.0__tar.gz

documate-0.2.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git grep *)"
+    ]
+  }
+}

documate-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+# Run the suite on every push/PR, and dogfood documate on its own docs — if our own
+# docs can go stale unnoticed, we have no business shipping a docs engine.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # the drift gate needs history to diff against the base
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: install
+        run: pip install -e .
+      - name: unit tests
+        run: python -m unittest discover -s tests -v
+      - name: dogfood — the gate on our own docs
+        run: documate --check --base "${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || 'HEAD' }}"

documate-0.2.0/.github/workflows/pages.yml

@@ -0,0 +1,40 @@
+name: docs-site
+
+# Publish the `documate --html` site to GitHub Pages. Works for private repos too.
+# Enable once, then trigger from the Actions tab (or add a `push:` trigger below):
+#   repo Settings -> Pages -> Source: "GitHub Actions".
+on:
+  workflow_dispatch:
+  # push:            # uncomment to auto-publish on every push to main
+  #   branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hotspots/evidence read git history
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .
+      - run: documate --html .
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deploy
+        uses: actions/deploy-pages@v4

documate-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+.documate/
+site/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+node_modules/
+*.tsbuildinfo
+.claude/worktrees/
+tmp/
+.coverage
+coverage/
+.pytest_cache/
+CLAUDE.md

documate-0.2.0/.pre-commit-hooks.yaml

@@ -0,0 +1,11 @@
+# Lets other repos consume documate via the `pre-commit` framework:
+#   - repo: https://github.com/<you>/documate
+#     rev: v0.2.0
+#     hooks: [{ id: documate }]
+- id: documate
+  name: documate (self-healing docs + gate)
+  description: Regenerate the generated docs tier and gate it — fails if pages changed (re-commit with fresh docs), an anchor is dead, or an authored doc lies about changed code.
+  entry: documate
+  language: python
+  pass_filenames: false
+  always_run: true

documate-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to documate
+
+Small tool, simple rules. The whole point is binding docs to code so they can't quietly
+rot, so the bar is: don't let documate's own docs rot, and don't break the gate.
+
+## Setup
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e .                 # stdlib tool + the vendored tree-sitter engine
+make test                        # or: python -m unittest discover -s tests -v
+```
+
+`tree-sitter-language-pack` is pinned `<1` on purpose — 1.x reshuffled the grammar API and
+breaks the vendored parser. Don't bump it past that.
+
+## The tool is one command
+
+- `documate` — index the repo, (re)write `docs/`, then gate the result.
+- `documate --check` — the gate alone, writes nothing (CI and the pre-commit hook).
+
+Everything else is a flag; `documate --help` is the whole surface on one screen.
+
+## Layout
+
+```
+src/documate/            the tool — repo-agnostic logic, stdlib-only
+src/documate/_engine/    the tree-sitter → sqlite indexer (MIT; see _engine/ORIGIN.md)
+src/documate/graphdb.py  the ONLY module that touches the engine / sqlite schema
+tests/test_documate.py   one file, stdlib unittest, throwaway git fixtures
+```
+
+The engine is first-party code (it began as a copy of code-review-graph — provenance and
+license in `_engine/ORIGIN.md`). Adapt to it through `graphdb.py`; never edit `_engine/*`
+to make documate work — put that logic behind the adapter instead.
+
+## Rules
+
+- **Anchor what you hand-write.** New authored prose about a symbol (under `docs/guides/`)
+  gets a `<!-- documents: sym:NAME -->` anchor, or the drift gate can't protect it.
+  `documate --check` prints a `sig:` fingerprint you can add to pin the anchor exactly.
+- **Never hand-edit generated pages.** `docs/README.md`, `docs/ARCHITECTURE.md`, and
+  `docs/architecture/*` are generated (each opens with a stamp line). Fix the source — a
+  docstring, or an anchor — then regenerate with `documate`.
+- **Run the gate before you commit.** `documate --check`, or install the hook:
+  `git config core.hooksPath hooks` (or use `.pre-commit-hooks.yaml`). The pre-commit
+  hook is self-healing — it regenerates the generated pages and stages them, then gates.
+  Skip it with `--no-verify`; override the base ref with `DOCUMATE_BASE=<ref>`.
+- **Stdlib for the tool.** documate's own modules import only the stdlib (plus rich for
+  output, and the `_engine` adapter). Heavy deps (tree-sitter, networkx) live behind
+  `_engine`.
+
+## Tests
+
+TDD-ish: a failing test first when you can. Cover the degraded-graph path — a missing or
+locked `graph.db` must soft-pass, never raise; that's the contract the whole design leans
+on. The engine ships no tests of its own, so cover engine changes with a `RealGraph`-style
+fixture here. `make`-free: just `python -m unittest discover -s tests`.

documate-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Aseem Chopra
+
+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.
+
+---
+
+This project vendors a code-indexing engine under src/documate/_engine/, which
+is a separate work licensed MIT, Copyright (c) 2026 Tirth Kanani (the
+code-review-graph project). Its license is retained at
+src/documate/_engine/LICENSE and provenance noted in
+src/documate/_engine/ORIGIN.md.

documate-0.2.0/Makefile

@@ -0,0 +1,27 @@
+PY := .venv/bin/python
+
+.PHONY: test coverage docs check
+
+test: ## Run the full test suite in parallel (same tests CI runs serially)
+	@$(PY) -c "import pytest, xdist" 2>/dev/null \
+		|| uv pip install -q --python $(PY) pytest pytest-xdist 2>/dev/null \
+		|| $(PY) -m pip install -q pytest pytest-xdist
+	@$(PY) -m pytest -n auto -q tests/test_documate.py
+
+coverage: ## Line coverage of documate's source → terminal table + coverage/html/index.html
+	@$(PY) -m coverage --version >/dev/null 2>&1 \
+		|| uv pip install -q --python $(PY) coverage 2>/dev/null \
+		|| $(PY) -m pip install -q coverage
+	@mkdir -p coverage
+	@$(PY) -m coverage run --source=src/documate -m unittest tests.test_documate \
+		>coverage/test.log 2>&1 || { cat coverage/test.log; exit 1; }
+	@$(PY) -m coverage html -q -d coverage/html
+	@$(PY) -m coverage json -q -o coverage/coverage.json
+	@$(PY) scripts/coverage_report.py coverage/coverage.json
+	@echo "   html: coverage/html/index.html"
+
+docs: ## The whole job: regenerate docs/ and gate them (+ static site: make docs HTML=1)
+	@.venv/bin/documate . $(if $(HTML),--html)
+
+check: ## The gate alone: docs fresh, anchors real, no drift vs origin/main
+	@.venv/bin/documate --check .

documate-0.2.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: documate
+Version: 0.2.0
+Summary: Tie docs to the code they describe, and yell when one moves without the other. Plugs into any repo.
+Author: Aseem Chopra
+License: MIT License
+        
+        Copyright (c) 2026 Aseem Chopra
+        
+        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.
+        
+        ---
+        
+        This project vendors a code-indexing engine under src/documate/_engine/, which
+        is a separate work licensed MIT, Copyright (c) 2026 Tirth Kanani (the
+        code-review-graph project). Its license is retained at
+        src/documate/_engine/LICENSE and provenance noted in
+        src/documate/_engine/ORIGIN.md.
+License-File: LICENSE
+Keywords: docs-as-code,documentation,drift,knowledge-graph,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: networkx<4,>=3.2
+Requires-Dist: rich-argparse<2,>=1.5
+Requires-Dist: rich<15,>=13
+Requires-Dist: tomli; python_version < '3.11'
+Requires-Dist: tree-sitter-language-pack<1,>=0.3.0
+Requires-Dist: tree-sitter<1,>=0.23.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src=".github/documate-intro.webp" alt="documate generating a repository's docs and gating them from the terminal" width="640">
+</p>
+
+# documate
+
+documate generates documentation from your code (an overview, one page per module, and an API
+reference from your docstrings) and fails CI when those docs stop matching the code.
+
+[![python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-self--generated_·_100%25_documented-8A2BE2)](docs/README.md)
+
+## Install
+
+```bash
+uv tool install documate     # or: pipx install documate  /  pip install documate
+```
+
+`--ai` additionally needs the `claude` CLI on your PATH. Everything else is stdlib.
+
+## Use
+
+```bash
+cd your-repo
+documate --init    # first run: create a config, then generate the docs
+documate           # generate or refresh docs/, then gate them
+```
+
+| Command | What it does |
+| --- | --- |
+| `documate` | index, write or refresh `docs/`, then gate it |
+| `documate --check` | gate only, writes nothing (for CI and pre-commit) |
+| `documate --watch` | regenerate on every save |
+| `documate --html` | also render a static site into `site/` |
+| `documate --ai [MODEL]` | draft missing docstrings with a model, then re-verify |
+| `documate --stats` | show coverage, documentation lines, and model spend |
+
+Run `documate path/to/repo` to document any repo. Run `documate --help` for the full list.
+
+## What it writes
+
+- `docs/README.md`: an overview with a dependency map, coverage, entry points, and hotspots.
+- `docs/ARCHITECTURE.md`: the whole system on one page.
+- `docs/architecture/<module>.md`: one page per module (docstring, dependencies, call-flow, symbols).
+
+## The gate
+
+`documate --check` exits non-zero when:
+
+1. Generated pages are out of date. Run `documate` to refresh them.
+2. A hand-written page points at code that no longer exists.
+3. A hand-written page describes code that changed since `--base` but was not updated.
+
+Install the pre-commit hook once:
+
+```bash
+git config core.hooksPath hooks
+```
+
+It regenerates and stages the generated pages on every commit. In CI, run `documate --check`
+with `fetch-depth: 0` on `actions/checkout`.
+
+## Authored pages
+
+Write Markdown under `docs/` and anchor it to the code it documents:
+
+```markdown
+<!-- documents: sym:build_model -->
+```
+
+`documate --check` then fails if that code changes and the page does not. Add a `sig:`
+fingerprint after the symbol to pin the page to the exact source.
+
+## Configuration
+
+`documate --init` writes `documate.config.json`. Override only what you need:
+
+```json
+{
+  "docs_dir": "docs",
+  "site_dir": "site",
+  "skip_dirs": ["/generated/"],
+  "default_base": "main"
+}
+```
+
+## License
+
+[MIT](LICENSE). The engine in `src/documate/_engine/` is vendored from code-review-graph (MIT).

documate-0.2.0/README.md

@@ -0,0 +1,90 @@
+<p align="center">
+  <img src=".github/documate-intro.webp" alt="documate generating a repository's docs and gating them from the terminal" width="640">
+</p>
+
+# documate
+
+documate generates documentation from your code (an overview, one page per module, and an API
+reference from your docstrings) and fails CI when those docs stop matching the code.
+
+[![python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-self--generated_·_100%25_documented-8A2BE2)](docs/README.md)
+
+## Install
+
+```bash
+uv tool install documate     # or: pipx install documate  /  pip install documate
+```
+
+`--ai` additionally needs the `claude` CLI on your PATH. Everything else is stdlib.
+
+## Use
+
+```bash
+cd your-repo
+documate --init    # first run: create a config, then generate the docs
+documate           # generate or refresh docs/, then gate them
+```
+
+| Command | What it does |
+| --- | --- |
+| `documate` | index, write or refresh `docs/`, then gate it |
+| `documate --check` | gate only, writes nothing (for CI and pre-commit) |
+| `documate --watch` | regenerate on every save |
+| `documate --html` | also render a static site into `site/` |
+| `documate --ai [MODEL]` | draft missing docstrings with a model, then re-verify |
+| `documate --stats` | show coverage, documentation lines, and model spend |
+
+Run `documate path/to/repo` to document any repo. Run `documate --help` for the full list.
+
+## What it writes
+
+- `docs/README.md`: an overview with a dependency map, coverage, entry points, and hotspots.
+- `docs/ARCHITECTURE.md`: the whole system on one page.
+- `docs/architecture/<module>.md`: one page per module (docstring, dependencies, call-flow, symbols).
+
+## The gate
+
+`documate --check` exits non-zero when:
+
+1. Generated pages are out of date. Run `documate` to refresh them.
+2. A hand-written page points at code that no longer exists.
+3. A hand-written page describes code that changed since `--base` but was not updated.
+
+Install the pre-commit hook once:
+
+```bash
+git config core.hooksPath hooks
+```
+
+It regenerates and stages the generated pages on every commit. In CI, run `documate --check`
+with `fetch-depth: 0` on `actions/checkout`.
+
+## Authored pages
+
+Write Markdown under `docs/` and anchor it to the code it documents:
+
+```markdown
+<!-- documents: sym:build_model -->
+```
+
+`documate --check` then fails if that code changes and the page does not. Add a `sig:`
+fingerprint after the symbol to pin the page to the exact source.
+
+## Configuration
+
+`documate --init` writes `documate.config.json`. Override only what you need:
+
+```json
+{
+  "docs_dir": "docs",
+  "site_dir": "site",
+  "skip_dirs": ["/generated/"],
+  "default_base": "main"
+}
+```
+
+## License
+
+[MIT](LICENSE). The engine in `src/documate/_engine/` is vendored from code-review-graph (MIT).