sergey-lint 0.1.1__tar.gz

sergey_lint-0.1.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: sergey-lint
+Version: 0.1.1
+Summary: Add your description here
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pygls>=2.0.1
+Requires-Dist: typer>=0.24.1
+
+# sergey
+
+A Python linter with opinionated rules about import style, naming, and code structure. Runs as a CLI tool or as an LSP server for editor integration.
+
+The primary intent of Sergey is to enforce my personal stylistic rules upon agentic code.
+However, you may also find these useful in standard development. Simultaneously, it is a testing
+space for me for agentic coding. 
+
+## Installation
+
+```bash
+uv add sergey
+```
+
+## Usage
+
+### CLI
+
+```bash
+sergey check path/to/file.py     # check a single file
+sergey check src/ tests/         # check directories (recursive)
+sergey check .                   # check the whole project
+```
+
+Exits with code `0` if no violations are found, `1` if any are found.
+
+### LSP server
+
+```bash
+sergey serve
+```
+
+Communicates over stdio using the Language Server Protocol. Configure your editor to launch this command as a language server for Python files.
+
+## Rules
+
+### Imports
+
+| Rule       | Description                                                                                                                                                                                            |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **IMP001** | `from module import name` is disallowed when `name` is not itself a submodule. Use `import module` and reference `module.name` at call sites. Typing modules, `__future__`, and `collections.abc` are exempt (see IMP002 and IMP004). |
+| **IMP002** | `import typing` and `import typing_extensions` are disallowed. Use `from typing import X` and `from typing_extensions import X` to import names directly.                                                                             |
+| **IMP003** | Dotted plain imports (`import os.path`) are disallowed. Use `from os import path` instead. `collections.abc` is exempt (see IMP004).                                                                                                  |
+| **IMP004** | `import collections.abc` is disallowed. Use `from collections.abc import X` to import names directly.                                                                                                                                 |
+
+The four rules together enforce a consistent import style: every name you use is either a bare module you imported at the top level, or a submodule you accessed via `from package import submodule`.
+
+### Naming
+
+| Rule       | Description                                                                                                                                                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **NAM001** | Functions annotated `-> bool` must start with a predicate prefix: `is_`, `has_`, `can_`, `should_`, `will_`, `did_`, or `was_`. Dunder methods are exempt. Leading underscores on private helpers are ignored (`_is_valid` passes). |
+| **NAM002** | Single-character variable names are disallowed in assignments, for-loops, comprehensions, with-statements, and walrus expressions. The conventional throwaway `_` is exempt.                                                        |
+| **NAM003** | Single-character function and method parameter names are disallowed. Covers positional-only, regular, and keyword-only parameters. `_`, `*args`, and `**kwargs` are exempt. Lambda parameters are not checked.                      |
+
+### Documentation
+
+| Rule       | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **DOC001** | Functions that contain explicit `raise` statements must include a `Raises` section in their docstring. Bare re-raises (`raise` with no argument) are exempt. Raises inside nested functions or classes belong to those scopes and are not counted against the outer function. Functions with no docstring are not checked. Both Google style (`Raises:`) and NumPy style (`Raises` / `------`) are accepted. |
+
+### Pydantic
+
+| Rule       | Description                                                                                                                                                                                                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **PDT001** | Every `BaseModel` subclass must have `model_config = ConfigDict(frozen=...)` with `frozen` explicitly set. This forces a deliberate decision about mutability. Both `frozen=True` and `frozen=False` are accepted; omitting `frozen` or omitting `model_config` entirely is flagged. |
+| **PDT002** | Frozen `BaseModel` subclasses (`frozen=True`) must not have fields annotated with mutable types such as `list`, `dict`, `set`, `deque`, etc. Use immutable alternatives (`tuple`, `frozenset`, …) instead. The check recurses into generic parameters and union syntax, so `Optional[list[str]]` and `str \| list[int]` are both caught. `ClassVar` annotations are exempt. |
+
+### Structure
+
+| Rule       | Description                                                                                                                                                                                                                                                                                                          |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **STR002** | Control-flow blocks nested deeper than 4 levels are flagged. Counted constructs: `if`/`elif`/`else`, `for`, `while`, `with`, `try`, `match`. `elif` branches count at the same depth as their leading `if`. Function, class, and lambda definitions reset the counter, so nested functions are judged independently. |
+| **STR003** | `try` bodies containing more than 4 statements are flagged. Statements are counted recursively (an `if` with branches contributes 1 plus all contained statements). Only the `try:` body is counted — `except` and `finally` blocks are not subject to this rule. Nested functions and classes reset the count. |
+| **STR004** | List and set literals inside functions that are never mutated and are not part of the function output (`return`/`yield`) should use immutable alternatives: `tuple` instead of `[]` and `frozenset` instead of `{}`. Only plain literals are checked; constructor calls and comprehensions are not covered. |
+
+## Suppression
+
+### Suppress a single line
+
+```python
+x = some_function()  # sergey: noqa
+x = some_function()  # sergey: noqa: NAM002
+x = some_function()  # sergey: noqa: NAM002, IMP001
+```
+
+### Suppress an entire file
+
+Place this comment anywhere in the file (position does not matter):
+
+```python
+# sergey: disable-file
+# sergey: disable-file: IMP001
+# sergey: disable-file: IMP001, IMP002
+```
+
+## Development
+
+```bash
+uv run ruff check .        # lint
+uv run ruff format .       # format
+uv run ty check            # type check
+uv run pytest              # run tests
+uv run sergey check .      # run sergey on itself
+```
+
+### Adding a rule
+
+1. Create or extend a module in `sergey/rules/` with a class that subclasses `base.Rule` and implements `check(tree, source) -> list[Diagnostic]`.
+2. Register the rule in `sergey/rules/__init__.py` by adding an instance to `ALL_RULES`.
+3. Add tests in `tests/rules/`.
+
+Rule IDs follow the pattern `CAT###` where `CAT` is a short category prefix (`IMP`, `NAM`, `STR`, …) and `###` is a three-digit number.

