shelkesays/safelint — drift 5.9/10

5.9/10

Notable drift

vs https://shelkesays.github.io/safelint/

The documentation and code API surface are generally well-aligned. The key exports, function signatures, and class names match across both. However, there are a few notable gaps where important APIs are undocumented or where documentation references functionality that isn't clearly exposed.

0 high3 medium3 low

Open issue with all findings ↗

Files analyzed

API symbols

Doc pages

41.0s

Analyzed in

12 source files inspected · claude-haiku-4-5-20251001 · Jun 1, 2026

6 mismatches found

Undocumented languages module API exports

src/safelint/languages/__init__.py

medium

In the code

def get_language_for_file(filepath: str) -> LanguageDefinition | None
def supported_extensions() -> frozenset[str]
def unavailable_extensions() -> dict[str, str]
def install_hint_for(extension: str) -> str | None
def extra_name_for(extension: str) -> str | None

In the docs

(not documented)

The safelint.languages module exports five important public functions for querying language availability and configuration (get_language_for_file, supported_extensions, unavailable_extensions, install_hint_for, extra_name_for), but these are never mentioned in the public documentation. Developers extending SafeLint or writing integrations would need to discover these through source code inspection.

Suggested fix

Add a new 'Language API' reference section to the documentation, or augment the existing language pages with a 'Programmatic API' subsection documenting these functions, their signatures, return types, and use cases (e.g., 'Use get_language_for_file(path) to detect the language of a source file').

Undocumented rule registration API

src/safelint/rules/__init__.py

medium

In the code

ALL_RULES: list[type[BaseRule]]
RULE_BY_NAME: dict[str, type[BaseRule]]

In the docs

(not documented)

The safelint.rules module exports ALL_RULES and RULE_BY_NAME, which are critical for programmatic rule introspection and custom rule tooling. These are completely undocumented, so tool authors building on SafeLint must reverse-engineer the API from source code.

Suggested fix

Document the rules module API in a 'Contributing' or 'API Reference' section. Include: (1) the structure of ALL_RULES and RULE_BY_NAME, (2) how to iterate over rules programmatically, (3) examples of accessing rule metadata (name, severity, language applicability).

Undocumented TaintTracker classes and dataflow analysis API

src/safelint/analysis/dataflow.py

medium

In the code

class TaintTracker:
  def __init__( self, params: set[str], sinks: frozenset[str], sanitizers: frozenset[str], sources: frozenset[str], *, assume_taint_preserving: bool = True, ) -> None
  def visit(self, root: tree_sitter.Node) -> None

class JavaTaintTracker:
  def __init__( self, params: set[str], sinks: frozenset[str], sanitizers: frozenset[str], sources: frozenset[str], *, assume_taint_preserving: bool = True, ) -> None
  def visit(self, root: tree_sitter.Node) -> None

class JsTaintTracker:
  def __init__( self, params: set[str], sinks: frozenset[str], sanitizers: frozenset[str], sources: frozenset[str], *, assume_taint_preserving: bool = True, ) -> None
  def visit(self, root: tree_sitter.Node) -> None

In the docs

(not documented)

The safelint.analysis.dataflow module exports three language-specific TaintTracker classes (TaintTracker, JavaTaintTracker, JsTaintTracker) that are fundamental to SAFE801 (tainted_sink) analysis. These classes are never documented or mentioned in any public documentation, making it impossible for users to understand or extend the taint tracking system without reading source code.

Suggested fix

Add a 'Dataflow Analysis' or 'Taint Tracking API' section to the Contributing guide or API reference documenting the TaintTracker classes, their constructor parameters (params, sinks, sanitizers, sources, assume_taint_preserving), the visit() method, and examples of how to instantiate and use them for custom rule development.

Undocumented cache and fingerprint API

src/safelint/core/_cache.py

low

In the code

def compute_engine_fingerprint( safelint_version: str, active_rules: Iterable[tuple[str, str, str, dict[str, Any]]], per_file_ignores: Iterable[tuple[str, Iterable[str], Iterable[str]]] = (), engine_internal_ignored: Iterable[str] = (), ) -> str

def compute_file_key(source: bytes, engine_fingerprint: str, filepath: str) -> str

class LintCache:
  def __init__(self, cache_dir: Path | None) -> None
  def get(self, key: str) -> tuple[list[Violation], list[Violation]] | None
  def put(self, key: str, violations: list[Violation], suppressed: list[Violation]) -> None

In the docs

(not documented)

The safelint.core._cache module exports the cache API (compute_engine_fingerprint, compute_file_key, LintCache class), which is essential for integrations that need to replicate SafeLint's caching logic or manage the cache independently. None of this is documented publicly, so integrators must reverse-engineer the cache format from source code.

Suggested fix

Document the cache API in the 'Configuration' or 'Integration' section: explain the purpose of compute_engine_fingerprint (to create a stable hash of the engine state for cache invalidation), compute_file_key (to create a file-specific cache key), and LintCache (to manage on-disk cache storage). Include the cache directory location (.safelint_cache/) and cache key format so integrators can work with it.

Undocumented diagnostic output API

src/safelint/core/_diagnostics.py

low

In the code

def print_warning(message: str) -> None

def print_error(message: str) -> None

In the docs

(not documented)

The safelint.core._diagnostics module exports print_warning and print_error functions for emitting diagnostic messages to stderr. These are used throughout the codebase but are not documented, making it unclear to custom rule authors how to emit warnings or errors in the standard SafeLint format.

Suggested fix

Document these functions in the Contributing guide under 'Custom Rules' or 'API Reference', explaining their purpose (emit formatted warnings/errors to stderr), parameter (message string), and usage in custom rule implementations with examples.

Undocumented validator and config resolution API

src/safelint/core/_validators.py

low

In the code

def resolve_lang_config_key(base_key: str, lang_name: str) -> str

def get_per_language_config( rule_config: dict[str, Any], base_key: str, lang_name: str, default: Any = None, ) -> Any

def resolve_lang_config_lookup( rule_config: dict[str, Any], base_key: str, lang_name: str, default: Any = None, ) -> tuple[Any, str]

In the docs

(not documented)

The safelint.core._validators module exports three functions for resolving per-language rule configuration, which is critical for custom rule development. These are completely undocumented, forcing rule authors to reverse-engineer the config resolution logic from source code.

Suggested fix

Document the config resolution API in the Contributing guide under 'Custom Rules': explain resolve_lang_config_key (construct a language-specific config key like 'io_functions_java'), get_per_language_config (retrieve and apply defaults for a language), and resolve_lang_config_lookup (resolve a config value and return its source key). Include examples showing how custom rules should use these functions.

Re-analyze →Check a different repo