asciilint 0.1.0__tar.gz

asciilint-0.1.0/.github/workflows/ci-tests.yml

@@ -0,0 +1,56 @@
+name: CI tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          # we are using the -e flag, so that code cov finds the source.
+          # this is not ideal, since installing an editable can technically
+          # differ from a normal install in surprising ways.
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest
+          pytest
+
+      # - name: Upload coverage reports to Codecov
+      #   uses: codecov/codecov-action@v4
+      #   with:
+      #     name: "py${{ matrix.python-version }}"
+      #     token: ${{ secrets.CODECOV_TOKEN }}
+
+  test-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest
+          pytest

asciilint-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical mkdocstrings-python
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

asciilint-0.1.0/.github/workflows/mypy.yml

@@ -0,0 +1,34 @@
+name: Mypy check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  mypy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run Type Checks
+        run: |
+          uv run mypy .

asciilint-0.1.0/.github/workflows/ruff-check.yml

@@ -0,0 +1,25 @@
+name: Ruff check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  ruff-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+      - name: Run Ruff
+        run: ruff check --output-format=github .

asciilint-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Zensical site
+/site/
+
+# Vendor files
+/vendor/

asciilint-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14.6

asciilint-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## asciilint 0.1.0
+
+### New features
+
+- Added the `asciilint` command-line interface for recursively scanning projects
+  for disallowed characters in UTF-8 text files.
+- Added ASCII-only defaults to detect non-ASCII characters with no required
+  configuration.
+- Added configurable character policies with arbitrary allowed and disallowed
+  literal characters and Unicode code point ranges.
+- Added `asciilint.toml` support, parsed with `tomllib`, plus equivalent
+  command line options for CI usage.
+- Added gitignore-syntax file filtering with `pathspec`, including
+  `.gitignore`, `.asciilintignore`, and user-specified ignore files.
+- Added automatic binary file skipping using the zlib `txtvsbin` heuristic.
+- Added explicit reporting for files that look like text but are not valid UTF-8.
+- Added concise terminal output with file, line, column, code point, and
+  summary information suitable for local use and CI logs.
+- Added project documentation and pytest coverage for CLI behavior,
+  policy parsing, ignore handling, binary detection, and UTF-8 errors.

asciilint-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026, asciilint authors
+
+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.