sergey_lint-0.1.1/README.md

@@ -0,0 +1,113 @@
+# sergey
+
+A Python linter with opinionated rules about import style, naming, and code structure. Runs as a CLI tool or as an LSP server for editor integration.
+
+The primary intent of Sergey is to enforce my personal stylistic rules upon agentic code.
+However, you may also find these useful in standard development. Simultaneously, it is a testing
+space for me for agentic coding. 
+
+## Installation
+
+```bash
+uv add sergey
+```
+
+## Usage
+
+### CLI
+
+```bash
+sergey check path/to/file.py     # check a single file
+sergey check src/ tests/         # check directories (recursive)
+sergey check .                   # check the whole project
+```
+
+Exits with code `0` if no violations are found, `1` if any are found.
+
+### LSP server
+
+```bash
+sergey serve
+```
+
+Communicates over stdio using the Language Server Protocol. Configure your editor to launch this command as a language server for Python files.
+
+## Rules
+
+### Imports
+
+| Rule       | Description                                                                                                                                                                                            |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **IMP001** | `from module import name` is disallowed when `name` is not itself a submodule. Use `import module` and reference `module.name` at call sites. Typing modules, `__future__`, and `collections.abc` are exempt (see IMP002 and IMP004). |
+| **IMP002** | `import typing` and `import typing_extensions` are disallowed. Use `from typing import X` and `from typing_extensions import X` to import names directly.                                                                             |
+| **IMP003** | Dotted plain imports (`import os.path`) are disallowed. Use `from os import path` instead. `collections.abc` is exempt (see IMP004).                                                                                                  |
+| **IMP004** | `import collections.abc` is disallowed. Use `from collections.abc import X` to import names directly.                                                                                                                                 |
+
+The four rules together enforce a consistent import style: every name you use is either a bare module you imported at the top level, or a submodule you accessed via `from package import submodule`.
+
+### Naming
+
+| Rule       | Description                                                                                                                                                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **NAM001** | Functions annotated `-> bool` must start with a predicate prefix: `is_`, `has_`, `can_`, `should_`, `will_`, `did_`, or `was_`. Dunder methods are exempt. Leading underscores on private helpers are ignored (`_is_valid` passes). |
+| **NAM002** | Single-character variable names are disallowed in assignments, for-loops, comprehensions, with-statements, and walrus expressions. The conventional throwaway `_` is exempt.                                                        |
+| **NAM003** | Single-character function and method parameter names are disallowed. Covers positional-only, regular, and keyword-only parameters. `_`, `*args`, and `**kwargs` are exempt. Lambda parameters are not checked.                      |
+
+### Documentation
+
+| Rule       | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **DOC001** | Functions that contain explicit `raise` statements must include a `Raises` section in their docstring. Bare re-raises (`raise` with no argument) are exempt. Raises inside nested functions or classes belong to those scopes and are not counted against the outer function. Functions with no docstring are not checked. Both Google style (`Raises:`) and NumPy style (`Raises` / `------`) are accepted. |
+
+### Pydantic
+
+| Rule       | Description                                                                                                                                                                                                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **PDT001** | Every `BaseModel` subclass must have `model_config = ConfigDict(frozen=...)` with `frozen` explicitly set. This forces a deliberate decision about mutability. Both `frozen=True` and `frozen=False` are accepted; omitting `frozen` or omitting `model_config` entirely is flagged. |
+| **PDT002** | Frozen `BaseModel` subclasses (`frozen=True`) must not have fields annotated with mutable types such as `list`, `dict`, `set`, `deque`, etc. Use immutable alternatives (`tuple`, `frozenset`, …) instead. The check recurses into generic parameters and union syntax, so `Optional[list[str]]` and `str \| list[int]` are both caught. `ClassVar` annotations are exempt. |
+
+### Structure
+
+| Rule       | Description                                                                                                                                                                                                                                                                                                          |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **STR002** | Control-flow blocks nested deeper than 4 levels are flagged. Counted constructs: `if`/`elif`/`else`, `for`, `while`, `with`, `try`, `match`. `elif` branches count at the same depth as their leading `if`. Function, class, and lambda definitions reset the counter, so nested functions are judged independently. |
+| **STR003** | `try` bodies containing more than 4 statements are flagged. Statements are counted recursively (an `if` with branches contributes 1 plus all contained statements). Only the `try:` body is counted — `except` and `finally` blocks are not subject to this rule. Nested functions and classes reset the count. |
+| **STR004** | List and set literals inside functions that are never mutated and are not part of the function output (`return`/`yield`) should use immutable alternatives: `tuple` instead of `[]` and `frozenset` instead of `{}`. Only plain literals are checked; constructor calls and comprehensions are not covered. |
+
+## Suppression
+
+### Suppress a single line
+
+```python
+x = some_function()  # sergey: noqa
+x = some_function()  # sergey: noqa: NAM002
+x = some_function()  # sergey: noqa: NAM002, IMP001
+```
+
+### Suppress an entire file
+
+Place this comment anywhere in the file (position does not matter):
+
+```python
+# sergey: disable-file
+# sergey: disable-file: IMP001
+# sergey: disable-file: IMP001, IMP002
+```
+
+## Development
+
+```bash
+uv run ruff check .        # lint
+uv run ruff format .       # format
+uv run ty check            # type check
+uv run pytest              # run tests
+uv run sergey check .      # run sergey on itself
+```
+
+### Adding a rule
+
+1. Create or extend a module in `sergey/rules/` with a class that subclasses `base.Rule` and implements `check(tree, source) -> list[Diagnostic]`.
+2. Register the rule in `sergey/rules/__init__.py` by adding an instance to `ALL_RULES`.
+3. Add tests in `tests/rules/`.
+
+Rule IDs follow the pattern `CAT###` where `CAT` is a short category prefix (`IMP`, `NAM`, `STR`, …) and `###` is a three-digit number.

