docsync 0.1.0__tar.gz

docsync-0.1.0/.bumpversion.cfg

@@ -0,0 +1,8 @@
+[bumpversion]
+current_version = 0.1.0
+commit = False
+tag = False
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"

docsync-0.1.0/.changelog/.gitkeep

@@ -0,0 +1,3 @@
+# Add changelog fragments here
+# Format: <issue_number>.<type>.md (e.g., 42.feature.md)
+# Types: feature, bugfix, misc

docsync-0.1.0/.github/workflows/callable-ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  workflow_call:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+
+  practical-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: docsync check docs/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -v

docsync-0.1.0/.github/workflows/prs.yml

@@ -0,0 +1,8 @@
+name: PRs
+
+on:
+  pull_request:
+
+jobs:
+  ci:
+    uses: ./.github/workflows/callable-ci.yml

docsync-0.1.0/.github/workflows/push-to-main.yml

@@ -0,0 +1,9 @@
+name: Push to main
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: ./.github/workflows/callable-ci.yml

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

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+          - initial
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install bump2version towncrier hatch
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        if: inputs.bump != 'initial'
+        run: bump2version ${{ inputs.bump }}
+
+      - name: Read new version
+        id: version
+        run: echo "version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")" >> "$GITHUB_OUTPUT"
+
+      - name: Build changelog
+        run: towncrier build --yes --version ${{ steps.version.outputs.version }}
+
+      - name: Commit and tag
+        run: |
+          git add -A
+          git commit -m "chore: release v${{ steps.version.outputs.version }}"
+          git tag "v${{ steps.version.outputs.version }}"
+          git push origin main --tags
+
+      - name: Build
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docsync-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.ignore/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/

docsync-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+## 0.1.0 (2026-02-17)
+
+No significant changes.
+
+
+# Changelog

docsync-0.1.0/LICENSE

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

docsync-0.1.0/Makefile

