safelint 1.7.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

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

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

Claude Code skill (one-line install)

pip install safelint
safelint skill install

After restarting Claude Code, ask things like "run safelint", "lint my changes with safelint", or "do a Power-of-Ten review on src/api/auth.py". The skill invokes safelint with structured output, groups violations by file, and offers to walk through fixes. Use --project to install only for the current project, --symlink for skill-development workflows, or --force to re-install after upgrades. See src/safelint/skill_files/README.md for the full reference.

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.

---

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.