docalign 0.1.0__tar.gz

docalign-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}"

docalign-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: docalign --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

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

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

docalign-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

docalign-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

docalign-0.1.0/.gitignore

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

docalign-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+## 0.1.0 (2026-02-18)
+
+No significant changes.
+
+
+## 0.3.3 (2026-02-17)
+
+No significant changes.
+
+
+## 0.3.2 (2026-02-16)
+
+No significant changes.
+
+
+## 0.3.1 (2026-02-16)
+
+No significant changes.
+
+
+## 0.3.0 (2026-02-16)
+
+No significant changes.
+
+
+## 0.2.4 (2026-02-15)
+
+No significant changes.
+
+
+## 0.2.3 (2026-02-15)
+
+No significant changes.
+
+
+## 0.2.2 (2026-02-15)
+
+No significant changes.
+
+
+## 0.2.1 (2026-02-15)
+
+No significant changes.
+
+
+## 0.2.0 (2026-02-15)
+
+No significant changes.
+
+
+## 0.1.1 (2026-02-12)
+
+### Misc
+
+- Add README as PyPI project description (add-readme-to-pypi)
+
+
+## 0.1.0 (2026-02-12)
+
+### Features
+
+- Initial release with CLI support for auto-fixing markdown table alignment (initial-release)

docalign-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.

docalign-0.1.0/Makefile

@@ -0,0 +1,22 @@
+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
+
+test-all-checks:
+	.venv/bin/pytest -v -k "all-checks"
+
+practical-test:
+	.venv/bin/docalign docs/ --fix
+
+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'])")

