lintex 0.1.0__tar.gz

lintex-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Pinned: `ubuntu-latest` moved to 26.04, which has no Python 3.9 build for
+        # actions/setup-python, and we support 3.9.
+        os: [ubuntu-24.04]
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python: "3.13"
+          - os: macos-latest
+            python: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e . pytest pyyaml
+      - run: python -m pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -e . ruff
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+      - run: lintex check . --format github

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

@@ -0,0 +1,73 @@
+name: Release
+
+# Publishes to PyPI when a version tag (e.g. v0.1.0) is pushed, or to TestPyPI
+# (or PyPI) on demand from the Actions tab. Uses trusted publishing, so no
+# tokens are stored: configure a trusted publisher for this repository and
+# workflow at https://pypi.org/manage/account/publishing/ (environment `pypi`)
+# and, for rehearsals, at https://test.pypi.org/manage/account/publishing/
+# (environment `testpypi`).
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python -m pip install build twine
+      - name: Check the tag matches the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version=$(python -c "import re,pathlib;print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('src/lintex/__init__.py').read_text()).group(1))")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "tag v$tag does not match __version__ $version" >&2
+            exit 1
+          fi
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - name: Smoke-test the wheel in a clean environment
+        run: |
+          python -m venv /tmp/smoke && /tmp/smoke/bin/pip install -q dist/*.whl
+          /tmp/smoke/bin/lintex --version
+          echo 'from collections import Mapping' > /tmp/smoke/x.py
+          # lintex exits 1 when it finds something, which is what we expect here.
+          # Capture the status so `bash -e` (the Actions default) doesn't abort on it.
+          status=0
+          /tmp/smoke/bin/lintex check /tmp/smoke/x.py --format concise --no-color || status=$?
+          test "$status" -eq 1
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'workflow_dispatch' && inputs.target || 'pypi' }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish to PyPI
+        if: github.event_name != 'workflow_dispatch' || inputs.target == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

lintex-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/

lintex-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: lintex
+  name: lintex
+  description: Lint Python code written by LLM coding agents.
+  entry: lintex check
+  language: python
+  types: [python]
+  require_serial: false

lintex-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to lintex are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/). While the version is 0.x, rule defaults and
+severities may change between minor versions as they are tuned on real codebases.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-23
+
+First release.
+
+### Rules
+
+- **LX001** syntax-error: the file does not parse (often a truncated edit).
+- **LX101** hallucinated-api: removed, deprecated or Python-2-only APIs, from a curated pack
+  and a pack generated from typeshed. Stdlib removals are judged against the project's minimum
+  Python (`requires-python` or `target-version`).
+- **LX102** nonexistent-stdlib-name: names that don't exist in a stdlib module, with
+  "did you mean" suggestions (Python 3.10+).
+- **LX103** unresolvable-import (opt-in): imports that aren't installed, stdlib or local.
+- **LX201** sql-string-interpolation: SQL built with f-strings, `.format()`, `%` or `+`.
+- **LX202** raw-sql (opt-in): any raw SQL, for ORM-only projects.
+- **LX203** dangerous-call: `eval`/`exec`, unsafe deserialization, `yaml.load` without a safe
+  loader, `os.system`, `shell=True`, `verify=False`.
+- **LX204** insecure-file-operation: `tempfile.mktemp`, world-writable modes, tar
+  `extractall()` without `filter=`, hard-coded `/tmp` paths.
+- **LX205** banned-api: project-specific banned modules and functions with custom messages.
+- **LX301–LX305** agent bloat: function length, cyclomatic complexity, parameter count,
+  nesting depth, module length.
+- **LX401** placeholder-code: comments standing in for elided code, stub markers.
+- **LX402** swallowed-exception, **LX403** bare-except.
+
+### Tooling
+
+- `lintex check` with `--format pretty|full|concise|github|json`, `--staged`, `--changed`,
+  `--select`/`--ignore`/`--enable`, `--fail-on`, inline `# lintex: ignore[CODE]` and
+  `# lintex: skip-file`.
+- Configuration in `pyproject.toml` `[tool.lintex]`, `.lintex.toml` or `.lintex.yaml`.
+- Claude Code `PostToolUse` hook that feeds findings (with `why` and `fix`) back to the agent.
+- Session ledger with `lintex report` and a Claude Code status line (`lintex statusline`).
+- Git pre-commit hook (`lintex install-hook git`) and a `.pre-commit-hooks.yaml`.
+- `python -m lintex.knowledge.sync` to regenerate the typeshed knowledge pack.
+
+[Unreleased]: https://github.com/700799/lintex/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/700799/lintex/releases/tag/v0.1.0

lintex-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to lintex
+
+Thanks for helping. The most valuable contributions, in order, are: a false positive with a
+minimal reproduction, a new API knowledge entry, and a new rule.
+
+## Set up
+
+```bash
+git clone https://github.com/700799/lintex && cd lintex
+python -m venv .venv && . .venv/bin/activate
+pip install -e . pytest pyyaml ruff mypy
+pytest                                    # the suite runs in well under a second
+ruff check src tests && ruff format --check src tests
+lintex check .                            # lintex lints itself and must stay clean
+```
+
+CI runs the same three commands on Python 3.9–3.13, Windows and macOS.
+
+## Report a false positive
+
+Open an issue with the smallest snippet that triggers it, the lintex version, and your
+Python version. Precision matters more than recall here: a rule that cries wolf gets turned
+off, so a confirmed false positive is a bug.
+
+## Add an API knowledge entry
+
+Removed, deprecated and Python-2-only names for LX101 live in
+`src/lintex/knowledge/curated.toml`. An entry is:
+
+```toml
+[[api]]
+name = "requests.packages.urllib3"
+status = "removed"          # removed | deprecated | py2
+package = "requests"        # omit for the standard library
+version = "2.16"
+fix = "Use `import urllib3` directly."
+```
+
+Write the `fix` as something an agent can paste: the replacement, not a description of it.
+Add a line to `tests/test_rules_hallucinations.py` showing it fires. Stdlib module removals and
+`@deprecated` names are generated into `typeshed.json`; don't edit that file, regenerate it
+with `python -m lintex.knowledge.sync --from-mypy` (stdlib) or `--typeshed PATH` (with
+third-party stubs). A curated entry overrides a generated one for the same name, which is the
+way to give a generated entry a better fix.
+
+## Add a rule
+
+1. Subclass `lintex.rules.base.Rule` in the module for its family (`hallucinations`,
+   `banned_patterns`, `bloat`, `agent_artifacts`). Set `code`, `name`, `summary`,
+   `explanation`, `default_severity`, `node_types` and, if configurable, `options`.
+2. Implement `check_node` (called for each node whose type is in `node_types`) and/or
+   `check_file`. Use `ctx.resolve(node)` to turn a Name/Attribute chain into an
+   import-qualified name, and `is_compat_guarded` to skip `try/except ImportError` blocks.
+3. Every violation needs a `message` (what), a `why` (the failure mode) and a `fix` (what to
+   write instead). Assume the reader is an LLM with no other context.
+4. Register it in `ALL_RULES` in `src/lintex/rules/__init__.py` and add tests with both a
+   triggering case and a clean case that looks similar.
+5. Run it over a large real codebase before opening the PR (the CPython stdlib is a good
+   known-good corpus: `lintex check $(python -c "import sysconfig;print(sysconfig.get_paths()['stdlib'])") --select LXnnn`).
+   New rules default to `warning` unless the finding is almost never wrong.
+
+## Keep the engine fast
+
+Rules run inside a single AST walk, dispatched by node type. Don't re-walk the tree in a rule;
+keep per-file state in `ctx.state[self.code]` and finish in `check_file`. Anything that reads
+files or imports modules must be cached across files.
+
+## Commit messages and PRs
+
+Explain the *why* in the commit body; the diff already shows the what. Keep PRs to one change.
+A PR that adds a rule should include the false-positive numbers from the corpus run.

lintex-0.1.0/LICENSE

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