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.
Every rule but one analyzes one Python file at a time. The exception is HSL104, which finds code copied across a project. More cross-file checks come next: 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) |
HSL104 |
Off | Code copied three or more times across the project, found with jscpd (needs house-lint[duplicates]) |
HSL105 |
Off | Mypy-style # type: ignore[code] comments, whose codes Pyright disregards |
HSL900 |
Always | Malformed, misplaced, or invalid suppressions; cannot be disabled |
HSL901 |
Off | Stale suppressions: unused, redundant, or naming a rule that doesn't run on the file |
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 selection,extend-selectandextend-ignoreincluded, as Ruff's does.--extend-selectand--extend-ignorecombine with the configured values, or layer on a CLI--select. 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, or that name an unknown rule or one that doesn't handle Python. It always runs. HSL901 flags stale ones: unused, redundant with another pragma, or naming a rule that doesn't run on the file. Like Ruff's RUF100, it's opt-in, so a run selecting one rule passes over pragmas for the others. Add extend-select = ["HSL901"] to keep stale suppressions from piling 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 file no enabled rule handles 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
HSL104 compares files with jscpd, which takes a few seconds on a large project, so run it before a push rather than on every commit. Given staged files, it still compares them against the whole configured scope and reports only copies in those files. pre-commit installs the hook in its own environment, so it needs jscpd added there:
- id: house-lint
name: house-lint duplicates
args: [--select, HSL104]
stages: [pre-push]
additional_dependencies: ["jscpd==5.4.1"]
Turn HSL104 on with --select in the pre-push hook, not with extend-select in pyproject.toml: config selection also applies to the commit-stage house-lint hook, whose environment has no jscpd, so every commit would fail with a project-rule-error.
New-code gating
house-lint check --base origin/main
--base <ref> reports only the findings the HEAD commit introduced since its merge-base with <ref>, so a project with a backlog can still fail a PR that adds to it. Both commits are scanned from git with the config committed at HEAD, so uncommitted changes never count. Moved or reformatted findings stay old, and HSL102 reports only files that grew. New-code gating covers how findings are matched, a GitHub Actions example, and how the gate fails.
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 3) 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.
A --base run adds a base object with the ref as given, the base_commit (the merge-base) and head_commit it compared, and preexisting_count, the number of findings it left out as old. Text output prints the same as a base: line before the summary.
Lines and columns are 1-based, columns count UTF-8 bytes, and end_column is exclusive.
Each finding has a related list of the other places the same issue occurs, including ones a pragma suppressed, each with path, line, column, end_line, and end_column. It is empty for findings from single-file rules. Text output appends the same locations to the finding's line, as (also at b.py:10:1, c.py), naming at most three and then and N more.
| 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, syntax, or project-rule 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, or --base couldn't resolve its commits; 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 |
project-rule-error |
A project rule could not run; rule_id names the rule |
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.7.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.7.0.tar.gz | 82.9 kB | With provenance | Details for house_lint-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| house_lint-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for house_lint-0.7.0-py3-none-any.whl |
Total release size: 180.8 kB
Release files / house_lint-0.7.0.tar.gz
| Download URL | house_lint-0.7.0.tar.gz |
|---|---|
| Size | 82.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86a2e6e5e955e4d483526b6589149f0d75e6bf3c14a9b6bb3423d97d430516b2
|
|
BLAKE2b-256 checksum How to use checksums |
12c2d31cf931aaa21ad9ef5cfb186f47249933ddc81b9e5777e9ae13c602c1f1
|
| 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 15, 2026.
Transparency logRelease files / house_lint-0.7.0-py3-none-any.whl
| Download URL | house_lint-0.7.0-py3-none-any.whl |
|---|---|
| Size | 98.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
061ece4aa5f79c3cddabbb28ccd619716ae7001dd3441a3c7c48b497251e3e56
|
|
BLAKE2b-256 checksum How to use checksums |
394e94156e22149366a7aaf7bed6fa8e7f67da437d098f7704592b4fdb4363b9
|
| 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 15, 2026.
Transparency logSecurity for house-lint 0.7.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.7.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 15, 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.