Skip to main content

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"]
  • select sets the base selection and ignore removes rules from it. extend-select and extend-ignore add and remove on top of that base.
  • On the command line, --select replaces the configured selection, extend-select and extend-ignore included, as Ruff's does. --extend-select and --extend-ignore combine with the configured values, or layer on a CLI --select. A CLI --ignore is 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
  • ignore covers the statement it sits on. An except clause is its own statement, so its pragma goes on the except line.
  • ignore-next on its own line covers the next statement in the same block, skipping comments and blank lines.
  • ignore-file covers 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.
  • --root fixes the project boundary. Without --config, house-lint looks in the root for house-lint.toml, then .house-lint.toml, then a pyproject.toml with [tool.house-lint].
  • --config names an exact configuration file, and its directory becomes the root unless --root is 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-cache skips reading the cache but still refreshes it.
  • --cache-dir moves 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)

Source distribution for house-lint 0.7.0
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)

Table of built distributions (wheels) for house-lint 0.7.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page