readability-cli 0.4.0__tar.gz

readability_cli-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.14'
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run linting
+        run: uv run ruff check .
+
+      - name: Run formatting check
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest

readability_cli-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.14'
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

readability_cli-0.4.0/.github/workflows/update-guides.yml

@@ -0,0 +1,33 @@
+name: Update Style Guides
+
+on:
+  schedule:
+    - cron: '0 0 * * 0' # Weekly on Sunday at midnight
+  workflow_dispatch: # Ad-hoc trigger
+
+jobs:
+  update-guides:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Sync guides
+        run: uv run readability sync --verbose
+
+      - name: Commit and push changes
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore: update style guides [skip ci]"
+          file_pattern: 'guides/*.md'

readability_cli-0.4.0/.gitignore

@@ -0,0 +1,152 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so may be deleted later.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+pytestdebug.log
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore it in the repository,
+#   but for a top-level application, you might want to keep it.
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, Pipfile.lock might cause issues.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+
+# PEP 582; used by e.g. github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# Ruff
+.ruff_cache/

readability_cli-0.4.0/.python-version

@@ -0,0 +1 @@
+3.12

readability_cli-0.4.0/LICENSE

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

readability_cli-0.4.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: readability-cli
+Version: 0.4.0
+Summary: A CLI to lint, format, and type-check code with Google-style defaults, and pull Google style guides in markdown format.
+Project-URL: Homepage, https://github.com/owahltinez/readability
+Project-URL: Repository, https://github.com/owahltinez/readability
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: click>=8.3.1
+Requires-Dist: markdownify>=1.2.2
+Requires-Dist: requests>=2.33.0
+Description-Content-Type: text/markdown
+
+# Readability
+
+A CLI tool that keeps code aligned with Google style conventions. It runs the
+right linters, formatters, and type checkers for your project with sensible
+defaults, and serves the official Google style guides in Markdown format. This
+is ideal for AI agents or developers who want consistent code quality checks
+and quick access to style conventions without browsing HTML pages.
+
+## Features
+
+- **Linting & Formatting**: A `check` command that automatically detects and
+  runs relevant tools (Ruff, Pyrefly, Biome, Prettier, gofmt) for your project.
+- **Sensible Defaults**: Bundled Google-style configurations for Ruff and
+  Pyrefly are used automatically when a project does not define its own.
+- **Style Guides**: A `guide` command that fetches the latest Google style
+  guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown.
+- **Offline Mode**: Local caching of style guides for fast, offline access,
+  kept fresh with a single `sync` command.
+
+## Quick Start
+
+You can run the tool directly without installing it using `uvx`:
+
+```bash
+# Check and fix formatting for the current directory
+uvx --from git+https://github.com/owahltinez/readability.git readability check . --fix
+
+# Get the Python style guide
+uvx --from git+https://github.com/owahltinez/readability.git readability guide python
+```
+
+## Installation
+
+Install it as a global tool with `uv`:
+
+```bash
+# Install the readability tool
+uv tool install git+https://github.com/owahltinez/readability.git
+
+# Use it anywhere
+readability check .
+readability guide python
+```
+
+### For Development
+
+This project uses `uv` for dependency management:
+
+```bash
+# Clone the repository
+git clone https://github.com/owahltinez/readability.git
+cd readability
+
+# Install dependencies and create a virtual environment
+uv sync
+
+# (Optional) Populate the local cache for offline use
+uv run readability sync
+```
+
+## Checking and Formatting
+
+The `check` command identifies and runs relevant linting and formatting tools
+based on file extensions and the presence of configuration files (triggers) in
+your project root:
+
+```bash
+# Run checks on the current directory
+readability check .
+
+# Check specific files or directories
+readability check src/ tests/ main.py
+
+# Automatically fix and format files
+readability check . --fix
+```
+
+### Supported Tools
+
+| Tool | Supported Extensions | Trigger Files |
+|------|----------------------|---------------|
+| **Ruff** | `.py` | `pyproject.toml`, `ruff.toml`, `.ruff.toml` |
+| **Pyrefly** | `.py` | `pyproject.toml`, `pyrefly.toml` |
+| **Biome** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html` | `biome.json`, `biome.jsonc` |
+| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | `.prettierrc*`, `prettier.config.*` |
+| **gofmt** | `.go` | `go.mod` |
+
+The command will only run a tool if its trigger file exists in the current
+working directory and the tool is available in your `PATH`. For `biome` and
+`prettier`, it attempts to run them via `npx`.
+
+### Default Configurations
+
+For Ruff and Pyrefly, bundled defaults based on the
+[Google Python style guide](https://google.github.io/styleguide/pyguide.html)
+(80-column lines, Google docstring convention, import ordering, full type
+checking) are applied when the project does not define its own configuration.
+To override them, add a `[tool.ruff]` or `[tool.pyrefly]` section to your
+`pyproject.toml` (or a dedicated `ruff.toml` / `pyrefly.toml`) — any
+project-level configuration takes full precedence over the bundled defaults.
+
+## Style Guides
+
+The `guide` command prints a Google style guide as Markdown, using the local
+cache when available:
+
+```bash
+# Get the Python style guide (uses local cache if available)
+readability guide python
+
+# Force fetching the latest version from the web
+readability guide python --remote
+
+# Save a style guide to a file
+readability guide cpp --output cpp-style.md
+
+# Synchronize all supported style guides to the local cache
+readability sync
+```
+
+### Supported Languages
+
+Use `readability languages` to see a full list of supported languages and
+their aliases. This command also indicates which guides are currently
+available in the local cache with a `[cached]` label:
+
+```bash
+$ readability languages
+Supported languages and their aliases:
+  - r [cached]
+  - c++, cpp [cached]
+  - c#, csharp [cached]
+  - docguide, markdown [cached]
+  - go [cached]
+  - css, html [cached]
+  - java [cached]
+  - javascript, js [cached]
+  - json [cached]
+  - objc, objective-c [cached]
+  - python [cached]
+  - shell [cached]
+  - ts, typescript [cached]
+  - vim [cached]
+```
+
+### Offline Mode
+
+The tool stores local copies of the style guides in the `guides/` directory
+and the `guide` command uses these local files when they exist. The bundled
+copies are automatically synchronized weekly from the official
+[Google Style Guides](https://google.github.io/styleguide/) repository via
+GitHub Actions, and you can refresh your local cache at any time with the
+`sync` command.
+
+You can override the default `guides/` directory by setting the
+`READABILITY_CACHE` environment variable. This is useful if you want to store
+the guides in a specific location or share them across different
+installations:
+
+```bash
+export READABILITY_CACHE=/path/to/my/guides
+readability guide python
+```
+
+## Development
+
+Run tests with `pytest`:
+
+```bash
+uv run pytest
+```
+
+Check code style with `ruff`:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```