docalign-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: docalign
+Version: 0.1.0
+Summary: Auto-fix alignment in markdown docs
+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 utility that auto-fixes alignment issues in markdown documentation files - tables, box-drawing diagrams, list descriptions, and more.
+
+```
+┌────────────────────────┐       ┌────────────────────────┐
+│  ┌────┐   ┌────┐      │        │  ┌────┐   ┌────┐       │
+│  │ A  │   │ B  │      │        │  │ A  │   │ B  │       │
+│  └──┬─┘   └──┬─┘      │        │  └──┬─┘   └──┬─┘       │
+│     │         │        │       │     │        │         │
+│     └────┬───┘         │  -->  │     └────┬───┘         │
+│           v            │       │          v             │
+│     ┌──────┐           │       │     ┌──────┐           │
+ │     │  C   │           │      │     │  C   │           │
+│     └──────┘           │       │     └──────┘           │
+└────────────────────────┘       └────────────────────────┘
+```
+
+<details>
+<summary>More examples</summary>
+
+### [Tables](tests/fixtures/checks/tables)
+
+```
+| Service        | Usage                         |             | Service        | Usage                         |
+|----------------|-------------------------------|             |----------------|-------------------------------|
+| Linear API     | Status transitions, comments|        -->    | Linear API     | Status transitions, comments  |
+| GitHub API| Repo clone, PR creation       |                  | GitHub API     | Repo clone, PR creation       |
+```
+
+### [List descriptions](tests/fixtures/checks/list-descs)
+
+```
+- docs/repo.md - mirrors CI steps                       - docs/repo.md                    - mirrors CI steps
+- docs/guides/testing-strategy.md - test suite  -->     - docs/guides/testing-strategy.md - test suite
+```
+
+### [Box widths](tests/fixtures/checks/box-widths)
+
+```
+┌──────────────┐       ┌──────────────┐
+│  Linear UI  │   -->  │  Linear UI   │
+│  (userscript)│       │  (userscript)│
+└──────────────┘       └──────────────┘
+```
+
+### [Rail alignment](tests/fixtures/checks/rails)
+
+```
+┌──────┬──────┐       ┌──────┬──────┐
+│      │      │       │      │      │
+│       │     │  -->  │      │      │
+│      │      │       │      │      │
+└──────┴──────┘       └──────┴──────┘
+```
+
+### [Arrow alignment](tests/fixtures/checks/arrows)
+
+```
+┌──────┐                     ┌──────┐
+│ step │                     │ step │
+└──┬───┘                     └──┬───┘
+   │           -->              │
+     v                          v
+┌──────┐                     ┌──────┐
+│ next │                     │ next │
+└──────┘                     └──────┘
+```
+
+### [Pipe continuity](tests/fixtures/checks/pipes)
+
+```
+┌──────┬──────┐              ┌──────┬──────┐
+│ src  │ dest │              │ src  │ dest │
+└──────┴──┬───┘              └──────┴──┬───┘
+          │        -->                 │
+            │                          │
+          │                            │
+┌─────────┴───┐              ┌─────────┴───┐
+│   output    │              │   output    │
+└─────────────┘              └─────────────┘
+```
+
+### [Box spacing](tests/fixtures/checks/box-spacing)
+
+```
+┌───────────┐       ┌────────────┐
+│  errors[] │       │  errors[]  │
+│  (strings)│  -->  │  (strings) │
+└───────────┘       └────────────┘
+```
+
+### [Box walls](tests/fixtures/checks/box-walls)
+
+```
+┌──────────────────┐       ┌──────────────────┐
+│  content here    │       │  content here    │
+│  more text       │  -->  │  more text       │
+└────────────────┘         └──────────────────┘
+```
+
+</details>
+
+## Motivation
+
+In the era of agentic engineering, documentation is the most critical artifact in any codebase. It guides both humans and AI agents.
+When docs are visually harmonious - with aligned columns, consistent box widths, and straight connector lines - they become easier to read, parse, and maintain by everyone.
+
+## Features
+
+- 3 modes        - check (default), auto-fix in place, or unified diff
+- flexible paths - files, directories, or glob patterns (e.g. `"docs/**/*.md"`)
+- CI-friendly    - exit code 0 when aligned, 1 when issues found
+- 12 alignment checks:
+  - [Table columns](tests/fixtures/checks/tables)           - pads cells so every column matches the separator row width
+  - [Box widths](tests/fixtures/checks/box-widths)          - ensures all lines in a box group have the same total length
+  - [Box padding](tests/fixtures/checks/box-padding)        - normalizes left-padding of content lines inside boxes
+  - [Horizontal arrows](tests/fixtures/checks/horiz-arrows) - closes gaps between `─>` / `<─` arrow tips and box walls
+  - [Rail alignment](tests/fixtures/checks/rails)           - aligns vertically adjacent box chars to the same column
+  - [Arrow alignment](tests/fixtures/checks/arrows)         - aligns standalone `v`/`^` arrows; detects `v`/`^` embedded in borders
+  - [Pipe continuity](tests/fixtures/checks/pipes)          - traces from T-junctions to detect drifted connector pipes
+  - [Box spacing](tests/fixtures/checks/box-spacing)        - ensures minimum right-side spacing between content and box wall
+  - [Box walls](tests/fixtures/checks/box-walls)            - verifies nested box right walls match their opening/closing borders
+  - [List descriptions](tests/fixtures/checks/list-descs)   - aligns the separator dash in list item descriptions
+  - [Definition lists](tests/fixtures/checks/def-lists)     - aligns the `:` separator in `key: value` list items
+  - [Wide chars](tests/fixtures/checks/wide-chars)          - detects ambiguous/double-width Unicode chars in code blocks
+
+## Commands
+
+```bash
+docalign <path>                        # check-only (default) - detect issues, no writes
+docalign --check <path>                # explicit check-only (same as default)
+docalign --fix <path>                  # auto-fix files in place
+docalign --diff <path>                 # show unified diff of what would change
+docalign --verbose <path>              # show actionable hints with each error
+docalign --ignore tables,pipes <path>  # skip specific checks
+docalign --help                        # show help
+docalign --version                     # show version
+```
+
+Paths can be files, directories, or glob patterns (e.g. `"docs/**/*.md"`).
+
+Check names for `--ignore`: tables, box-widths, box-padding, box-spacing, horiz-arrows, box-walls, rails, arrows, pipes, list-descs, def-lists, wide-chars.
+
+Exit codes: 0 = all aligned, 1 = issues found.
+
+### Install
+
+```bash
+pipx install docalign
+# pip install docalign
+```
+
+### Update
+
+```bash
+pipx upgrade docalign
+# pip install --upgrade docalign
+```
+
+### Uninstall
+
+```bash
+pipx uninstall docalign
+# pip uninstall docalign
+```
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -v
+```

docalign-0.1.0/README.md

@@ -0,0 +1,175 @@
+# Overview
+
+CLI utility that auto-fixes alignment issues in markdown documentation files - tables, box-drawing diagrams, list descriptions, and more.
+
+```
+┌────────────────────────┐       ┌────────────────────────┐
+│  ┌────┐   ┌────┐      │        │  ┌────┐   ┌────┐       │
+│  │ A  │   │ B  │      │        │  │ A  │   │ B  │       │
+│  └──┬─┘   └──┬─┘      │        │  └──┬─┘   └──┬─┘       │
+│     │         │        │       │     │        │         │
+│     └────┬───┘         │  -->  │     └────┬───┘         │
+│           v            │       │          v             │
+│     ┌──────┐           │       │     ┌──────┐           │
+ │     │  C   │           │      │     │  C   │           │
+│     └──────┘           │       │     └──────┘           │
+└────────────────────────┘       └────────────────────────┘
+```
+
+<details>
+<summary>More examples</summary>
+
+### [Tables](tests/fixtures/checks/tables)
+
+```
+| Service        | Usage                         |             | Service        | Usage                         |
+|----------------|-------------------------------|             |----------------|-------------------------------|
+| Linear API     | Status transitions, comments|        -->    | Linear API     | Status transitions, comments  |
+| GitHub API| Repo clone, PR creation       |                  | GitHub API     | Repo clone, PR creation       |
+```
+
+### [List descriptions](tests/fixtures/checks/list-descs)
+
+```
+- docs/repo.md - mirrors CI steps                       - docs/repo.md                    - mirrors CI steps
+- docs/guides/testing-strategy.md - test suite  -->     - docs/guides/testing-strategy.md - test suite
+```
+
+### [Box widths](tests/fixtures/checks/box-widths)
+
+```
+┌──────────────┐       ┌──────────────┐
+│  Linear UI  │   -->  │  Linear UI   │
+│  (userscript)│       │  (userscript)│
+└──────────────┘       └──────────────┘
+```
+
+### [Rail alignment](tests/fixtures/checks/rails)
+
+```
+┌──────┬──────┐       ┌──────┬──────┐
+│      │      │       │      │      │
+│       │     │  -->  │      │      │
+│      │      │       │      │      │
+└──────┴──────┘       └──────┴──────┘
+```
+
+### [Arrow alignment](tests/fixtures/checks/arrows)
+
+```
+┌──────┐                     ┌──────┐
+│ step │                     │ step │
+└──┬───┘                     └──┬───┘
+   │           -->              │
+     v                          v
+┌──────┐                     ┌──────┐
+│ next │                     │ next │
+└──────┘                     └──────┘
+```
+
+### [Pipe continuity](tests/fixtures/checks/pipes)
+
+```
+┌──────┬──────┐              ┌──────┬──────┐
+│ src  │ dest │              │ src  │ dest │
+└──────┴──┬───┘              └──────┴──┬───┘
+          │        -->                 │
+            │                          │
+          │                            │
+┌─────────┴───┐              ┌─────────┴───┐
+│   output    │              │   output    │
+└─────────────┘              └─────────────┘
+```
+
+### [Box spacing](tests/fixtures/checks/box-spacing)
+
+```
+┌───────────┐       ┌────────────┐
+│  errors[] │       │  errors[]  │
+│  (strings)│  -->  │  (strings) │
+└───────────┘       └────────────┘
+```
+
+### [Box walls](tests/fixtures/checks/box-walls)
+
+```
+┌──────────────────┐       ┌──────────────────┐
+│  content here    │       │  content here    │
+│  more text       │  -->  │  more text       │
+└────────────────┘         └──────────────────┘
+```
+
+</details>
+
+## Motivation
+
+In the era of agentic engineering, documentation is the most critical artifact in any codebase. It guides both humans and AI agents.
+When docs are visually harmonious - with aligned columns, consistent box widths, and straight connector lines - they become easier to read, parse, and maintain by everyone.
+
+## Features
+
+- 3 modes        - check (default), auto-fix in place, or unified diff
+- flexible paths - files, directories, or glob patterns (e.g. `"docs/**/*.md"`)
+- CI-friendly    - exit code 0 when aligned, 1 when issues found
+- 12 alignment checks:
+  - [Table columns](tests/fixtures/checks/tables)           - pads cells so every column matches the separator row width
+  - [Box widths](tests/fixtures/checks/box-widths)          - ensures all lines in a box group have the same total length
+  - [Box padding](tests/fixtures/checks/box-padding)        - normalizes left-padding of content lines inside boxes
+  - [Horizontal arrows](tests/fixtures/checks/horiz-arrows) - closes gaps between `─>` / `<─` arrow tips and box walls
+  - [Rail alignment](tests/fixtures/checks/rails)           - aligns vertically adjacent box chars to the same column
+  - [Arrow alignment](tests/fixtures/checks/arrows)         - aligns standalone `v`/`^` arrows; detects `v`/`^` embedded in borders
+  - [Pipe continuity](tests/fixtures/checks/pipes)          - traces from T-junctions to detect drifted connector pipes
+  - [Box spacing](tests/fixtures/checks/box-spacing)        - ensures minimum right-side spacing between content and box wall
+  - [Box walls](tests/fixtures/checks/box-walls)            - verifies nested box right walls match their opening/closing borders
+  - [List descriptions](tests/fixtures/checks/list-descs)   - aligns the separator dash in list item descriptions
+  - [Definition lists](tests/fixtures/checks/def-lists)     - aligns the `:` separator in `key: value` list items
+  - [Wide chars](tests/fixtures/checks/wide-chars)          - detects ambiguous/double-width Unicode chars in code blocks
+
+## Commands
+
+```bash
+docalign <path>                        # check-only (default) - detect issues, no writes
+docalign --check <path>                # explicit check-only (same as default)
+docalign --fix <path>                  # auto-fix files in place
+docalign --diff <path>                 # show unified diff of what would change
+docalign --verbose <path>              # show actionable hints with each error
+docalign --ignore tables,pipes <path>  # skip specific checks
+docalign --help                        # show help
+docalign --version                     # show version
+```
+
+Paths can be files, directories, or glob patterns (e.g. `"docs/**/*.md"`).
+
+Check names for `--ignore`: tables, box-widths, box-padding, box-spacing, horiz-arrows, box-walls, rails, arrows, pipes, list-descs, def-lists, wide-chars.
+
+Exit codes: 0 = all aligned, 1 = issues found.
+
+### Install
+
+```bash
+pipx install docalign
+# pip install docalign
+```
+
+### Update
+
+```bash
+pipx upgrade docalign
+# pip install --upgrade docalign
+```
+
+### Uninstall
+
+```bash
+pipx uninstall docalign
+# pip uninstall docalign
+```
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -v
+```