safelint 1.8.0

Engineering safety lint rules and pre-commit integration for modern Python codebases

SafeLint

SafeLint is a configurable static analysis tool that enforces safety-critical coding practices inspired by Gerard J. Holzmann's "Power of Ten" rules at NASA/JPL.

Originally designed for mission-critical systems, these principles apply to any modern Python codebase - and are especially valuable when code is written fast, reviewed quickly, or generated by AI.

SafeLint integrates with pre-commit and CI pipelines to prevent unsafe code from entering your codebase.

Why SafeLint?

Fast-moving codebases - whether written by humans under pressure or generated by AI tools - tend to drift toward the same failure patterns:

• Unbounded loops
• Silent error handling
• Hidden side effects
• Poor resource management

SafeLint catches these early, automatically, regardless of who wrote the code.

Philosophy

"When it really counts, it may be worth going the extra mile and living within stricter limits than may be desirable."

• Gerard J. Holzmann, NASA/JPL

---

Power of Ten - adapted for Python

In 1987, Holzmann wrote ten rules for spacecraft software at NASA/JPL. Nearly four decades later, the same failure patterns appear in every Python codebase. SafeLint is those ten rules, adapted for Python and automated.

#	Holzmann's Rule	SafeLint Rule	Code
1	No complex control flow - no goto, no deep recursion	nesting_depth, complexity	SAFE102, SAFE104
2	All loops must have a fixed upper bound	unbounded_loops	SAFE501
3	No dynamic memory allocation after startup	-	(not applicable to Python)
4	Functions must fit on one printed page	function_length	SAFE101
5	Use at least two assertions per function	missing_assertions	SAFE601
6	Declare variables at the smallest scope	-	(Python handles this)
7	Check the return value of every non-void function	return_value_ignored, bare_except, empty_except	SAFE802, SAFE201, SAFE202
8	Limit preprocessor use	-	(not applicable to Python)
9	Restrict pointer use - no chained indirection	null_dereference	SAFE803
10	Compile with all warnings; use static analysis	SafeLint itself	-

Original paper: spinroot.com/gerard/pdf/P10.pdf

---

Installation

pip install safelint

---

Usage

Discover the CLI surface (ruff-style help and version):

safelint --help              # or: safelint help, safelint -h
safelint help check          # subcommand-specific help
safelint --version           # or: safelint version, safelint -V

Check modified files (default — only files changed since last commit):

safelint check src/

Check all files (full scan, e.g. in CI):

safelint check src/ --all-files

Check specific files (pre-commit style):

safelint src/mymodule.py src/utils.py

Fail on warnings too (useful in CI):

safelint check src/ --all-files --fail-on=warning

Run in CI mode (warnings become blocking):

safelint check src/ --all-files --mode=ci

Ignore specific rules for one run:

safelint check src/ --ignore SAFE203 --ignore side_effects

Machine-readable output for tooling consumers (editors, CI, the Claude Code skill):

safelint check src/ --format=json     # stable JSON schema
safelint check src/ --format=sarif    # SARIF 2.1.0 (GitHub code scanning, etc.)

Lint un-saved buffer contents from stdin (editor mode):

cat my_module.py | safelint --stdin --stdin-filename my_module.py --format=json

--stdin-filename drives language detection by extension and is shown as the violation file path. Combine with --format=json so the editor can parse the result.

Disable the lint-result cache:

safelint check src/ --no-cache       # otherwise: ~instant re-runs on unchanged files

By default safelint memoises rule output keyed on sha256(source + engine config + filepath) in a .safelint_cache/ directory next to your config file (mirroring .pytest_cache). The filepath is folded in so two files with identical contents under different paths get separate entries, and Violation.filepath always reflects the current call. Add .safelint_cache/ to .gitignore.

---

Pre-commit integration

Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/shelkesays/safelint
    rev: v1.8.0  # replace with the latest release tag
    hooks:
      - id: safelint
        args: [--fail-on=error]  # use --fail-on=warning for stricter CI
        files: ^src/

Then install the hooks:

pre-commit install

SafeLint will now run on every git commit and block the commit if it finds errors.

---

What it checks

Code	Rule	What it flags
SAFE101	function_length	Functions longer than 60 lines
SAFE102	nesting_depth	Control flow nested more than 2 levels deep
SAFE103	max_arguments	Functions with more than 7 parameters
SAFE104	complexity	Functions with high cyclomatic complexity
SAFE201	bare_except	except: with no exception type
SAFE202	empty_except	except blocks that do nothing (pass)
SAFE203	logging_on_error	Except blocks that swallow errors silently
SAFE301	global_state	Use of the global keyword inside functions
SAFE302	global_mutation	Writing to global variables inside functions
SAFE303	side_effects_hidden	Pure-looking functions that secretly do I/O
SAFE304	side_effects	Functions that call print, open, etc. without signalling intent
SAFE401	resource_lifecycle	Files or connections opened outside a with block
SAFE501	unbounded_loops	while True loops with no break

Dataflow rules (opt-in, disabled by default):

Code	Rule	What it flags
SAFE801	tainted_sink	User input flowing into eval, exec, subprocess, etc. without sanitization
SAFE802	return_value_ignored	Discarding the return value of calls like subprocess.run or file.write
SAFE803	null_dereference	Chaining methods directly on calls that can return None, e.g. d.get("key").strip()