readability_cli-0.4.0/README.md

@@ -0,0 +1,178 @@
+# Readability
+
+A CLI tool that keeps code aligned with Google style conventions. It runs the
+right linters, formatters, and type checkers for your project with sensible
+defaults, and serves the official Google style guides in Markdown format. This
+is ideal for AI agents or developers who want consistent code quality checks
+and quick access to style conventions without browsing HTML pages.
+
+## Features
+
+- **Linting & Formatting**: A `check` command that automatically detects and
+  runs relevant tools (Ruff, Pyrefly, Biome, Prettier, gofmt) for your project.
+- **Sensible Defaults**: Bundled Google-style configurations for Ruff and
+  Pyrefly are used automatically when a project does not define its own.
+- **Style Guides**: A `guide` command that fetches the latest Google style
+  guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown.
+- **Offline Mode**: Local caching of style guides for fast, offline access,
+  kept fresh with a single `sync` command.
+
+## Quick Start
+
+You can run the tool directly without installing it using `uvx`:
+
+```bash
+# Check and fix formatting for the current directory
+uvx --from git+https://github.com/owahltinez/readability.git readability check . --fix
+
+# Get the Python style guide
+uvx --from git+https://github.com/owahltinez/readability.git readability guide python
+```
+
+## Installation
+
+Install it as a global tool with `uv`:
+
+```bash
+# Install the readability tool
+uv tool install git+https://github.com/owahltinez/readability.git
+
+# Use it anywhere
+readability check .
+readability guide python
+```
+
+### For Development
+
+This project uses `uv` for dependency management:
+
+```bash
+# Clone the repository
+git clone https://github.com/owahltinez/readability.git
+cd readability
+
+# Install dependencies and create a virtual environment
+uv sync
+
+# (Optional) Populate the local cache for offline use
+uv run readability sync
+```
+
+## Checking and Formatting
+
+The `check` command identifies and runs relevant linting and formatting tools
+based on file extensions and the presence of configuration files (triggers) in
+your project root:
+
+```bash
+# Run checks on the current directory
+readability check .
+
+# Check specific files or directories
+readability check src/ tests/ main.py
+
+# Automatically fix and format files
+readability check . --fix
+```
+
+### Supported Tools
+
+| Tool | Supported Extensions | Trigger Files |
+|------|----------------------|---------------|
+| **Ruff** | `.py` | `pyproject.toml`, `ruff.toml`, `.ruff.toml` |
+| **Pyrefly** | `.py` | `pyproject.toml`, `pyrefly.toml` |
+| **Biome** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html` | `biome.json`, `biome.jsonc` |
+| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | `.prettierrc*`, `prettier.config.*` |
+| **gofmt** | `.go` | `go.mod` |
+
+The command will only run a tool if its trigger file exists in the current
+working directory and the tool is available in your `PATH`. For `biome` and
+`prettier`, it attempts to run them via `npx`.
+
+### Default Configurations
+
+For Ruff and Pyrefly, bundled defaults based on the
+[Google Python style guide](https://google.github.io/styleguide/pyguide.html)
+(80-column lines, Google docstring convention, import ordering, full type
+checking) are applied when the project does not define its own configuration.
+To override them, add a `[tool.ruff]` or `[tool.pyrefly]` section to your
+`pyproject.toml` (or a dedicated `ruff.toml` / `pyrefly.toml`) — any
+project-level configuration takes full precedence over the bundled defaults.
+
+## Style Guides
+
+The `guide` command prints a Google style guide as Markdown, using the local
+cache when available:
+
+```bash
+# Get the Python style guide (uses local cache if available)
+readability guide python
+
+# Force fetching the latest version from the web
+readability guide python --remote
+
+# Save a style guide to a file
+readability guide cpp --output cpp-style.md
+
+# Synchronize all supported style guides to the local cache
+readability sync
+```
+
+### Supported Languages
+
+Use `readability languages` to see a full list of supported languages and
+their aliases. This command also indicates which guides are currently
+available in the local cache with a `[cached]` label:
+
+```bash
+$ readability languages
+Supported languages and their aliases:
+  - r [cached]
+  - c++, cpp [cached]
+  - c#, csharp [cached]
+  - docguide, markdown [cached]
+  - go [cached]
+  - css, html [cached]
+  - java [cached]
+  - javascript, js [cached]
+  - json [cached]
+  - objc, objective-c [cached]
+  - python [cached]
+  - shell [cached]
+  - ts, typescript [cached]
+  - vim [cached]
+```
+
+### Offline Mode
+
+The tool stores local copies of the style guides in the `guides/` directory
+and the `guide` command uses these local files when they exist. The bundled
+copies are automatically synchronized weekly from the official
+[Google Style Guides](https://google.github.io/styleguide/) repository via
+GitHub Actions, and you can refresh your local cache at any time with the
+`sync` command.
+
+You can override the default `guides/` directory by setting the
+`READABILITY_CACHE` environment variable. This is useful if you want to store
+the guides in a specific location or share them across different
+installations:
+
+```bash
+export READABILITY_CACHE=/path/to/my/guides
+readability guide python
+```
+
+## Development
+
+Run tests with `pytest`:
+
+```bash
+uv run pytest
+```
+
+Check code style with `ruff`:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```

