Safelint

safelint skill

You are running the safelint static-analysis CLI on behalf of the user. safelint enforces Holzmann's "Power of Ten" safety rules adapted from C/C++ aerospace conventions to modern languages: function length, nesting depth, cyclomatic complexity, error-handling discipline, hidden side effects, dataflow taint, and similar. The same rule set applies across every language safelint supports; only the parser and language-specific node types differ.

Follow the steps below in order.

Step 1: Verify safelint is installed

Run safelint --version via Bash. This is portable across macOS, Linux, and Windows shells and returns non-zero whenever safelint isn't on PATH. If you specifically need a "is the binary findable?" check without invoking it, fall back to python -c "import shutil, sys; sys.exit(0 if shutil.which('safelint') else 1)".

If either check returns non-zero (or the shell reports "command not found" / "is not recognized"):

• safelint is a Python package regardless of the language being linted, but v2.0.0+ ships language grammars as opt-in extras, so the install command needs a [<lang>] suffix matching the project's language(s). Glance at the file extensions in the project tree, then suggest the right one:

  Project contains	Install command
  .py / .pyw	uv add 'safelint[python]' or pip install 'safelint[python]'
  .js / .mjs / .cjs	uv add 'safelint[javascript]' or pip install 'safelint[javascript]'
  .ts / .tsx / .as	uv add 'safelint[typescript]' or pip install 'safelint[typescript]' (bundles JS grammar too)
  .java	uv add 'safelint[java]' or pip install 'safelint[java]' (Spring Boot via [tool.safelint.java] framework = "spring-boot", see languages/java.md)
  .rs	uv add 'safelint[rust]' or pip install 'safelint[rust]' (Rust-specific rules and Holzmann-inspired additions; see languages/rust.md)
  Multiple languages	Compose, e.g. pip install 'safelint[python,javascript]'
  Unsure / kitchen-sink	pip install 'safelint[all]' (covers every supported language)

  Plain pip install safelint (no extra) installs only the engine and is rarely what the user wants. On first run safelint emits an install hint pointing them at the right extra and exits with code 2.

• If safelint is already installed but exits non-zero with safelint: error: no files linted … on stderr, the grammar extra is missing. That error fires in every output mode (JSON / SARIF included) and is the reliable signal. Pretty-mode runs additionally print one safelint: warning: skipping .X files … line per missing grammar as context; JSON / SARIF runs, and hook-mode runs where every file is skipped, suppress that warning. Re-install with the right [<lang>] extra and retry.

• After running safelint skill install, safelint also auto-detects the project's language(s) and emits a final safelint: warning: Detected source files for N language(s) ... Run: pip install 'safelint[<a,b>]' line if any grammars are missing. The composed install command in that line is the one-shot fix for multi-language projects; run it as-is.

• For pre-commit users: the same extra must go into additional_dependencies in .pre-commit-config.yaml, e.g. additional_dependencies: ['safelint[python]']. Without it, the pre-commit hook also exits 2 and is reported as Failed (red), so there's no silent-pass.

• Stop. Do not proceed until they install the right extra.

Step 2: Identify the language(s) involved

Look at the project files in cwd to figure out which languages safelint can lint here. The current registry:

(More languages will land over time. To check the live list, run python -c "from safelint.languages import supported_extensions; print(sorted(supported_extensions()))".)

If the user's project has files matching one or more registered languages, proceed. If safelint doesn't yet support the language they're working in (e.g. they have only .go files), tell them so plainly; don't run safelint just to report "0 files checked".

For deeper, language-specific guidance (install nuance, idiomatic fixes, language-specific rule notes), read the matching languages/<lang>.md file from the bundled skill directory. Locate it with safelint skill path (prints the on-disk root); the addendums sit at <that path>/languages/<lang>.md. Skip the read if the user's request doesn't need that depth (e.g. a simple "run safelint and show me the count").

Step 3: Decide what to lint

If the user mentions CI strictness, also pass --mode ci (treats warnings as blocking) or --fail-on warning.

Step 4: Run safelint with structured output

Always use --format json so you can parse the result reliably. safelint walks the target tree and lints every file whose extension matches a registered language; you don't need to filter by language yourself.

safelint check <target> --format json [--all-files]

Notes:

• Exit 0 = no blocking violations; exit 1 = at least one blocking violation. The JSON document is on stdout in both cases; keep parsing it.
• Exit 2 = setup error: safelint linted zero files because every candidate's grammar isn't installed (silent-failure guard). The stderr will name the extra to install (e.g. add 'safelint[typescript]' to additional_dependencies … under pre-commit, or install with: pip install 'safelint[typescript]' direct). The JSON on stdout will look clean (zero violations), so do not report this as "lint clean"; surface the stderr install hint to the user.
• Stderr may contain config warnings (typo guards, oversize-skip notes). Surface those to the user only if non-empty.
• If safelint itself crashes (bug), say so and include the stderr verbatim.

Step 5: Parse the JSON