sergey_lint-0.1.1/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "sergey-lint"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pygls>=2.0.1",
+    "typer>=0.24.1",
+]
+
+[project.scripts]
+sergey = "sergey.__main__:main"
+
+[tool.uv]
+package = true
+
+[tool.setuptools.packages.find]
+include = ["sergey*"]
+
+[dependency-groups]
+dev = [
+    "prek>=0.3.3",
+    "pytest>=9.0.2",
+    "ruff>=0.15.2",
+    "ty>=0.0.18",
+]
+
+[tool.ruff.lint]
+preview = false
+select = ["ALL"]
+ignore = [
+    "PYI063", # Preview rule not correctly ignored.
+    "SIM300", # Can cause mypy issues in SQLAlchemy where statements.
+    # Recommended ignores by Astral https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules)
+    "W191",   # Tab indentation
+    "E111",   # Indentation with invalid multiple
+    "E114",   # Indentation with invalid multiple comment
+    "E117",   # Over indented
+    "D206",   # Docstring tab indentation
+    "D300",   # Triple single quotes
+    "Q000",   # Bad quotes inline string
+    "Q001",   # Bad quotes multiline string
+    "Q002",   # Bad quotes docstring
+    "Q003",   # Avoidable escaped quote
+    "COM812", # Missing trailing comma
+    "COM819", # Prohibited trailing comma
+    "ISC002", # Multi-line implicit string concatenation
+]
+fixable = ["ALL"]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",    # asserts should be used in pytest
+    "SLF001",  # accessing private members in tests is fine
+    "INP001",  # tests should not be a module
+    "ARG001",  # tests can have unused arguments (fixtures with side-effects)
+    "D1",      # docstrings not required on test classes/methods
+    "D2",      # docstring formatting rules not relevant in tests
+    "PLR2004", # magic values in assertions are fine in tests
+]
+"sergey/rules/*.py" = [
+    "ARG002", # `source` is part of the Rule.check() interface; not all rules use it
+]
+".claude/hooks/*.py" = [
+    "S603",  # subprocess inputs are controlled (file paths from Claude Code)
+    "S607",  # partial path for `uv` is intentional
+]
+"local/**/*" = ["ALL"]
+
+[tool.ruff.format]
+preview = false
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"