@@ -0,0 +1,19 @@
+install:
+	python3 -m venv .venv
+	.venv/bin/pip install -e ".[dev]"
+
+check:
+	.venv/bin/ruff check .
+	.venv/bin/ruff format --check .
+
+test:
+	.venv/bin/pytest -v
+
+practical-test:
+	.venv/bin/docsync check docs/
+
+changelog:
+	.venv/bin/towncrier build --yes --version $(shell python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+
+changelog-draft:
+	.venv/bin/towncrier build --draft --version $(shell python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")

docsync-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: docsync
+Version: 0.1.0
+Summary: Auto-validate and update docs in large codebases
+License-File: LICENSE
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: bump2version>=1; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: towncrier>=23; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Overview
+
+CLI tool that keeps documentation in sync with code in large codebases. Detects which docs are affected by code changes and generates reports for AI validation.
+
+```
+  src/booking/handler.ts changed
+            │
+            v
+  ┌─────────────────────────┐
+  │ docsync cascade HEAD~1  │
+  └───────────┬─────────────┘
+              │
+              v
+  ┌─────────────────────────┐      ┌─────────────────────────┐
+  │ Direct hits:            │      │ docs/bookings.md        │
+  │  - docs/bookings.md     │ ──>  │                         │
+  └─────────────────────────┘      │ related sources:        │
+              │                    │  - src/booking/  <───── │ ← matched!
+              v                    └─────────────────────────┘
+  ┌─────────────────────────┐
+  │ Cascade hits:           │      docs/bookings.md references
+  │  - docs/payments.md     │ ──>  docs/payments.md, so it
+  └─────────────────────────┘      might need review too
+```
+
+<details>
+<summary>How it works</summary>
+
+Each doc ends with metadata sections:
+
+```markdown
+# Booking System
+
+How bookings work...
+
+---
+
+related docs:
+- docs/payments.md - payment integration
+
+related sources:
+- src/booking/           - booking module
+- src/booking/commands/  - command handlers
+```
+
+When `src/booking/handler.ts` changes:
+
+```
+docsync cascade HEAD~1
+
+Direct hits (1):
+  docs/bookings.md       <- references src/booking/
+
+Cascade hits (1):
+  docs/payments.md       <- referenced BY docs/bookings.md
+```
+
+The cascade propagates: if `bookings.md` might be outdated, then `payments.md` (which references it) might also need review.
+
+</details>
+
+## Motivation
+
+In large codebases, docs get outdated because:
+1. No one remembers which docs need updating when a file changes
+2. AI agents don't know which files to read to validate each doc
+
+docsync solves this by adding "hints" to each doc - `related sources:` tells any AI exactly what to read.
+
+## Features
+
+- check   - validates all referenced paths exist
+- cascade - finds docs affected by code changes (with directory matching)
+- sync    - generates prompt for AI to fix docs (ordered by deps)
+- tree    - shows doc dependency tree
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pipx install docsync
+```
+
+### 2. Add metadata to your docs
+
+Each doc needs two sections at the end (after a `---` separator):
+
+```markdown
+# My Feature
+
+Documentation content here...
+
+---
+
+related docs:
+- docs/other-feature.md - brief description
+
+related sources:
+- src/feature/           - main module
+- src/feature/utils.ts   - helper functions
+```
+
+### 3. Initialize config (optional)
+
+```bash
+docsync init    # creates .docsync/ folder
+```
+
+<details>
+<summary>Config options</summary>
+
+```
+.docsync/
+├── config.json   # required
+├── sync.md       # optional - custom prompt template
+├── lock.json     # optional - tracks last synced commit
+└── syncs/        # ignored - AI writes sync reports here
+```
+
+config.json:
+```json
+{
+  "ignored_paths": ["**/migrations/**", "**/*.test.ts"],
+  "cascade_depth_limit": null
+}
+```
+
+sync.md (custom template):
+```markdown
+Sync {count} docs. Write reports to {syncs_dir}/
+
+{phases}
+```
+
+Placeholders: `{count}`, `{phases}`, `{docs_list}`, `{syncs_dir}`
+
+</details>
+
+### 4. Validate your setup
+
+```bash
+docsync check docs/    # ensures all paths exist
+```
+
+### 5. Use it
+
+```bash
+docsync cascade HEAD~5 --docs docs/    # docs affected by last 5 commits
+docsync sync docs/ | pbcopy            # generate AI prompt
+claude "$(docsync sync docs/)"         # or pipe directly to AI
+```
+
+## Commands
+
+```bash
+docsync check <path>                   # validate refs exist
+docsync cascade <commit> --docs <dir>  # list affected docs
+docsync sync <path>                    # generate prompt (ordered by deps)
+docsync sync <path> --parallel         # ignore deps, all at once
+docsync sync <path> --incremental      # only include changed docs
+docsync sync <path> --update-lock      # update lock.json after sync
+docsync sync <path> --json             # output as JSON for scripts
+docsync tree <path>                    # show doc dependency tree
+docsync init                           # create .docsync/ folder
+docsync --version                      # show version
+```
+
+### AI Sync
+
+The `sync` command generates a prompt for AI to fix docs in phases (respecting dependencies):
+
+```
+Sync 5 docs by launching agents in phases (respecting dependencies).
+
+Each agent will:
+1. Read the doc + all related sources
+2. Fix any outdated/incorrect content directly in the doc
+3. Write a report to .docsync/syncs/2024-01-15T10-30-00/
+
+Phase 1 - Independent (launch parallel):
+  docs/utils.md
+  docs/config.md
+
+Phase 2 - Level 1 (after phase 1 completes):
+  docs/auth.md
+    sources: src/auth/
+
+Phase 3 - Level 2 (after phase 2 completes):
+  docs/login.md
+    sources: src/login/
+```
+
+Use `--parallel` to ignore dependencies and sync all at once.
+
+## Development
+
+```bash
+make install        # create venv + install
+make check          # lint
+make test           # run tests
+docsync check docs/ # practical test
+```

docsync-0.1.0/README.md

@@ -0,0 +1,203 @@
+# Overview
+
+CLI tool that keeps documentation in sync with code in large codebases. Detects which docs are affected by code changes and generates reports for AI validation.
+
+```
+  src/booking/handler.ts changed
+            │
+            v
+  ┌─────────────────────────┐
+  │ docsync cascade HEAD~1  │
+  └───────────┬─────────────┘
+              │
+              v
+  ┌─────────────────────────┐      ┌─────────────────────────┐
+  │ Direct hits:            │      │ docs/bookings.md        │
+  │  - docs/bookings.md     │ ──>  │                         │
+  └─────────────────────────┘      │ related sources:        │
+              │                    │  - src/booking/  <───── │ ← matched!
+              v                    └─────────────────────────┘
+  ┌─────────────────────────┐
+  │ Cascade hits:           │      docs/bookings.md references
+  │  - docs/payments.md     │ ──>  docs/payments.md, so it
+  └─────────────────────────┘      might need review too
+```
+
+<details>
+<summary>How it works</summary>
+
+Each doc ends with metadata sections:
+
+```markdown
+# Booking System
+
+How bookings work...
+
+---
+
+related docs:
+- docs/payments.md - payment integration
+
+related sources:
+- src/booking/           - booking module
+- src/booking/commands/  - command handlers
+```
+
+When `src/booking/handler.ts` changes:
+
+```
+docsync cascade HEAD~1
+
+Direct hits (1):
+  docs/bookings.md       <- references src/booking/
+
+Cascade hits (1):
+  docs/payments.md       <- referenced BY docs/bookings.md
+```
+
+The cascade propagates: if `bookings.md` might be outdated, then `payments.md` (which references it) might also need review.
+
+</details>
+
+## Motivation
+
+In large codebases, docs get outdated because:
+1. No one remembers which docs need updating when a file changes
+2. AI agents don't know which files to read to validate each doc
+
+docsync solves this by adding "hints" to each doc - `related sources:` tells any AI exactly what to read.
+
+## Features
+
+- check   - validates all referenced paths exist
+- cascade - finds docs affected by code changes (with directory matching)
+- sync    - generates prompt for AI to fix docs (ordered by deps)
+- tree    - shows doc dependency tree
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pipx install docsync
+```
+
+### 2. Add metadata to your docs
+
+Each doc needs two sections at the end (after a `---` separator):
+
+```markdown
+# My Feature
+
+Documentation content here...
+
+---
+
+related docs:
+- docs/other-feature.md - brief description
+
+related sources:
+- src/feature/           - main module
+- src/feature/utils.ts   - helper functions
+```
+
+### 3. Initialize config (optional)
+
+```bash
+docsync init    # creates .docsync/ folder
+```
+
+<details>
+<summary>Config options</summary>
+
+```
+.docsync/
+├── config.json   # required
+├── sync.md       # optional - custom prompt template
+├── lock.json     # optional - tracks last synced commit
+└── syncs/        # ignored - AI writes sync reports here
+```
+
+config.json:
+```json
+{
+  "ignored_paths": ["**/migrations/**", "**/*.test.ts"],
+  "cascade_depth_limit": null
+}
+```
+
+sync.md (custom template):
+```markdown
+Sync {count} docs. Write reports to {syncs_dir}/
+
+{phases}
+```
+
+Placeholders: `{count}`, `{phases}`, `{docs_list}`, `{syncs_dir}`
+
+</details>
+
+### 4. Validate your setup
+
+```bash
+docsync check docs/    # ensures all paths exist
+```
+
+### 5. Use it
+
+```bash
+docsync cascade HEAD~5 --docs docs/    # docs affected by last 5 commits
+docsync sync docs/ | pbcopy            # generate AI prompt
+claude "$(docsync sync docs/)"         # or pipe directly to AI
+```
+
+## Commands
+
+```bash
+docsync check <path>                   # validate refs exist
+docsync cascade <commit> --docs <dir>  # list affected docs
+docsync sync <path>                    # generate prompt (ordered by deps)
+docsync sync <path> --parallel         # ignore deps, all at once
+docsync sync <path> --incremental      # only include changed docs
+docsync sync <path> --update-lock      # update lock.json after sync
+docsync sync <path> --json             # output as JSON for scripts
+docsync tree <path>                    # show doc dependency tree
+docsync init                           # create .docsync/ folder
+docsync --version                      # show version
+```
+
+### AI Sync
+
+The `sync` command generates a prompt for AI to fix docs in phases (respecting dependencies):
+
+```
+Sync 5 docs by launching agents in phases (respecting dependencies).
+
+Each agent will:
+1. Read the doc + all related sources
+2. Fix any outdated/incorrect content directly in the doc
+3. Write a report to .docsync/syncs/2024-01-15T10-30-00/
+
+Phase 1 - Independent (launch parallel):
+  docs/utils.md
+  docs/config.md
+
+Phase 2 - Level 1 (after phase 1 completes):
+  docs/auth.md
+    sources: src/auth/
+
+Phase 3 - Level 2 (after phase 2 completes):
+  docs/login.md
+    sources: src/login/
+```
+
+Use `--parallel` to ignore dependencies and sync all at once.
+
+## Development
+
+```bash
+make install        # create venv + install
+make check          # lint
+make test           # run tests
+docsync check docs/ # practical test
+```

docsync-0.1.0/docs/test.md

@@ -0,0 +1,12 @@
+# Test Doc
+
+This is a test documentation file.
+
+---
+
+related docs:
+- README.md - project readme
+
+related sources:
+- src/docsync/cli.py    - CLI implementation
+- src/docsync/core/parser.py - parser implementation

docsync-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "docsync"
+version = "0.1.0"
+description = "Auto-validate and update docs in large codebases"
+readme = "README.md"
+requires-python = ">=3.9"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.9", "towncrier>=23", "bump2version>=1"]
+
+[project.scripts]
+docsync = "docsync.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docsync"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.towncrier]
+directory = ".changelog"
+filename = "CHANGELOG.md"
+title_format = "## {version} ({project_date})"
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "Features"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Bug Fixes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "misc"
+name = "Misc"
+showcontent = true

docsync-0.1.0/src/docsync/__init__.py

@@ -0,0 +1,5 @@
+from docsync.commands.cascade import find_affected_docs
+from docsync.commands.check import check_refs
+from docsync.core.parser import parse_doc
+
+__all__ = ["parse_doc", "check_refs", "find_affected_docs"]