notignored-sdk 0.1.4__tar.gz

notignored_sdk-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick DeRobertis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

notignored_sdk-0.1.4/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: notignored-sdk
+Version: 0.1.4
+Summary: Typed Python SDK for notignored: every lint and type-check suppression in a source tree, as records.
+Keywords: lint,noqa,suppression,code-review,sdk
+Author: Nick DeRobertis
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: notignored-cli==0.1.4
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/nickderobertis/notignored
+Project-URL: Repository, https://github.com/nickderobertis/notignored
+Description-Content-Type: text/markdown
+
+# notignored-sdk
+
+Typed Python access to [`notignored`](https://github.com/nickderobertis/notignored):
+every lint and type-check suppression comment in a source tree — `# noqa`,
+`// eslint-disable-next-line`, `#[allow(...)]`, `# type: ignore`, and the rest —
+as frozen records with the tool, the rules, and the stated reason.
+
+The distribution is `notignored-sdk`, the import is `notignored_sdk`, and every
+release depends on the exact `notignored-cli` it was built with, so
+`pip install` brings a binary that speaks the same report contract.
+
+```console
+pip install notignored-sdk
+```
+
+```python
+from notignored_sdk import scan
+
+report = scan(["src"])
+for directive in report.ignores:
+    print(
+        f"{directive.path}:{directive.line} {directive.tool} {directive.rules} — {directive.reason}"
+    )
+```
+
+## The guard: prove nobody silenced a linter to make the gate pass
+
+The case this exists for. A green `just check` means nothing if the way it went
+green was a new `# noqa`, so pin the suppressions a branch is allowed to add and
+fail when it adds one that is not justified:
+
+```python
+from notignored_sdk import scan
+
+
+def test_this_branch_added_no_unjustified_suppression() -> None:
+    """Every suppression this change adds has to say why it is there."""
+    added = scan(diff=True, diff_base="origin/main")
+
+    assert added.errors == (), added.errors
+    unexplained = [d for d in added.ignores if not d.reason]
+    assert not unexplained, "\n".join(
+        f"{d.path}:{d.line} adds `{d.raw}` with no stated reason" for d in unexplained
+    )
+```
+
+`diff=True` reports only the suppressions on lines the change added, using the
+same merge-base semantics as `notignored --diff` — so a suppression that was
+already on `main` is never yours.
+
+## The surface
+
+One entry point, in two forms. `ascan` takes the identical arguments and returns
+the identical report:
+
+```python
+scan(paths=(), *, diff=False, diff_base=None, tools=None, cwd=None, binary=None) -> Report
+await ascan(...)  # the same call, on an event loop
+```
+
+| Argument | What it does |
+| --- | --- |
+| `paths` | Files and/or directories. Directories are walked recursively, honouring `.gitignore`. Empty scans the working directory. |
+| `diff` | Report only the suppressions this change added. |
+| `diff_base` | The git revision `diff` compares against. Without `diff=True` it is a `ValueError`, exactly as the CLI rejects it. |
+| `tools` | Report only these tools (`Tool` members or their names); `None` reports all of them. |
+| `cwd` | Directory to run in. Report paths are relative to it. |
+| `binary` | The `notignored` to run. Defaults to `$NOTIGNORED_BIN`, then to the one on `PATH`. |
+
+The records mirror the CLI's JSON contract exactly, as frozen dataclasses:
+
+```python
+Report(version, ignores, errors)
+IgnoreDirective(tool, scope, rules, reason, path, line, end_line, column, raw, suppressed)
+Suppressed(start_line, end_line)  # end_line is None when the range runs to end-of-file
+ReportError(path, message)
+```
+
+`Tool` and `Scope` are string enums, so `directive.tool == "ruff"` and
+`directive.scope == "next-line"` both work.
+
+A file that could not be read is a `ReportError` in the report, never an
+exception — the CLI exits non-zero for it and the SDK still hands you the report
+that names it, because a tree with an unscannable file is not a clean tree.
+
+## Errors
+
+Everything raised is a `NotignoredError`:
+
+| Error | When |
+| --- | --- |
+| `NotignoredNotFoundError` | No `notignored` binary could be found. The message says how to install one. |
+| `NotignoredSpawnError` | The binary is there but the process could not start. |
+| `NotignoredExitError` | The scan could not run and printed no report; carries `returncode` and the CLI's `stderr`. |
+| `NotignoredContractError` | The output is not the report contract this SDK reads. |
+
+Parsing is strict: an unknown tool, an unknown scope, or a missing field is a
+`NotignoredContractError`, never a silently dropped record. Because the package
+pins its CLI exactly, a supported install cannot hit it.
+
+## Working on it
+
+From the repository root:
+
+```bash
+just bootstrap                             # provisions every project
+just nx run notignored-sdk-python:check    # this project's gate alone
+just check                                 # the whole repo's gate
+```

notignored_sdk-0.1.4/README.md

@@ -0,0 +1,109 @@
+# notignored-sdk
+
+Typed Python access to [`notignored`](https://github.com/nickderobertis/notignored):
+every lint and type-check suppression comment in a source tree — `# noqa`,
+`// eslint-disable-next-line`, `#[allow(...)]`, `# type: ignore`, and the rest —
+as frozen records with the tool, the rules, and the stated reason.
+
+The distribution is `notignored-sdk`, the import is `notignored_sdk`, and every
+release depends on the exact `notignored-cli` it was built with, so
+`pip install` brings a binary that speaks the same report contract.
+
+```console
+pip install notignored-sdk
+```
+
+```python
+from notignored_sdk import scan
+
+report = scan(["src"])
+for directive in report.ignores:
+    print(
+        f"{directive.path}:{directive.line} {directive.tool} {directive.rules} — {directive.reason}"
+    )
+```
+
+## The guard: prove nobody silenced a linter to make the gate pass
+
+The case this exists for. A green `just check` means nothing if the way it went
+green was a new `# noqa`, so pin the suppressions a branch is allowed to add and
+fail when it adds one that is not justified:
+
+```python
+from notignored_sdk import scan
+
+
+def test_this_branch_added_no_unjustified_suppression() -> None:
+    """Every suppression this change adds has to say why it is there."""
+    added = scan(diff=True, diff_base="origin/main")
+
+    assert added.errors == (), added.errors
+    unexplained = [d for d in added.ignores if not d.reason]
+    assert not unexplained, "\n".join(
+        f"{d.path}:{d.line} adds `{d.raw}` with no stated reason" for d in unexplained
+    )
+```
+
+`diff=True` reports only the suppressions on lines the change added, using the
+same merge-base semantics as `notignored --diff` — so a suppression that was
+already on `main` is never yours.
+
+## The surface
+
+One entry point, in two forms. `ascan` takes the identical arguments and returns
+the identical report:
+
+```python
+scan(paths=(), *, diff=False, diff_base=None, tools=None, cwd=None, binary=None) -> Report
+await ascan(...)  # the same call, on an event loop
+```
+
+| Argument | What it does |
+| --- | --- |
+| `paths` | Files and/or directories. Directories are walked recursively, honouring `.gitignore`. Empty scans the working directory. |
+| `diff` | Report only the suppressions this change added. |
+| `diff_base` | The git revision `diff` compares against. Without `diff=True` it is a `ValueError`, exactly as the CLI rejects it. |
+| `tools` | Report only these tools (`Tool` members or their names); `None` reports all of them. |
+| `cwd` | Directory to run in. Report paths are relative to it. |
+| `binary` | The `notignored` to run. Defaults to `$NOTIGNORED_BIN`, then to the one on `PATH`. |
+
+The records mirror the CLI's JSON contract exactly, as frozen dataclasses:
+
+```python
+Report(version, ignores, errors)
+IgnoreDirective(tool, scope, rules, reason, path, line, end_line, column, raw, suppressed)
+Suppressed(start_line, end_line)  # end_line is None when the range runs to end-of-file
+ReportError(path, message)
+```
+
+`Tool` and `Scope` are string enums, so `directive.tool == "ruff"` and
+`directive.scope == "next-line"` both work.
+
+A file that could not be read is a `ReportError` in the report, never an
+exception — the CLI exits non-zero for it and the SDK still hands you the report
+that names it, because a tree with an unscannable file is not a clean tree.
+
+## Errors
+
+Everything raised is a `NotignoredError`:
+
+| Error | When |
+| --- | --- |
+| `NotignoredNotFoundError` | No `notignored` binary could be found. The message says how to install one. |
+| `NotignoredSpawnError` | The binary is there but the process could not start. |
+| `NotignoredExitError` | The scan could not run and printed no report; carries `returncode` and the CLI's `stderr`. |
+| `NotignoredContractError` | The output is not the report contract this SDK reads. |
+
+Parsing is strict: an unknown tool, an unknown scope, or a missing field is a
+`NotignoredContractError`, never a silently dropped record. Because the package
+pins its CLI exactly, a supported install cannot hit it.
+
+## Working on it
+
+From the repository root:
+
+```bash
+just bootstrap                             # provisions every project
+just nx run notignored-sdk-python:check    # this project's gate alone
+just check                                 # the whole repo's gate
+```

notignored_sdk-0.1.4/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "notignored-sdk"
+version = "0.1.4"
+description = "Typed Python SDK for notignored: every lint and type-check suppression in a source tree, as records."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = [
+    "lint",
+    "noqa",
+    "suppression",
+    "code-review",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = ["notignored-cli==0.1.4"]
+
+[[project.authors]]
+name = "Nick DeRobertis"
+
+[project.urls]
+Homepage = "https://github.com/nickderobertis/notignored"
+Repository = "https://github.com/nickderobertis/notignored"
+
+[tool.uv.build-backend]
+module-name = "notignored_sdk"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=notignored_sdk --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "ASYNC",
+    "S",
+    "RUF",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "S404",
+    "S603",
+    "S607",
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+
+[tool.coverage.run]
+branch = true
+source = ["notignored_sdk"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8,<10",
+    "pytest-cov>=5,<8",
+]

notignored_sdk-0.1.4/pyproject.toml.orig

@@ -0,0 +1,84 @@
+# The typed Python SDK: `pip install notignored-sdk`, `import notignored_sdk`.
+#
+# Pure Python — it drives the `notignored` binary as a subprocess, so there is
+# nothing to compile and one wheel serves every platform. The binary comes from
+# the `notignored-cli` dependency below, which is the same maturin wheel the
+# root pyproject.toml builds.
+#
+# NEITHER the version nor that dependency's pin is a version source. Cargo.toml
+# is the only one (see AGENTS.md, "The registry packages"), and
+# `scripts/python-sdk-build.mjs` stamps both from it at release time. The
+# committed file therefore carries a `.dev0` placeholder and an UNPINNED
+# `notignored-cli`, so a local `uv sync` resolves a real binary while nothing
+# here can drift out of step with a release.
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "notignored-sdk"
+version = "0.1.4"
+description = "Typed Python SDK for notignored: every lint and type-check suppression in a source tree, as records."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Nick DeRobertis" }]
+keywords = ["lint", "noqa", "suppression", "code-review", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = ["notignored-cli==0.1.4"]
+
+[project.urls]
+Homepage = "https://github.com/nickderobertis/notignored"
+Repository = "https://github.com/nickderobertis/notignored"
+
+[tool.uv.build-backend]
+module-name = "notignored_sdk"
+module-root = "src"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "pytest-cov>=5,<8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Coverage is enforced here rather than trusted: the suite drives a real
+# subprocess, so an untested branch is one nobody has ever run.
+addopts = "--cov=notignored_sdk --cov-report=term-missing --cov-fail-under=95"
+
+# ruff is not pinned here: `.ruff-version` is this repository's one source for it
+# and `scripts/dev-tool.sh` resolves the binary `just bootstrap` installed. Only
+# the rule selection lives with the project.
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B", "ASYNC", "S", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101", # Assertions are the test contract.
+    "S404", # The suite exists to drive a real subprocess.
+    "S603", # Its argument vectors are fixed or built from tmp_path.
+    "S607", # `cargo`, `git`, and `uv` are resolved from PATH on purpose.
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+
+[tool.coverage.run]
+branch = true
+source = ["notignored_sdk"]

notignored_sdk-0.1.4/src/notignored_sdk/__init__.py

@@ -0,0 +1,41 @@
+"""Typed Python access to the `notignored` CLI.
+
+One entry point, in two forms — :func:`scan` for the synchronous callers this
+exists for (a pytest suite guarding that nobody silenced a linter to make the
+gate pass) and :func:`ascan` for an event loop. Both drive the real `notignored`
+binary as a subprocess and return the same strictly-parsed :class:`Report`.
+
+    >>> from notignored_sdk import scan
+    >>> report = scan(["src"], tools=["ruff"])          # doctest: +SKIP
+    >>> [(d.path, d.line, d.rules) for d in report.ignores]   # doctest: +SKIP
+    [('src/app.py', 12, ('E501',))]
+
+The distribution depends on the exact `notignored-cli` it was released with, so
+`pip install notignored-sdk` brings a binary that matches this contract.
+"""
+
+from ._client import ascan, scan
+from ._errors import (
+    NotignoredContractError,
+    NotignoredError,
+    NotignoredExitError,
+    NotignoredNotFoundError,
+    NotignoredSpawnError,
+)
+from ._model import IgnoreDirective, Report, ReportError, Scope, Suppressed, Tool
+
+__all__ = [
+    "IgnoreDirective",
+    "NotignoredContractError",
+    "NotignoredError",
+    "NotignoredExitError",
+    "NotignoredNotFoundError",
+    "NotignoredSpawnError",
+    "Report",
+    "ReportError",
+    "Scope",
+    "Suppressed",
+    "Tool",
+    "ascan",
+    "scan",
+]

notignored_sdk-0.1.4/src/notignored_sdk/_client.py

@@ -0,0 +1,223 @@
+"""The one entry point, in both forms: `scan` and `ascan`.
+
+The SDK is a thin, typed shell over the real `notignored` binary — it never
+re-implements a parser, and it never shells out to anything else. `scan` and
+`ascan` take the same arguments and return the same :class:`Report`; the only
+difference is which subprocess API runs the process, so `pytest` can call one
+directly and an async service the other.
+
+Arguments are validated *before* a process is spawned, and paths go after a `--`
+separator so a filename that starts with a dash can never be read as a flag.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import subprocess
+from collections.abc import Sequence
+from typing import Any, Union
+
+from ._errors import (
+    INSTALL_HINT,
+    NotignoredContractError,
+    NotignoredExitError,
+    NotignoredNotFoundError,
+    NotignoredSpawnError,
+)
+from ._model import Report, Tool, report_from_payload
+
+#: Points the SDK at a specific binary without threading one through every call.
+#: An explicit ``binary=`` argument still wins over it.
+BINARY_ENV_VAR = "NOTIGNORED_BIN"
+
+#: Anything `os.fspath` accepts: `str`, `pathlib.Path`, or another path-like.
+PathLike = Union[str, "os.PathLike[str]"]
+
+# A report of a large tree is a single JSON document on one line, so the async
+# reader's default 64 KiB line limit is far too small.
+_STREAM_LIMIT = 64 * 1024 * 1024
+
+
+def _resolve_binary(binary: PathLike | None) -> str:
+    """Which `notignored` this call runs: the argument, the env override, PATH."""
+    if binary is not None:
+        return os.fspath(binary)
+    override = os.environ.get(BINARY_ENV_VAR)
+    if override:
+        return override
+    found = shutil.which("notignored")
+    if found is None:
+        raise NotignoredNotFoundError(
+            "notignored",
+            f"no `notignored` binary on PATH and {BINARY_ENV_VAR} is unset; {INSTALL_HINT}",
+        )
+    return found
+
+
+def _paths(paths: Sequence[PathLike]) -> list[str]:
+    """The positional PATHS, validated as a sequence of real paths."""
+    if isinstance(paths, (str, bytes, os.PathLike)):
+        raise TypeError("paths is a sequence of paths; pass [path] to scan a single one")
+    resolved = []
+    for index, path in enumerate(paths):
+        if isinstance(path, bytes) or not isinstance(path, (str, os.PathLike)):
+            raise TypeError(f"paths[{index}] is {type(path).__name__}, not a path")
+        text = os.fspath(path)
+        if not text:
+            raise ValueError(f"paths[{index}] is empty; omit it to scan the current directory")
+        resolved.append(text)
+    return resolved
+
+
+def _tools(tools: Sequence[Tool | str] | None) -> list[str]:
+    """The `--tool` filter, rejecting an unknown name before a process is spawned."""
+    if tools is None:
+        return []
+    if isinstance(tools, (str, bytes, Tool)):
+        raise TypeError("tools is a sequence of tools; pass [tool] to filter to a single one")
+    names = []
+    for index, tool in enumerate(tools):
+        if not isinstance(tool, str):
+            raise TypeError(f"tools[{index}] is {type(tool).__name__}, not a tool or its name")
+        try:
+            names.append(Tool(tool).value)
+        except ValueError:
+            known = ", ".join(known_tool.value for known_tool in Tool)
+            raise ValueError(f"tools[{index}] is {tool!r}; known tools are {known}") from None
+    return names
+
+
+def _command(
+    paths: Sequence[PathLike],
+    diff: bool,
+    diff_base: str | None,
+    tools: Sequence[Tool | str] | None,
+    binary: PathLike | None,
+) -> list[str]:
+    """The argument vector this call implies.
+
+    Every argument is validated before the binary is even resolved, so a typo in
+    a call is a `TypeError`/`ValueError` about the typo rather than whatever the
+    host happens to have installed.
+    """
+    if diff_base is not None:
+        if not diff:
+            raise ValueError("diff_base needs diff=True; there is nothing to compare it against")
+        if not isinstance(diff_base, str):
+            raise TypeError(f"diff_base is {type(diff_base).__name__}, not a git revision")
+    selected = _paths(paths)
+    names = _tools(tools)
+    argv = [_resolve_binary(binary), "--format", "json"]
+    for name in names:
+        argv.extend(("--tool", name))
+    if diff:
+        argv.append("--diff")
+    if diff_base is not None:
+        argv.extend(("--diff-base", diff_base))
+    # `--` last: a path spelled `-x` is a path, not a flag this SDK forwarded.
+    if selected:
+        argv.append("--")
+        argv.extend(selected)
+    return argv
+
+
+def _spawn_failure(command: str, error: OSError) -> NotignoredSpawnError:
+    """The OS's refusal to start the process, as one of this SDK's errors."""
+    if isinstance(error, FileNotFoundError):
+        return NotignoredNotFoundError(
+            command, f"no `notignored` binary at {command!r}; {INSTALL_HINT}"
+        )
+    return NotignoredSpawnError(command, f"cannot run `notignored` at {command!r}: {error}")
+
+
+def _report(returncode: int, stdout: bytes, stderr: bytes) -> Report:
+    """One finished run, as a report or as the error that stopped it.
+
+    A non-zero exit with a report on stdout is *not* an error: an unreadable file
+    makes the CLI exit 2 and still print the report that names it, and dropping
+    that would hide the very thing `Report.errors` exists to carry.
+    """
+    if not stdout.strip():
+        if returncode != 0:
+            raise NotignoredExitError(returncode, stderr.decode("utf-8", errors="replace"))
+        raise NotignoredContractError("notignored printed no report")
+    try:
+        payload: Any = json.loads(stdout)
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        if returncode != 0:
+            raise NotignoredExitError(
+                returncode, stderr.decode("utf-8", errors="replace")
+            ) from error
+        message = f"notignored printed output that is not JSON: {error}"
+        raise NotignoredContractError(message) from error
+    return report_from_payload(payload)
+
+
+def scan(
+    paths: Sequence[PathLike] = (),
+    *,
+    diff: bool = False,
+    diff_base: str | None = None,
+    tools: Sequence[Tool | str] | None = None,
+    cwd: PathLike | None = None,
+    binary: PathLike | None = None,
+) -> Report:
+    """Report every suppression comment `notignored` finds.
+
+    :param paths: Files and/or directories to scan. Directories are walked
+        recursively, honouring `.gitignore`. Empty scans the working directory,
+        which is the CLI's own default.
+    :param diff: Report only the suppressions this change added.
+    :param diff_base: The git revision `diff` compares against. Passing it
+        without ``diff=True`` is a :class:`ValueError`, exactly as the CLI
+        rejects ``--diff-base`` without ``--diff``.
+    :param tools: Report only these tools; ``None`` reports all of them.
+    :param cwd: Directory to run in. Report paths are relative to it.
+    :param binary: The `notignored` to run. Defaults to the ``NOTIGNORED_BIN``
+        environment variable, then to the one on ``PATH``.
+    :raises NotignoredNotFoundError: No `notignored` binary could be run.
+    :raises NotignoredExitError: The scan could not run and printed no report.
+    :raises NotignoredContractError: The report is not the contract this SDK reads.
+    """
+    argv = _command(paths, diff, diff_base, tools, binary)
+    try:
+        completed = subprocess.run(  # noqa: S603  # a vector this module built, never a shell
+            argv,
+            cwd=None if cwd is None else os.fspath(cwd),
+            capture_output=True,
+            check=False,
+        )
+    except OSError as error:
+        raise _spawn_failure(argv[0], error) from error
+    return _report(completed.returncode, completed.stdout, completed.stderr)
+
+
+async def ascan(
+    paths: Sequence[PathLike] = (),
+    *,
+    diff: bool = False,
+    diff_base: str | None = None,
+    tools: Sequence[Tool | str] | None = None,
+    cwd: PathLike | None = None,
+    binary: PathLike | None = None,
+) -> Report:
+    """Await :func:`scan`'s result without blocking the event loop.
+
+    Same arguments, same report, same errors; see :func:`scan`.
+    """
+    argv = _command(paths, diff, diff_base, tools, binary)
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *argv,
+            cwd=None if cwd is None else os.fspath(cwd),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            limit=_STREAM_LIMIT,
+        )
+    except OSError as error:
+        raise _spawn_failure(argv[0], error) from error
+    stdout, stderr = await process.communicate()
+    return _report(process.returncode or 0, stdout, stderr)

notignored_sdk-0.1.4/src/notignored_sdk/_errors.py

@@ -0,0 +1,64 @@
+"""The typed errors this SDK raises, and nothing else.
+
+Every failure a caller can hit crosses the same boundary: the CLI could not be
+started, it refused to finish, or what it printed is not the report contract this
+SDK reads. Each of those is a distinct class so a caller can tell "notignored is
+not installed" from "the scan itself failed" without matching on a message.
+"""
+
+from __future__ import annotations
+
+# The concrete next action for a host with no `notignored` on it. Attached to
+# every not-found error because that error is nearly always a setup problem, and
+# the traceback is the only place the reader is looking.
+INSTALL_HINT = (
+    "install it with `pip install notignored-sdk` (which depends on the "
+    "notignored-cli binary wheel) or `npm install -g notignored-cli`, or pass "
+    "`binary=` / set NOTIGNORED_BIN to point at one you already have"
+)
+
+
+class NotignoredError(Exception):
+    """Base class for every error this SDK raises."""
+
+
+class NotignoredSpawnError(NotignoredError):
+    """The `notignored` subprocess could not be started."""
+
+    def __init__(self, command: str, message: str) -> None:
+        self.command = command
+        super().__init__(message)
+
+
+class NotignoredNotFoundError(NotignoredSpawnError):
+    """No `notignored` binary could be found to run.
+
+    A subclass of :class:`NotignoredSpawnError` because it is the same failure —
+    the process never started — narrowed to the one cause worth its own `except`.
+    """
+
+
+class NotignoredExitError(NotignoredError):
+    """`notignored` exited non-zero without printing a report.
+
+    A scan that *does* produce a report is returned even when the CLI exits
+    non-zero: unreadable files are part of the contract (``Report.errors``), not
+    an SDK-level failure. This is the case where there is no report at all — a
+    path that does not exist, an argument the CLI rejected.
+    """
+
+    def __init__(self, returncode: int, stderr: str) -> None:
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"notignored exited {returncode}: {stderr.strip() or '(no stderr)'}")
+
+
+class NotignoredContractError(NotignoredError):
+    """What `notignored` printed is not the report contract this SDK reads.
+
+    Parsing is strict on purpose — an unknown tool, an unknown scope, or a
+    missing field is this error rather than a silently dropped record, because a
+    scan that quietly reports fewer suppressions than it found is worse than one
+    that fails. The SDK depends on an exact `notignored-cli`, so in a supported
+    install this cannot happen.
+    """

notignored_sdk-0.1.4/src/notignored_sdk/_model.py

@@ -0,0 +1,271 @@
+"""The report contract, as Python objects, and the strict reader that builds them.
+
+This mirrors notignored's `src/model.rs` field for field: it is a **versioned
+wire contract**, so the names here are the names on the wire and changing one is
+a breaking change for both sides at once.
+
+The reader is strict about what the contract *specifies* — an unknown tool, an
+unknown scope, a missing field, or a wrong type is a
+:class:`~notignored_sdk.NotignoredContractError` — and tolerant of keys it has
+never heard of, because the contract's own rule is that new fields are optional
+and additive. Rejecting those would break this SDK against a CLI that had only
+added something.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from ._errors import NotignoredContractError
+
+# The one envelope version this SDK reads. Bumped in step with notignored's
+# `REPORT_VERSION`; anything else is rejected at the boundary rather than parsed
+# into a record that may have lost fields.
+SUPPORTED_REPORT_VERSION = 1
+
+
+class Tool(str, Enum):
+    """A lint or type-check tool whose suppression comments notignored parses.
+
+    The values are what the CLI writes in a report and takes on ``--tool``, so a
+    plain string is accepted anywhere a :class:`Tool` is.
+    """
+
+    ESLINT = "eslint"
+    BIOME = "biome"
+    RUFF = "ruff"
+    TYPESCRIPT = "typescript"
+    MYPY = "mypy"
+    PYRIGHT = "pyright"
+    TY = "ty"
+    RUST = "rust"
+    SHELLCHECK = "shellcheck"
+    LLMLINT = "llmlint"
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+class Scope(str, Enum):
+    """How far a directive's suppression reaches."""
+
+    LINE = "line"
+    NEXT_LINE = "next-line"
+    FILE = "file"
+    BLOCK = "block"
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+@dataclass(frozen=True)
+class Suppressed:
+    """The range of source lines a directive silences."""
+
+    start_line: int
+    """First 1-based line the directive silences."""
+
+    end_line: int | None
+    """Last 1-based line, or ``None`` when the range runs to end-of-file or is
+    unterminated."""
+
+
+@dataclass(frozen=True)
+class IgnoreDirective:
+    """One parsed suppression comment."""
+
+    tool: Tool
+    """The tool whose rules are being silenced."""
+
+    scope: Scope
+    """How far the suppression reaches."""
+
+    rules: tuple[str, ...]
+    """Rule names/codes exactly as written. Empty means a blanket suppression of
+    every rule the tool would apply."""
+
+    reason: str | None
+    """The stated justification, or ``None`` when none was given."""
+
+    path: str
+    """Path to the file, relative to the invocation directory, ``/``-separated."""
+
+    line: int
+    """1-based line the directive starts on."""
+
+    end_line: int
+    """1-based line the directive ends on."""
+
+    column: int
+    """1-based column the directive starts at."""
+
+    raw: str
+    """The directive exactly as it appears in the source, delimiters included."""
+
+    suppressed: Suppressed
+    """The range of lines this directive silences."""
+
+
+@dataclass(frozen=True)
+class ReportError:
+    """A file that could not be read, or a directive that could not be parsed."""
+
+    path: str
+    """Path the problem was found at, ``/``-separated."""
+
+    message: str
+    """What went wrong, in one line."""
+
+
+@dataclass(frozen=True)
+class Report:
+    """The report envelope: everything one scan produced."""
+
+    version: int
+    """Envelope version; always :data:`SUPPORTED_REPORT_VERSION` once parsed."""
+
+    ignores: tuple[IgnoreDirective, ...]
+    """Every directive found, ordered by path, then line, then column."""
+
+    errors: tuple[ReportError, ...]
+    """Files that could not be read and directives that could not be parsed."""
+
+
+def _object(value: Any, where: str) -> dict[str, Any]:
+    """`value` as a JSON object, or a contract error naming what it was instead."""
+    if not isinstance(value, dict):
+        raise NotignoredContractError(f"{where} is {_kind(value)}, not an object")
+    return value
+
+
+def _kind(value: Any) -> str:
+    """How to name a JSON value in a diagnostic."""
+    return "null" if value is None else f"a {type(value).__name__}"
+
+
+def _field(obj: dict[str, Any], key: str, where: str) -> Any:
+    if key not in obj:
+        raise NotignoredContractError(f"{where} has no {key!r} field")
+    return obj[key]
+
+
+def _text(obj: dict[str, Any], key: str, where: str) -> str:
+    value = _field(obj, key, where)
+    if not isinstance(value, str):
+        raise NotignoredContractError(f"{where}.{key} is {_kind(value)}, not a string")
+    return value
+
+
+def _optional_text(obj: dict[str, Any], key: str, where: str) -> str | None:
+    value = _field(obj, key, where)
+    if value is None or isinstance(value, str):
+        return value
+    raise NotignoredContractError(f"{where}.{key} is {_kind(value)}, not a string or null")
+
+
+def _number(obj: dict[str, Any], key: str, where: str) -> int:
+    value = _field(obj, key, where)
+    # `bool` is a subclass of `int`, and `true` is not a line number.
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise NotignoredContractError(f"{where}.{key} is {_kind(value)}, not an integer")
+    return value
+
+
+def _optional_number(obj: dict[str, Any], key: str, where: str) -> int | None:
+    if _field(obj, key, where) is None:
+        return None
+    return _number(obj, key, where)
+
+
+def _texts(obj: dict[str, Any], key: str, where: str) -> tuple[str, ...]:
+    value = _field(obj, key, where)
+    if not isinstance(value, list):
+        raise NotignoredContractError(f"{where}.{key} is {_kind(value)}, not an array")
+    for index, item in enumerate(value):
+        if not isinstance(item, str):
+            raise NotignoredContractError(f"{where}.{key}[{index}] is {_kind(item)}, not a string")
+    return tuple(value)
+
+
+def _objects(obj: dict[str, Any], key: str, where: str) -> list[dict[str, Any]]:
+    value = _field(obj, key, where)
+    if not isinstance(value, list):
+        raise NotignoredContractError(f"{where}.{key} is {_kind(value)}, not an array")
+    return [_object(item, f"{where}.{key}[{index}]") for index, item in enumerate(value)]
+
+
+def _tool(obj: dict[str, Any], where: str) -> Tool:
+    name = _text(obj, "tool", where)
+    try:
+        return Tool(name)
+    except ValueError:
+        known = ", ".join(tool.value for tool in Tool)
+        raise NotignoredContractError(
+            f"{where}.tool is {name!r}, which this SDK does not know (known tools: {known}); "
+            "upgrade notignored-sdk"
+        ) from None
+
+
+def _scope(obj: dict[str, Any], where: str) -> Scope:
+    name = _text(obj, "scope", where)
+    try:
+        return Scope(name)
+    except ValueError:
+        known = ", ".join(scope.value for scope in Scope)
+        raise NotignoredContractError(
+            f"{where}.scope is {name!r}, which this SDK does not know (known scopes: {known}); "
+            "upgrade notignored-sdk"
+        ) from None
+
+
+def _suppressed(obj: dict[str, Any], where: str) -> Suppressed:
+    nested = _object(_field(obj, "suppressed", where), f"{where}.suppressed")
+    return Suppressed(
+        start_line=_number(nested, "start_line", f"{where}.suppressed"),
+        end_line=_optional_number(nested, "end_line", f"{where}.suppressed"),
+    )
+
+
+def _directive(obj: dict[str, Any], where: str) -> IgnoreDirective:
+    return IgnoreDirective(
+        tool=_tool(obj, where),
+        scope=_scope(obj, where),
+        rules=_texts(obj, "rules", where),
+        reason=_optional_text(obj, "reason", where),
+        path=_text(obj, "path", where),
+        line=_number(obj, "line", where),
+        end_line=_number(obj, "end_line", where),
+        column=_number(obj, "column", where),
+        raw=_text(obj, "raw", where),
+        suppressed=_suppressed(obj, where),
+    )
+
+
+def report_from_payload(payload: Any) -> Report:
+    """Read a decoded `--format json` payload as a :class:`Report`, strictly."""
+    envelope = _object(payload, "the report")
+    version = _number(envelope, "version", "the report")
+    if version != SUPPORTED_REPORT_VERSION:
+        upgrade = (
+            "notignored-sdk" if version > SUPPORTED_REPORT_VERSION else "the notignored binary"
+        )
+        raise NotignoredContractError(
+            f"the report claims version {version}, but this SDK reads version "
+            f"{SUPPORTED_REPORT_VERSION}; upgrade {upgrade}"
+        )
+    return Report(
+        version=version,
+        ignores=tuple(
+            _directive(item, f"the report.ignores[{index}]")
+            for index, item in enumerate(_objects(envelope, "ignores", "the report"))
+        ),
+        errors=tuple(
+            ReportError(
+                path=_text(item, "path", f"the report.errors[{index}]"),
+                message=_text(item, "message", f"the report.errors[{index}]"),
+            )
+            for index, item in enumerate(_objects(envelope, "errors", "the report"))
+        ),
+    )