sergey_lint-0.1.1/sergey/__init__.py

@@ -0,0 +1 @@
+"""sergey: an opinionated Python LSP for LLM agent loops."""

sergey_lint-0.1.1/sergey/__main__.py

@@ -0,0 +1,188 @@
+"""Entry point: sergey [check <path>... | serve]."""
+
+import pathlib
+from typing import Annotated, Final
+
+import typer
+
+from sergey.rules import base as rules_base
+
+app = typer.Typer()
+
+
+def _apply_fixes(source: str, diagnostics: list[rules_base.Diagnostic]) -> str:
+    """Return *source* with all fixable diagnostics applied.
+
+    Fixes are applied from bottom to top so that earlier offsets remain valid
+    after each replacement.  When multiple diagnostics share the same range
+    (e.g. two dotted aliases on one import statement) only the first fix
+    encountered is applied — they are identical by construction.
+    """
+    # Deduplicate by range; preserve insertion order (already sorted top→bottom).
+    seen_ranges: set[tuple[int, int, int, int]] = set()
+    unique: list[rules_base.Diagnostic] = []
+    for diag in diagnostics:
+        if diag.fix is None:
+            continue
+        key = (diag.line, diag.col, diag.end_line, diag.end_col)
+        if key not in seen_ranges:
+            seen_ranges.add(key)
+            unique.append(diag)
+
+    # Apply bottom→top to keep earlier positions stable.
+    for diag in reversed(unique):
+        lines = source.splitlines(keepends=True)
+        # Build character offsets for start and end of the diagnostic range.
+        start = sum(len(lines[idx]) for idx in range(diag.line - 1)) + diag.col
+        end = sum(len(lines[idx]) for idx in range(diag.end_line - 1)) + diag.end_col
+        if diag.fix is None:  # pragma: no cover
+            continue
+        source = source[:start] + diag.fix.replacement + source[end:]
+    return source
+
+
+# Directories that are never interesting to analyse.
+_SKIP_DIRS: Final[frozenset[str]] = frozenset(
+    {".venv", "venv", "__pycache__", ".git", "node_modules", "build", "dist", ".tox"}
+)
+
+
+def _collect_python_files(root: pathlib.Path) -> list[pathlib.Path]:
+    """Recursively find .py files under root, skipping non-source directories."""
+    return sorted(
+        py_file
+        for py_file in root.rglob("*.py")
+        if not any(part in _SKIP_DIRS for part in py_file.parts)
+    )
+
+
+def _git_diff_python_files() -> list[pathlib.Path]:
+    """Return .py files changed relative to HEAD in the current git repository.
+
+    Returns an empty list when git is unavailable or the directory is not a
+    git repository.
+    """
+    import subprocess  # noqa: PLC0415
+
+    try:
+        root_proc = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        diff_proc = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=ACMR", "HEAD"],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return []
+    if root_proc.returncode != 0 or diff_proc.returncode != 0:
+        return []
+    git_root = pathlib.Path(root_proc.stdout.strip())
+    return [
+        git_root / line
+        for line in diff_proc.stdout.splitlines()
+        if line.endswith(".py")
+    ]
+
+
+def _resolve_files(
+    paths: list[pathlib.Path] | None,
+    *,
+    diff: bool,
+) -> list[pathlib.Path]:
+    """Expand paths and optionally the git diff into a deduplicated .py file list."""
+    candidates: list[pathlib.Path] = []
+    if diff:
+        candidates.extend(_git_diff_python_files())
+    for raw_path in paths or []:
+        if raw_path.is_dir():
+            candidates.extend(_collect_python_files(raw_path))
+        else:
+            candidates.append(raw_path)
+    seen: set[pathlib.Path] = set()
+    unique: list[pathlib.Path] = []
+    for file_path in candidates:
+        resolved = file_path.resolve()
+        if resolved not in seen:
+            seen.add(resolved)
+            unique.append(file_path)
+    return unique
+
+
+@app.command(no_args_is_help=True)
+def check(
+    paths: Annotated[
+        list[pathlib.Path] | None,
+        typer.Argument(help="Files or directories to check."),
+    ] = None,
+    diff: Annotated[  # noqa: FBT002
+        bool,
+        typer.Option("--diff", help="Check .py files changed in the current git diff."),
+    ] = False,
+    fix: Annotated[  # noqa: FBT002
+        bool,
+        typer.Option("--fix", help="Apply auto-fixes for fixable violations."),
+    ] = False,
+) -> None:
+    """Check one or more files/directories for rule violations.
+
+    Raises:
+        typer.Exit: With code 1 if any unfixed violations remain.
+    """
+    from sergey import analyzer as sergey_analyzer  # noqa: PLC0415
+    from sergey import config as sergey_config  # noqa: PLC0415
+    from sergey import rules  # noqa: PLC0415
+
+    python_files = _resolve_files(paths, diff=diff)
+    cfg = sergey_config.load_config()
+    active_rules = sergey_config.filter_rules(rules.ALL_RULES, cfg)
+    active_rules = sergey_config.configure_rules(active_rules, cfg)
+    analyzer = sergey_analyzer.Analyzer(rules=active_rules)
+    found_any = False
+
+    for file_path in python_files:
+        try:
+            source = file_path.read_text()
+        except OSError as e:
+            typer.echo(f"error: {e}", err=True)
+            continue
+
+        diagnostics = analyzer.analyze(source)
+
+        if fix:
+            fixed_source = _apply_fixes(source, diagnostics)
+            if fixed_source != source:
+                file_path.write_text(fixed_source)
+                # Re-analyze to report any remaining violations.
+                diagnostics = analyzer.analyze(fixed_source)
+
+        for diag in diagnostics:
+            typer.echo(
+                f"{file_path}:{diag.line}:{diag.col}: {diag.rule_id} {diag.message}"
+            )
+        if diagnostics:
+            found_any = True
+
+    if found_any:
+        raise typer.Exit(code=1)
+
+
+@app.command(no_args_is_help=True)
+def serve() -> None:
+    """Run the LSP server over stdio."""
+    from sergey import server  # noqa: PLC0415
+
+    server.start()
+
+
+def main() -> None:
+    """Dispatch to CLI check mode or LSP server mode."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

sergey_lint-0.1.1/sergey/analyzer.py

@@ -0,0 +1,111 @@
+"""Orchestrates rule execution against a parsed AST."""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from sergey.rules import base
+
+# Matches:  # sergey: noqa          (suppress all rules on this line)
+#           # sergey: noqa: IMP001  (suppress specific rules on this line)
+_LINE_NOQA_PAT: Final = re.compile(
+    r"#\s*sergey:\s*noqa(?::\s*([A-Z0-9][A-Z0-9,\s]*))?",
+    re.IGNORECASE,
+)
+
+# Matches:  # sergey: disable-file           (suppress all rules in this file)
+#           # sergey: disable-file: IMP001   (suppress specific rules in this file)
+_FILE_DISABLE_PAT: Final = re.compile(
+    r"#\s*sergey:\s*disable-file(?::\s*([A-Z0-9][A-Z0-9,\s]*))?",
+    re.IGNORECASE,
+)
+
+
+def _rule_ids(raw: str | None) -> frozenset[str] | None:
+    """Parse rule IDs from a suppression comment capture group.
+
+    Returns None to indicate all rules are suppressed, or a frozenset of
+    specific uppercased rule IDs.
+    """
+    if not raw or not raw.strip():
+        return None
+    ids = frozenset(part.strip().upper() for part in raw.split(",") if part.strip())
+    return ids or None
+
+
+def _is_covered(suppressed: frozenset[str] | None, rule_id: str) -> bool:
+    """Return True if rule_id falls within the suppression set.
+
+    None means all rules are suppressed.
+    """
+    return suppressed is None or rule_id in suppressed
+
+
+def _apply_suppressions(
+    diagnostics: list[base.Diagnostic],
+    source: str,
+) -> list[base.Diagnostic]:
+    """Remove diagnostics covered by inline sergey suppression comments."""
+    lines = source.splitlines()
+
+    file_sup_active = False
+    file_sup_rules: frozenset[str] | None = None
+    line_sups: dict[int, frozenset[str] | None] = {}
+
+    for lineno, line_text in enumerate(lines, start=1):
+        file_match = _FILE_DISABLE_PAT.search(line_text)
+        if file_match:
+            file_sup_active = True
+            file_sup_rules = _rule_ids(file_match.group(1))
+
+        line_match = _LINE_NOQA_PAT.search(line_text)
+        if line_match:
+            line_sups[lineno] = _rule_ids(line_match.group(1))
+
+    return [
+        diag
+        for diag in diagnostics
+        if not (
+            (file_sup_active and _is_covered(file_sup_rules, diag.rule_id))
+            or (
+                diag.line in line_sups
+                and _is_covered(line_sups[diag.line], diag.rule_id)
+            )
+        )
+    ]
+
+
+class Analyzer:
+    """Runs all registered rules against a source file."""
+
+    def __init__(self, rules: list[base.Rule]) -> None:
+        """Initialize with a list of rule instances.
+
+        Args:
+            rules: Rule instances to run on every analysis request.
+        """
+        self.rules = rules
+
+    def analyze(self, source: str) -> list[base.Diagnostic]:
+        """Parse source, run all rules, and apply inline suppressions.
+
+        Args:
+            source: Raw Python source code to analyze.
+
+        Returns:
+            Diagnostics sorted by (line, col) with suppressed entries removed.
+            Returns an empty list if the source cannot be parsed.
+        """
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return []
+
+        diagnostics = sorted(
+            [diag for rule in self.rules for diag in rule.check(tree, source)],
+            key=lambda diag: (diag.line, diag.col),
+        )
+        return _apply_suppressions(diagnostics, source)