house-lint
Lint checks that catch the habits AI coding assistants leave behind.
AI coding assistants write code that runs and passes review at a glance, but they leave the same habits behind:
- filler phrases in comments ("it is important to note", "leverage")
- imports tucked inside functions
- constants defined halfway down the module
- files that keep growing
- planning-ticket IDs (
AC1,T05) leaking into the code - the same block pasted into a third module
Reviewers stop reading comments that all sound the same, and nobody notices the import buried in a function until it breaks a mock. house-lint flags these habits; the rules table shows what it checks today.
It complements Ruff rather than replacing it. A check belongs here when it targets a pattern AI-assisted code produces and Ruff and the type checker don't already catch it. The rules are opinionated, and you choose which ones to enable. They started as scripts in one project and now live here, so every project gets the same checks from one versioned tool.
Today every rule analyzes one Python file at a time. Next come checks that compare files across a project, starting with duplicate-code detection for Python and TypeScript (#39), then complexity and dead code (#53).
Quick start
You need Python 3.11 or later.
uvx house-lint check
With no configuration, house-lint scans the whole project tree from the project root (the nearest directory at or above the current one with a house-lint config, or failing that, with a pyproject.toml or .git), skips anything git ignores, and runs the four default rules. The output lists the root, configuration, enabled rules, file counts, findings, and a summary.
To pin it as a development dependency:
uv add --dev house-lint
uv run house-lint check
Rules
| ID | Default | Checks |
|---|---|---|
HSL001 |
On | AI-writing tells in comments and docstrings (never ordinary strings) |
HSL002 |
On | Imports inside function or async-function bodies |
HSL003 |
On | Top-level TYPE_CHECKING import blocks placed before regular imports |
HSL004 |
On | Module constants defined after the first class or function, except derived bindings |
HSL101 |
Off | Planning and spec tokens (built-in families like AC1, T05, KI-001, plus your own such as JIRA-123) in comments, docstrings, and filenames |
HSL102 |
Off | Files longer than a configured line limit (default 800) |
HSL103 |
Off | Bound exception names outside an allowed policy (default exc or *_exc) |
HSL900 |
Always | Invalid, unused, conflicting, or malformed suppressions; cannot be disabled |
house-lint rules --format json prints the installed rule metadata. The rule reference describes exactly what each rule flags and what it leaves alone.
Configuration
Configure house-lint in pyproject.toml under [tool.house-lint], or in a standalone house-lint.toml or .house-lint.toml:
[tool.house-lint]
include = ["src", "tests"] # optional; default is the whole tree
exclude = ["generated/"] # gitignore-style patterns, no negation
extend-select = ["HSL102", "HSL103"]
[tool.house-lint.rules.HSL102]
max_lines = 600
[tool.house-lint.per-file-ignores]
"tests/**" = ["HSL002"]
selectsets the base selection andignoreremoves rules from it.extend-selectandextend-ignoreadd and remove on top of that base.- On the command line,
--selectreplaces the configured base.--extend-selectand--extend-ignorecombine with the configured values. A CLI--ignoreis applied last and always wins. - Each flag occurrence takes one comma-separated list. Selection is strict: unknown, duplicate, or empty rule IDs are usage errors.
Configuration covers config file discovery, precedence, scan scope, excludes, rule options, and HSL101 token families.
Suppressions
Every suppression names the rule and gives a reason of at least three alphanumeric characters:
# house-lint: ignore-file[HSL102] - generated compatibility module
def load_plugin():
import plugin # house-lint: ignore[HSL002] - avoids a circular import
# house-lint: ignore-next[HSL004] - kept beside the loader it configures
RETRIES = 3
try:
callback()
except OSError as error: # house-lint: ignore[HSL103] - compatibility callback signature
raise
ignorecovers the statement it sits on. Anexceptclause is its own statement, so its pragma goes on theexceptline.ignore-nexton its own line covers the next statement in the same block, skipping comments and blank lines.ignore-filecovers the whole file for the listed rules. It must come before the first statement other than a docstring or__future__import.
HSL900 flags suppressions that are malformed, misplaced, unused, duplicated, or that name an unknown or disabled rule, so stale suppressions don't pile up. See suppressions.
Paths and roots
house-lint check # configured scope, or the whole tree
house-lint check src/service.py tests # only these files and directories
- Explicit paths are strict: a missing path, a path outside the root, or a non-Python file is an error.
- An explicit file that matches a built-in or configured exclude is skipped. An explicit file that is only gitignored is linted.
--rootfixes the project boundary. Without--config, house-lint looks in the root forhouse-lint.toml, then.house-lint.toml, then apyproject.tomlwith[tool.house-lint].--confignames an exact configuration file, and its directory becomes the root unless--rootis given.
Inside a git repository, house-lint takes its file list from git ls-files, so tracked files are scanned and untracked ignored files aren't. A git failure there stops the run with exit code 3. Outside a repository, or with --no-git, it walks the directory and reads no ignore files. See File selection.
Pre-commit
The published hook runs house-lint on staged Python files, serially rather than in parallel batches:
repos:
- repo: https://github.com/NodeJSmith/house-lint
rev: v0.2.0
hooks:
- id: house-lint
Or run an installed copy as a local hook:
repos:
- repo: local
hooks:
- id: house-lint
name: house-lint
entry: house-lint check
language: system
types: [python]
require_serial: true
Caching
check caches each file's result under <root>/.house-lint-cache/. The key covers the file's content, the rules and rule options in effect, and the Python version; configuration lists every input. A hit skips parsing and rule execution.
The cache directory is namespaced by house-lint's version and a fingerprint of its own source, so upgrading starts from a clean cache. Old directories are pruned.
--no-cacheskips reading the cache but still refreshes it.--cache-dirmoves it.
A cache failure never fails a scan. house-lint prints one warning for the first failure in a run, and --debug shows the rest.
Output and exit codes
--format json prints one schema-versioned JSON object to stdout (schema_version 2) with the root, config, enabled rules, file counts, findings, errors, and summary. Match on rule IDs, locations, and error code values. Finding message text is for people and may change.
| Exit | Meaning |
|---|---|
| 0 | Clean scan |
| 1 | Findings, including HSL900 |
| 2 | Usage or configuration error; nothing was scanned |
| 3 | Incomplete scan: path, traversal, git, budget, read, decode, tokenize, or syntax error |
| 4 | Unexpected internal error |
When several apply, the highest code wins.
| Error code | Meaning |
|---|---|
config-error |
Invalid CLI arguments, configuration, or root |
path-error |
Invalid explicit path or source path |
traversal-error |
Discovery filesystem failure; the rest of the scan still ran |
git-error |
git failed inside a repository; nothing was scanned |
budget-error |
A discovery or candidate-count safety limit was exceeded |
source-too-large |
A source file exceeds the 10 MiB read limit |
read-error |
A source file could not be read |
decode-error |
A source file could not be decoded |
tokenize-error |
A source file could not be tokenized |
syntax-error |
A source file could not be parsed as Python |
internal-error |
An unexpected failure reached the CLI boundary |
Development
uv run pytest
uv run ruff check .
uv run pyright
CI runs the tests on Python 3.11 through 3.14, plus Ruff, Pyright, and a package build. This repo also runs house-lint on itself through prek.toml. Release Please cuts releases from Conventional Commits and publishes to PyPI. See the changelog for compatibility notes.
Metadata
Release files for house-lint 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| house_lint-0.4.0.tar.gz | 58.0 kB | With provenance | Details for house_lint-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| house_lint-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for house_lint-0.4.0-py3-none-any.whl |
Total release size: 126.3 kB
Release files / house_lint-0.4.0.tar.gz
| Download URL | house_lint-0.4.0.tar.gz |
|---|---|
| Size | 58.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4824937d73d70c72c67be6fb2d4e7790a7dc03b07a808f05552cb45346a1192a
|
|
BLAKE2b-256 checksum How to use checksums |
dc792f0148b65af6295507045571188c0b593c43dd530da40eb59f14298b3d6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logRelease files / house_lint-0.4.0-py3-none-any.whl
| Download URL | house_lint-0.4.0-py3-none-any.whl |
|---|---|
| Size | 68.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d4d4717ebaf6fafc828c529d57b56f7a513e7c8271d078b0f6d9179c7ea9096b
|
|
BLAKE2b-256 checksum How to use checksums |
b9116614b4f80461875dd65904778cbc491d73bf9c0d9f35df90474537961f2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logSecurity for house-lint 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for house_lint-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.