The schema is documented in docs/json-schema.md inside the safelint repo. Its shape has been stable since v1.5.0; the rule set has expanded as new languages landed (Java in v2.1.0, Rust in v2.2.0), but the field structure of each violation / summary entry is unchanged. The shape:

{
  "version": "1.x.y",
  "summary": {
    "files_checked": N,
    "violations": N,
    "errors": N,
    "warnings": N,
    "blocking": N,
    "fail_on": "error" | "warning",
    "suppressed": {"total": N, "by_code": {"SAFE501": 3, ...}}
  },
  "violations": [
    {"code": "SAFE201", "rule": "bare_except", "severity": "error",
     "filepath": "src/foo.py", "lineno": 42,
     "end_lineno": 42, "column_start": 5, "column_end": 12,
     "message": "Bare ``except:`` clause - specify the exception type to handle",
     "suggestions": [
       {"description": "Replace `except:` with `except Exception:`",
        "edits": [
          {"start_line": 42, "start_column": 5,
           "end_line": 42, "end_column": 12,
           "replacement": "except Exception:"}
        ]}
     ]}
  ],
  "suppressed": [ /* same shape */ ]
}

Violation objects are language-agnostic. The filepath field tells you which language each violation came from (via extension); use that if you want to group results by language.

The suggestions[] array (added in v1.8.0) is advisory only. Each Suggestion carries a one-line description and zero or more TextEdit entries (half-open [start, end) ranges plus the literal replacement text). Surface them to the user as offered quick-fixes, but never apply them automatically. safelint is a review tool, not a refactoring tool, and the user must confirm every edit. Empty edits arrays are valid: a description-only suggestion is a hint, not a fix recipe.

Step 6: Present results

Order matters: lead with what the user needs first.

1. One-line headline. Examples:

   • Clean run: 12 files checked, no violations. (if zero)
   • Clean run: 12 files checked. 3 violations suppressed (2 SAFE501, 1 SAFE304). (clean but with suppressions)
   • Found 4 errors and 7 warnings across 5 files (1 suppressed). (otherwise)

2. Per-file breakdown (skip files with zero violations). For each file, list violations one per line:

   src/api/auth.py
     SAFE101  L42  Function "verify_token" is 78 lines (max 60)              [function_length]
     SAFE102  L51  Nesting depth is 4 (max 2)                                 [nesting_depth]
     SAFE304  L88  Function "_run_pipeline" calls I/O primitive "open" - ...  [side_effects]
   

   Pad codes / line numbers / messages so columns line up. Don't emit ANSI colour; the user's terminal already renders it via the pretty mode if they want that, so the skill output should be plain.

   If a project has files in multiple languages, group by language first, then by file within each language.

3. Suggested next step. Pick exactly one based on the result:

   • 0 violations → say "All checks passed." and stop. No follow-up.
   • 1–4 violations → "Want me to walk through fixes one at a time?"
   • 5+ violations → "Want me to start with the most common issue (CODE, N occurrences)?"
   • Many function_length / complexity violations clustered in one file → "These look like one large function. Want me to extract some helpers?"

Step 7: When the user asks "why is this flagged?"

Briefly explain the Power-of-Ten rationale (one or two sentences). Reference the rule code and the underlying safety property. Don't lecture; keep it tight.

The rule set is shared across all supported languages. Universal rationale crib sheet:

For language-specific phrasing (e.g. how bare_except translates to catch (Throwable t) in another language) read the relevant languages/<lang>.md addendum; locate it via safelint skill path.

Step 8: Constraints

• Do not auto-fix. Even if confident, ask before editing. The user invoked a review, not a refactor.
• Do not invent violations. Only report what's in the JSON.
• Do not run --all-files on a large repo by default. Git-modified is the default for a reason: it's fast and scoped to current work.
• Respect inline-suppression directives. They appear in suppressed, not violations. Don't suggest removing them; they're intentional.
• Don't assume Python idioms when fixing other languages. For language-specific fix patterns, consult the addendum.
• If the user asks "is my code safe?", answer based on the blocking count combined with the exit code: summary.blocking == 0 AND exit 0 means the run passed under the configured fail_on threshold; summary.blocking == 0 AND exit 2 means zero files were actually linted (silent-failure guard fired), which is not the same as passing. Surface the stderr install hint instead of declaring the code safe.

Adding support for a new language

When safelint adds a new language (TypeScript, Go, Rust, …):

1. Add the language registration in safelint itself (src/safelint/languages/<lang>.py).
2. Add a row to the Step 2 registry table above.
3. Create src/safelint/skill_files/languages/<lang>.md mirroring the existing addendums. The addendum should cover at minimum:
   • Install nuance specific to that ecosystem (if any; safelint stays a Python install for now).
   • File extensions and how to recognise them in this skill's context.
   • Language-specific phrasing for rule rationales (e.g. how bare_except maps to that language's catch-all idiom).
   • Idiomatic fix patterns the skill can suggest when offering to walk through fixes.

Keep the skill core (this file) language-neutral. Per-language detail belongs in the addendum.

Source: shelkesays/safelint — distributed by TomeVault.