readability_cli-0.4.0/configs/pyrefly.toml

@@ -0,0 +1,11 @@
+# Default configuration used by `readability check` when the target project
+# does not define its own pyrefly settings (pyrefly.toml or [tool.pyrefly] in
+# pyproject.toml). The presence of a config file switches pyrefly from its
+# lenient "basic" preset to full type checking.
+
+[errors]
+# When this bundled config is used, pyrefly treats its directory as the
+# project root, so imports local to the checked project cannot be resolved
+# reliably; suppress those errors to avoid false positives
+missing-import = false
+missing-module-attribute = false

readability_cli-0.4.0/configs/ruff.toml

@@ -0,0 +1,20 @@
+# Default configuration used by `readability check` when the target project
+# does not define its own ruff settings (ruff.toml or [tool.ruff] in
+# pyproject.toml). Based on the Google Python style guide:
+# https://google.github.io/styleguide/pyguide.html
+line-length = 80
+
+[lint]
+# Pycodestyle (E, W), Pyflakes (F), import order (I), naming (N),
+# docstrings (D), and pylint (PL) rules
+select = ["E", "W", "F", "I", "N", "D", "PL"]
+# Complexity counters and magic-value warnings are guidance, not errors
+ignore = ["PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR2004"]
+
+[lint.pydocstyle]
+convention = "google"
+
+[lint.per-file-ignores]
+# Docstring requirements are noise in test files
+"test_*.py" = ["D"]
+"*_test.py" = ["D"]