asciilint-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: asciilint
+Version: 0.1.0
+Summary: ASCII and character policy checks for text files
+Project-URL: Homepage, https://nanx.me/asciilint/
+Project-URL: Documentation, https://nanx.me/asciilint/
+Project-URL: Repository, https://github.com/nanxstats/asciilint
+Project-URL: Issues, https://github.com/nanxstats/asciilint/issues
+Project-URL: Changelog, https://github.com/nanxstats/asciilint/blob/main/CHANGELOG.md
+Author-email: Nan Xiao <me@nanx.me>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.4.2
+Requires-Dist: pathspec>=1.1.1
+Description-Content-Type: text/markdown
+
+# asciilint
+
+[![PyPI version](https://img.shields.io/pypi/v/asciilint)](https://pypi.org/project/asciilint/)
+![Python versions](https://img.shields.io/pypi/pyversions/asciilint)
+[![CI tests](https://github.com/nanxstats/asciilint/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/ci-tests.yml)
+[![Mypy check](https://github.com/nanxstats/asciilint/actions/workflows/mypy.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/mypy.yml)
+[![Ruff check](https://github.com/nanxstats/asciilint/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/ruff-check.yml)
+[![Documentation](https://github.com/nanxstats/asciilint/actions/workflows/docs.yml/badge.svg)](https://nanx.me/asciilint/)
+![License](https://img.shields.io/pypi/l/asciilint)
+
+Minimal, configurable, CI-friendly character policy checks for text files.
+
+By default, `asciilint` recursively scans a project and fails when UTF-8
+text files contain non-ASCII characters. It can also enforce arbitrary Unicode
+allowlists and denylists, so it is useful for broader character policy checks.
+
+## Installation
+
+```bash
+pip install asciilint
+```
+
+With `uv`:
+
+```bash
+uv add asciilint
+```
+
+## Usage
+
+```bash
+asciilint .
+```
+
+Example failing output:
+
+```text
+> Checking characters in /path/to/project
+Files found: 3, 2 text, 0 binary skipped, 1 ignored
+Checking text: ✓x
+
+Issues :-(
+> Disallowed characters
+  1. docs/page.md
+     1. [L012:C018] U+2014 "\u2014" not allowed by policy
+Summary: 1 disallowed character(s), 0 read error(s)
+```
+
+Exit code `0` means no issues. Exit code `1` means disallowed characters or
+read errors were found.
+
+## Configuration
+
+Create `asciilint.toml`:
+
+```toml
+[asciilint]
+paths = ["."]
+respect_gitignore = true
+ignore_files = [".asciilintignore"]
+allowed_ranges = ["U+0000-U+007F"]
+allowed_chars = []
+disallowed_ranges = []
+disallowed_chars = []
+max_issues_per_file = 5
+```
+
+Ignore files use gitignore syntax and are matched with `pathspec`.
+`.gitignore` is respected by default.
+You can add other ignore files, for example:
+
+```bash
+asciilint . --ignore-file .asciilintignore --ignore-file config/lint.ignore
+```
+
+Character ranges can be written as `U+0000-U+007F`, `0x20..0x7e`, `32-126`, or
+single code points such as `U+00A9`. Deny rules take precedence over allow rules.
+
+To allow any Unicode character except a small denylist:
+
+```bash
+asciilint . --allow-any --disallowed-char "→" --disallowed-range U+2000-U+206F
+```
+
+## UTF-8 and binary files
+
+`asciilint` assumes text files are UTF-8. Files that are classified as text but
+cannot be decoded as UTF-8 are reported explicitly and skipped. Binary files are
+skipped automatically using the zlib `txtvsbin` heuristic.

asciilint-0.1.0/README.md

@@ -0,0 +1,89 @@
+# asciilint
+
+[![PyPI version](https://img.shields.io/pypi/v/asciilint)](https://pypi.org/project/asciilint/)
+![Python versions](https://img.shields.io/pypi/pyversions/asciilint)
+[![CI tests](https://github.com/nanxstats/asciilint/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/ci-tests.yml)
+[![Mypy check](https://github.com/nanxstats/asciilint/actions/workflows/mypy.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/mypy.yml)
+[![Ruff check](https://github.com/nanxstats/asciilint/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/ruff-check.yml)
+[![Documentation](https://github.com/nanxstats/asciilint/actions/workflows/docs.yml/badge.svg)](https://nanx.me/asciilint/)
+![License](https://img.shields.io/pypi/l/asciilint)
+
+Minimal, configurable, CI-friendly character policy checks for text files.
+
+By default, `asciilint` recursively scans a project and fails when UTF-8
+text files contain non-ASCII characters. It can also enforce arbitrary Unicode
+allowlists and denylists, so it is useful for broader character policy checks.
+
+## Installation
+
+```bash
+pip install asciilint
+```
+
+With `uv`:
+
+```bash
+uv add asciilint
+```
+
+## Usage
+
+```bash
+asciilint .
+```
+
+Example failing output:
+
+```text
+> Checking characters in /path/to/project
+Files found: 3, 2 text, 0 binary skipped, 1 ignored
+Checking text: ✓x
+
+Issues :-(
+> Disallowed characters
+  1. docs/page.md
+     1. [L012:C018] U+2014 "\u2014" not allowed by policy
+Summary: 1 disallowed character(s), 0 read error(s)
+```
+
+Exit code `0` means no issues. Exit code `1` means disallowed characters or
+read errors were found.
+
+## Configuration
+
+Create `asciilint.toml`:
+
+```toml
+[asciilint]
+paths = ["."]
+respect_gitignore = true
+ignore_files = [".asciilintignore"]
+allowed_ranges = ["U+0000-U+007F"]
+allowed_chars = []
+disallowed_ranges = []
+disallowed_chars = []
+max_issues_per_file = 5
+```
+
+Ignore files use gitignore syntax and are matched with `pathspec`.
+`.gitignore` is respected by default.
+You can add other ignore files, for example:
+
+```bash
+asciilint . --ignore-file .asciilintignore --ignore-file config/lint.ignore
+```
+
+Character ranges can be written as `U+0000-U+007F`, `0x20..0x7e`, `32-126`, or
+single code points such as `U+00A9`. Deny rules take precedence over allow rules.
+
+To allow any Unicode character except a small denylist:
+
+```bash
+asciilint . --allow-any --disallowed-char "→" --disallowed-range U+2000-U+206F
+```
+
+## UTF-8 and binary files
+
+`asciilint` assumes text files are UTF-8. Files that are classified as text but
+cannot be decoded as UTF-8 are reported explicitly and skipped. Binary files are
+skipped automatically using the zlib `txtvsbin` heuristic.

asciilint-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "asciilint"
+version = "0.1.0"
+description = "ASCII and character policy checks for text files"
+authors = [{ name = "Nan Xiao", email = "me@nanx.me" }]
+readme = "README.md"
+dependencies = ["click>=8.4.2", "pathspec>=1.1.1"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+
+    "Intended Audience :: Developers",
+
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Text Processing",
+    "Topic :: Utilities",
+
+    "Operating System :: OS Independent",
+
+    "License :: OSI Approved :: MIT License",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+requires-python = ">=3.11"
+
+[project.scripts]
+asciilint = "asciilint.cli:main"
+
+[project.urls]
+Homepage = "https://nanx.me/asciilint/"
+Documentation = "https://nanx.me/asciilint/"
+Repository = "https://github.com/nanxstats/asciilint"
+Issues = "https://github.com/nanxstats/asciilint/issues"
+Changelog = "https://github.com/nanxstats/asciilint/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/docs", "/scripts", "/AGENTS.md", "/uv.lock", "/zensical.toml"]
+
+[tool.hatch.build.targets.wheel]
+exclude = ["/docs", "/scripts", "/AGENTS.md", "/uv.lock", "/zensical.toml"]
+
+[dependency-groups]
+dev = [
+    "isort>=8.0.1",
+    "mkdocstrings-python>=2.0.5",
+    "mypy>=2.1.0",
+    "pytest>=9.1.1",
+    "ruff>=0.15.20",
+    "zensical>=0.0.46",
+]
+
+[tool.ruff]
+exclude = ["vendor", ".venv"]
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+
+[tool.isort]
+profile = "black"
+skip = ["vendor", ".venv"]
+
+[tool.mypy]
+exclude = ["vendor/"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

asciilint-0.1.0/src/asciilint/__init__.py

@@ -0,0 +1,12 @@
+"""ASCII and character policy checks for text files."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("asciilint")
+except (
+    PackageNotFoundError
+):  # pragma: no cover - package is not installed in editable docs
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

asciilint-0.1.0/src/asciilint/__main__.py

@@ -0,0 +1,6 @@
+"""Run asciilint as ``python -m asciilint``."""
+
+from asciilint.cli import main
+
+if __name__ == "__main__":
+    main()