For opt-in rules (SAFE601, SAFE701, SAFE702) and full configuration options for every rule, see CONFIGURATION.md.

---

Suppressing violations inline

Add a # nosafe comment to suppress a violation on a specific line without changing global config.

Suppress all violations on a line:

result = eval(user_input)  # nosafe

Suppress a specific rule by code:

while True:  # nosafe: SAFE501
    ...

Suppress by rule name:

while True:  # nosafe: unbounded_loops
    ...

Suppress multiple rules at once:

def get_data(conn, q, p1, p2, p3, p4, p5, p6):  # nosafe: SAFE101, SAFE103
    ...

When at least one violation is suppressed, the CLI summary reports a per-code breakdown (e.g. (2 SAFE501, 1 SAFE304 suppressed)) so suppressions remain visible and auditable. Use # nosafe sparingly — it's for line-level exceptions only. For broader suppression use the config-level options:

# pyproject.toml
[tool.safelint]
ignore = ["SAFE203", "side_effects"]          # suppress project-wide

[tool.safelint.per_file_ignores]
"tests/**" = ["SAFE101", "SAFE103"]           # suppress only for matching files

See CONFIGURATION.md — Inline suppression, CONFIGURATION.md — Global ignore list, and CONFIGURATION.md — Per-file ignore list for full reference.

---

Configuration

SafeLint is configured via [tool.safelint] in your pyproject.toml, or a standalone safelint.toml file at your project root. When both exist in the same directory, safelint.toml wins — its values override anything in [tool.safelint] — matching ruff's ruff.toml / pyproject.toml precedence. See CONFIGURATION.md for all options, defaults, and examples.

Highlights:

• Incremental ignore lists — use extend_ignore / extend_per_file_ignores to grow the defaults instead of replacing them (mirrors ruff's extend-select ergonomics).
• --statistics flag — print a per-rule violation-count table at the end of a run (safelint check src/ --statistics).
• SAFE004 unused_suppression — automatically warns about stale # nosafe directives that no longer suppress anything. Disable globally via ignore = ["SAFE004"] if undesired.
• No --fix flag — SafeLint is review-only by design. Editor integrations may surface suggestions as code actions, but every edit is user-confirmed.

Ready-to-copy samples:

• examples/sample.pyproject.toml — [tool.safelint] block for an existing pyproject.toml
• examples/sample.safelint.toml — standalone safelint.toml (no [tool.safelint] wrapper)

---

Editor / agent integrations

AI-client skills (Claude Code, Cursor; more on the way)

pip install safelint
safelint skill install          # auto-detects which AI client(s) you use

The bare command is --client auto under the hood: it scans the current directory for client markers (CLAUDE.md, .cursor/, …), falls back to your home directory, and installs the relevant skill / project rule for every AI client it finds. Multiple clients in the same project? It installs for both.

After restarting the AI client (or reloading its window), ask things like "run safelint", "lint my changes with safelint", or "do a Power-of-Ten review on src/api/auth.py". The skill / rule invokes safelint with structured output, groups violations by file, and offers to walk through fixes.

For explicit control (--client claude / --client cursor), per-client setup, project-vs-user-scope semantics, symlink mode for skill development, and troubleshooting, see AI_CLIENTS.md. To add support for a new AI client (GitHub Copilot, codex, windsurf, antigravity, etc. — the registry is open-ended), follow the contributor walkthrough in ADDING_AN_AI_CLIENT.md.

Other integration points

• Stdin mode — safelint --stdin --stdin-filename PATH --format json lints unsaved buffer contents fed via stdin. Designed for editor extensions (VSCode plugin, custom LSP wrappers).
• JSON / SARIF output — --format json and --format sarif emit stable, machine-readable documents. The JSON schema is documented in docs/JSON_SCHEMA.md. SARIF output is GitHub code-scanning compatible.
• Column-precise positions — every violation carries lineno, end_lineno, column_start, column_end (1-based, half-open). Maps directly to LSP / VSCode Range and SARIF region.endColumn. Synthetic violations (e.g. test_existence) leave column fields null; editors should treat that as "underline the whole line".
• Advisory suggestions — every violation may carry a suggestions array with one-line descriptions and TextEdit ranges. Editor integrations must never apply these automatically — every edit goes through user confirmation. SARIF output uses the spec's native fixes[] block for the same data. SafeLint will never ship a --fix flag.

---

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run the linter on itself
safelint check src/

Releasing to PyPI (Trusted Publishing)

This project publishes to PyPI via GitHub Actions using PyPI Trusted Publishing (OIDC). Do not use local uv publish username/password auth.

One-time setup:

1. In PyPI, open your project → Manage → Publishing → Add a trusted publisher.
2. Use:
   • Owner: shelkesays
   • Repository: safelint
   • Workflow: publish.yml
   • Environment: pypi
3. In GitHub, create an environment named pypi in Settings → Environments.

Release flow:

# 1) bump version in pyproject.toml
# 2) commit and push
git tag vX.Y.Z
git push origin vX.Y.Z

Pushing the version tag triggers .github/workflows/publish.yml, which builds and publishes to PyPI.

---

Contributing

See CONTRIBUTING.md for guidelines on bug reports, adding new rules, and opening pull requests.