code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/linting/external.py

@@ -0,0 +1,1454 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import timedelta
+from enum import StrEnum
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import signal
+import subprocess  # ruff: ignore[suspicious-subprocess-import] -- fixed argv, no shell, bounded timeout.
+import sys
+import threading
+import time
+import tomllib
+from typing import TYPE_CHECKING, ClassVar, Literal, NamedTuple, Protocol
+
+from pathspec import PathSpec
+from pydantic import BaseModel, ConfigDict, Field
+
+from sarj_standards.libs.adoption import manifest, packagemanager
+from sarj_standards.libs.adoption.lifecycle import select_eslint_commands
+from sarj_standards.libs.diagnostics import (
+    AnalyzerId,
+    Completion,
+    Diagnostic,
+    ExecutionIssue,
+    InvocationId,
+    Location,
+    Position,
+    Region,
+    Severity,
+    SourceDocument,
+    ToolReport,
+    TrustMode,
+)
+
+from .runner import GroupedPaths, group_paths
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import BinaryIO
+
+    from .policy import Policy
+
+
+class _ReactDoctorSelection(NamedTuple):
+    project: Path
+    projects: tuple[Path, ...]
+
+
+class _PreparedInputs(NamedTuple):
+    repository: Path
+    selected: tuple[str, ...]
+    grouped: GroupedPaths
+
+
+_TIMEOUT = timedelta(seconds=120)
+_ESLINT_ERROR = 2
+_MAX_STDOUT_BYTES = 16 * 1024 * 1024
+_MAX_STDERR_BYTES = 64 * 1024
+_READ_BYTES = 64 * 1024
+_MAX_ESLINT_PROJECTS = 32
+_MAX_PYTHON_PROJECTS = 32
+_ANALYSIS_DEADLINE = timedelta(seconds=300)
+_REACT_DOCTOR_MAX_DURATION = timedelta(seconds=60)
+_REACT_RUNTIME_PACKAGES = frozenset(
+    {
+        "@astrojs/react",
+        "@vitejs/plugin-react",
+        "@vitejs/plugin-react-swc",
+        "expo",
+        "next",
+        "preact",
+        "react",
+        "react-dom",
+        "react-native",
+    }
+)
+_JAVASCRIPT_SCAN_SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".next",
+        ".open-next",
+        ".turbo",
+        ".yarn",
+        "build",
+        "coverage",
+        "dist",
+        "node_modules",
+        "out",
+        "vendor",
+    }
+)
+_SAFE_ENVIRONMENT_KEYS = frozenset(
+    {
+        "HOME",
+        "LANG",
+        "PATH",
+        "SHELL",
+        "SYSTEMROOT",
+        "TEMP",
+        "TMP",
+        "TMPDIR",
+        "WINDIR",
+    }
+)
+
+
+class _ReactDoctorProtocolModel(BaseModel):
+    """Strictly type every React Doctor field consumed by the adapter."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", strict=True)
+
+
+class _ReactDoctorFailure(_ReactDoctorProtocolModel):
+    message: str = Field(min_length=1)
+
+
+class _ReactDoctorDiagnostic(_ReactDoctorProtocolModel):
+    file_path: str = Field(alias="filePath", min_length=1)
+    plugin: str = Field(min_length=1)
+    rule: str = Field(min_length=1)
+    severity: Literal["error", "warning"]
+    message: str = Field(min_length=1)
+    line: int = Field(ge=0)
+    column: int = Field(ge=0)
+    end_line: int | None = Field(default=None, alias="endLine", ge=0)
+    end_column: int | None = Field(default=None, alias="endColumn", ge=0)
+    url: str | None = None
+
+
+class _ReactDoctorProject(_ReactDoctorProtocolModel):
+    directory: str = Field(min_length=1)
+    complete: bool
+    diagnostics: tuple[_ReactDoctorDiagnostic, ...] = ()
+
+
+class _ReactDoctorReport(_ReactDoctorProtocolModel):
+    schema_version: Literal[3] = Field(alias="schemaVersion")
+    version: str = Field(min_length=1)
+    ok: bool
+    projects: tuple[_ReactDoctorProject, ...]
+    skipped_projects: tuple[object, ...] = Field(default=(), alias="skippedProjects")
+    error: _ReactDoctorFailure | None
+
+
+class _BasedPyrightPosition(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", strict=True)
+
+    line: int = Field(ge=0)
+    character: int = Field(ge=0)
+
+
+class _BasedPyrightRange(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", strict=True)
+
+    start: _BasedPyrightPosition
+    end: _BasedPyrightPosition
+
+
+class _BasedPyrightDiagnostic(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", strict=True)
+
+    file: str = Field(min_length=1)
+    severity: str = Field(min_length=1)
+    message: str = Field(min_length=1)
+    rule: str | None = None
+    range: _BasedPyrightRange
+
+
+class _BasedPyrightReport(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", strict=True)
+
+    general_diagnostics: tuple[_BasedPyrightDiagnostic, ...] = Field(alias="generalDiagnostics")
+
+
+class _ExternalSeverity(StrEnum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFORMATION = "information"
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessOutput:
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+class OutputLimitError(OSError):
+    """An analyzer exceeded the memory-safe structured-output contract."""
+
+
+class ProcessRunner(Protocol):
+    def __call__(self, argv: Sequence[str], *, cwd: Path) -> ProcessOutput: ...
+
+
+def analyze_external(
+    files: Sequence[str],
+    *,
+    root: Path,
+    trust: TrustMode | str,
+    runner: ProcessRunner | None = None,
+    policy: Policy | None = None,
+    capabilities: frozenset[str] | None = None,
+    grouped: GroupedPaths | None = None,
+    include_react_doctor: bool = False,
+    react_doctor_staged: bool = False,
+) -> tuple[ToolReport, ...]:
+    execute = run_process if runner is None else runner
+    try:
+        normalized_trust = TrustMode(trust)
+        root, _contained, routed = _prepare_inputs(files, root, policy=policy, grouped=grouped)
+    except (OSError, ValueError) as exc:
+        issue = ExecutionIssue("external", "invalid-input", str(exc))
+        return (ToolReport("external", Completion.FAILED, issues=(issue,)),)
+    reports: list[ToolReport] = []
+    if routed.python:
+        if capabilities is None or "ruff" in capabilities:
+            reports.extend(
+                _invoke_ruff_projects(
+                    routed.python,
+                    root=root,
+                    runner=execute,
+                )
+            )
+        if capabilities is None or "pyright" in capabilities:
+            reports.extend(
+                _invoke_python_projects(
+                    "basedpyright",
+                    routed.python,
+                    root=root,
+                    runner=execute,
+                    parser=parse_basedpyright,
+                )
+            )
+    if capabilities is not None and "eslint" not in capabilities:
+        eslint_commands = ()
+        unowned_eslint = 0
+    else:
+        try:
+            eslint_commands, unowned_eslint = select_eslint_commands(root, routed.typescript, label="analysis")
+        except (OSError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            message = _redact_message(f"{type(exc).__name__}: {exc}", root)
+            issue = ExecutionIssue("eslint", "configuration-failure", message)
+            reports.append(ToolReport("eslint", Completion.FAILED, issues=(issue,)))
+            return tuple(reports)
+    if unowned_eslint:
+        issue = ExecutionIssue(
+            "eslint",
+            "coverage-missing",
+            f"no TypeScript project accepts {unowned_eslint} selected JavaScript/TypeScript path(s)",
+        )
+        reports.append(
+            ToolReport(
+                "eslint",
+                Completion.FAILED,
+                issues=(issue,),
+                analyzer_id=AnalyzerId("eslint"),
+                invocation_id=InvocationId("eslint:unowned"),
+                file_count=unowned_eslint,
+            )
+        )
+    if len(eslint_commands) > _MAX_ESLINT_PROJECTS:
+        issue = ExecutionIssue(
+            "eslint",
+            "project-limit",
+            f"selected {len(eslint_commands)} ESLint projects; maximum is {_MAX_ESLINT_PROJECTS}",
+        )
+        reports.append(ToolReport("eslint", Completion.FAILED, issues=(issue,)))
+        eslint_commands = ()
+    analysis_started = time.monotonic()
+    for command in eslint_commands:
+        if time.monotonic() - analysis_started >= _ANALYSIS_DEADLINE.total_seconds():
+            issue = ExecutionIssue("eslint", "aggregate-timeout", "ESLint aggregate analysis exceeded 300 seconds")
+            reports.append(ToolReport("eslint", Completion.FAILED, issues=(issue,)))
+            break
+        if normalized_trust is TrustMode.SAFE:
+            issue = ExecutionIssue(
+                "eslint",
+                "trust-required",
+                "ESLint config is executable repository code; retry with TrustMode.TRUSTED",
+            )
+            reports.append(ToolReport("eslint", Completion.FAILED, issues=(issue,)))
+            continue
+        if runner is None and (issue := _missing_eslint_issue(command.cwd, root)) is not None:
+            reports.append(
+                ToolReport(
+                    "eslint",
+                    Completion.FAILED,
+                    issues=(issue,),
+                    analyzer_id=AnalyzerId("eslint"),
+                    invocation_id=InvocationId(f"eslint:{command.cwd.relative_to(root).as_posix() or '.'}"),
+                    file_count=_argv_file_count(command.argv),
+                )
+            )
+            continue
+        reports.append(
+            _invoke(
+                "eslint",
+                _local_eslint_argv(_eslint_json_argv(command.argv), command.cwd, root)
+                if runner is None
+                else _eslint_json_argv(command.argv),
+                cwd=command.cwd,
+                root=root,
+                runner=execute,
+                parser=parse_eslint,
+                invocation_id=command.cwd.relative_to(root).as_posix() or ".",
+                file_count=_argv_file_count(command.argv),
+            )
+        )
+    react_selection = _selected_react_doctor_projects(
+        root,
+        enabled=include_react_doctor,
+        has_typescript=bool(routed.typescript),
+        capabilities=capabilities,
+    )
+    if react_selection is not None:
+        react_root, react_projects = react_selection
+        reports.append(
+            _invoke_react_doctor(
+                react_root,
+                projects=react_projects,
+                root=root,
+                runner=execute,
+                use_local_binary=runner is None,
+                file_count=len(routed.typescript),
+                staged=react_doctor_staged,
+            )
+        )
+    if policy is None:
+        return tuple(reports)
+    return tuple(
+        ToolReport(
+            report.name,
+            report.completion,
+            diagnostics=policy.filter_diagnostics(report.diagnostics),
+            issues=report.issues,
+            analyzer_id=report.analyzer_id,
+            invocation_id=report.invocation_id,
+            version=report.version,
+            duration_ms=report.duration_ms,
+            file_count=report.file_count,
+            cache_status=report.cache_status,
+        )
+        for report in reports
+    )
+
+
+def _missing_eslint_issue(project: Path, root: Path) -> ExecutionIssue | None:
+    current = project.resolve()
+    repository = root.resolve()
+    while True:
+        if (current / ".pnp.cjs").is_file() or (current / ".pnp.loader.mjs").is_file():
+            return None
+        binaries = current / "node_modules" / ".bin"
+        if (binaries / "eslint").is_file() or (binaries / "eslint.cmd").is_file():
+            return None
+        if current.parent == current:
+            break
+        current = current.parent
+    relative = project.resolve().relative_to(repository).as_posix() or "."
+    message = (
+        f"ESLint is not installed locally for {relative}; node_modules/.bin/eslint is missing. "
+        "Run the repository's locked package install or rerun `code-standards setup`, then retry."
+    )
+    return ExecutionIssue("eslint", "missing-dependency", message)
+
+
+def _local_eslint_argv(argv: Sequence[str], project: Path, root: Path) -> tuple[str, ...]:
+    current = project.resolve()
+    while True:
+        if (current / ".pnp.cjs").is_file() or (current / ".pnp.loader.mjs").is_file():
+            return tuple(argv)
+        binaries = current / "node_modules" / ".bin"
+        binary = binaries / ("eslint.cmd" if os.name == "nt" else "eslint")
+        if binary.is_file():
+            try:
+                tail = tuple(argv[argv.index("eslint") + 1 :])
+            except ValueError as exc:
+                msg = "ESLint command does not contain an eslint executable"
+                raise ValueError(msg) from exc
+            if os.name == "nt":
+                return ("cmd.exe", "/d", "/s", "/c", str(binary), *tail)
+            return (str(binary), *tail)
+        if current.parent == current:
+            break
+        current = current.parent
+    # The preflight owns the user-facing missing-dependency error. Reaching
+    # this branch means the filesystem changed between preflight and launch.
+    relative = project.resolve().relative_to(root.resolve()).as_posix() or "."
+    msg = f"local ESLint disappeared before execution for {relative}"
+    raise OSError(msg)
+
+
+def _selected_react_doctor_projects(
+    root: Path,
+    *,
+    enabled: bool,
+    has_typescript: bool,
+    capabilities: frozenset[str] | None,
+) -> _ReactDoctorSelection | None:
+    if not enabled or not has_typescript or (capabilities is not None and "eslint" not in capabilities):
+        return None
+    adopted = manifest.load(root)
+    project = _react_doctor_root(root, adopted=adopted)
+    excluded = () if adopted is None else adopted.doctor_excluded_paths
+    if project is None or not (projects := _react_project_roots(project, repository=root, excluded=excluded)):
+        return None
+    return _ReactDoctorSelection(project, projects)
+
+
+def _react_doctor_root(root: Path, *, adopted: manifest.Manifest | None = None) -> Path | None:
+    if adopted is None:
+        adopted = manifest.load(root)
+    candidate = root if adopted is None else (root / adopted.typescript_dest).resolve()
+    return candidate if candidate.is_dir() else None
+
+
+def _react_project_roots(
+    root: Path,
+    *,
+    repository: Path | None = None,
+    excluded: Sequence[str] = (),
+) -> tuple[Path, ...]:
+    repository_root = root.resolve() if repository is None else repository.resolve()
+    exclusions = PathSpec.from_lines("gitignore", excluded)
+    projects: list[Path] = []
+    for parent, directories, filenames in os.walk(root, topdown=True, followlinks=False):
+        directory = Path(parent).resolve()
+        relative = directory.relative_to(repository_root).as_posix()
+        if relative and exclusions.match_file(relative):
+            directories[:] = []
+            continue
+        directories[:] = sorted(name for name in directories if name not in _JAVASCRIPT_SCAN_SKIP_DIRS)
+        if "package.json" not in filenames:
+            continue
+        package_json = directory / "package.json"
+        try:
+            parsed: object = json.loads(package_json.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+        except OSError, ValueError:
+            continue
+        document = manifest.as_table(parsed)
+        declared: set[str] = set()
+        for field in ("dependencies", "devDependencies", "peerDependencies"):
+            declared.update(manifest.table_field(document, field))
+        if declared.intersection(_REACT_RUNTIME_PACKAGES):
+            projects.append(directory)
+    return tuple(projects)
+
+
+def _invoke_react_doctor(
+    project: Path,
+    *,
+    projects: Sequence[Path],
+    root: Path,
+    runner: ProcessRunner,
+    use_local_binary: bool,
+    file_count: int,
+    staged: bool,
+) -> ToolReport:
+    name = "react-doctor"
+    if use_local_binary and (issue := _missing_local_binary_issue(name, project, root)) is not None:
+        return ToolReport(
+            name,
+            Completion.FAILED,
+            issues=(issue,),
+            analyzer_id=AnalyzerId(name),
+            invocation_id=InvocationId(name),
+            file_count=file_count,
+        )
+    install_root = packagemanager.workspace_root(project, root)
+    client = packagemanager.detect(install_root)
+    # React Doctor is introduced as a no-baseline ratchet: hooks inspect the
+    # index, while whole-repository Standards runs block only diagnostics that
+    # are new relative to the detected merge base. A standalone React Doctor
+    # full scan remains available for deliberate debt cleanup.
+    scope_args = _react_doctor_scope_args(staged=staged)
+    argv = packagemanager.exec_argv(
+        client,
+        name,
+        ".",
+        "--project",
+        ",".join(item.relative_to(project).as_posix() or "." for item in projects),
+        *scope_args,
+        "--blocking",
+        "warning",
+        "--no-dead-code",
+        "--no-supply-chain",
+        "--no-score",
+        "--no-cache",
+        "--max-duration",
+        str(int(_REACT_DOCTOR_MAX_DURATION.total_seconds())),
+        "--json",
+        "--json-compact",
+        "--no-color",
+    )
+    report = _invoke(
+        name,
+        _local_node_binary_argv(name, argv, project, root) if use_local_binary else argv,
+        cwd=project,
+        root=root,
+        runner=runner,
+        parser=parse_react_doctor,
+        invocation_id=project.relative_to(root).as_posix() or None,
+        file_count=file_count,
+    )
+    return _filter_react_doctor_to_changed_paths(report, root=root, runner=runner, staged=staged)
+
+
+def _filter_react_doctor_to_changed_paths(
+    report: ToolReport,
+    *,
+    root: Path,
+    runner: ProcessRunner,
+    staged: bool,
+) -> ToolReport:
+    if staged:
+        return report
+    base = change_scope_base()
+    if not base:
+        return report
+    changed = runner(
+        ("git", "diff", "--name-only", "--diff-filter=ACMR", "-z", f"{base}...HEAD", "--"),
+        cwd=root,
+    )
+    if changed.returncode != 0:
+        return report
+    changed_paths = frozenset(path for path in changed.stdout.split("\0") if path)
+    return replace(
+        report,
+        diagnostics=tuple(item for item in report.diagnostics if item.location.path in changed_paths),
+    )
+
+
+def _react_doctor_scope_args(*, staged: bool) -> tuple[str, ...]:
+    if staged:
+        return ("--staged",)
+    base = change_scope_base()
+    if base:
+        return ("--scope", "changed", "--base", base)
+    return ("--scope", "changed")
+
+
+def change_scope_base() -> str:
+    explicit = os.environ.get(  # ruff: ignore[banned-api] -- explicit CI workflow boundary, not application settings.
+        "SARJ_REACT_DOCTOR_BASE", ""
+    ).strip()
+    if explicit:
+        return explicit
+    event_path = os.environ.get(  # ruff: ignore[banned-api] -- GitHub owns this path in Actions.
+        "GITHUB_EVENT_PATH", ""
+    ).strip()
+    if not event_path:
+        return ""
+    try:
+        payload: object = json.loads(Path(event_path).read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    except OSError, json.JSONDecodeError:
+        return ""
+    pull_request = manifest.as_table(manifest.as_table(payload).get("pull_request"))
+    base = manifest.as_table(pull_request.get("base"))
+    sha = manifest.text_field(base, "sha")
+    return sha if sha is not None and re.fullmatch(r"[0-9a-f]{40}", sha) else ""
+
+
+def is_non_default_github_push() -> bool:
+    event_name = os.environ.get(  # ruff: ignore[banned-api] -- GitHub owns this value in Actions.
+        "GITHUB_EVENT_NAME", ""
+    ).strip()
+    if event_name != "push":
+        return False
+    event_path = os.environ.get(  # ruff: ignore[banned-api] -- GitHub owns this path in Actions.
+        "GITHUB_EVENT_PATH", ""
+    ).strip()
+    if not event_path:
+        return False
+    try:
+        payload: object = json.loads(Path(event_path).read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    except OSError, json.JSONDecodeError:
+        return False
+    event = manifest.as_table(payload)
+    if manifest.as_table(event.get("pull_request")):
+        return False
+    ref = manifest.text_field(event, "ref")
+    repository = manifest.as_table(event.get("repository"))
+    default_branch = manifest.text_field(repository, "default_branch")
+    prefix = "refs/heads/"
+    return bool(ref and default_branch and ref.startswith(prefix) and ref.removeprefix(prefix) != default_branch)
+
+
+def _missing_local_binary_issue(name: str, project: Path, root: Path) -> ExecutionIssue | None:
+    current = project.resolve()
+    repository = root.resolve()
+    while current.is_relative_to(repository):
+        if (current / ".pnp.cjs").is_file() or (current / ".pnp.loader.mjs").is_file():
+            return None
+        binaries = current / "node_modules" / ".bin"
+        if (binaries / name).is_file() or (binaries / f"{name}.cmd").is_file():
+            return None
+        if current == repository:
+            break
+        current = current.parent
+    relative = project.relative_to(repository).as_posix() or "."
+    message = (
+        f"{name} is not installed locally for {relative}; node_modules/.bin/{name} is missing. "
+        "Run the repository's locked package install or rerun `code-standards setup`, then retry."
+    )
+    return ExecutionIssue(name, "missing-dependency", message)
+
+
+def _local_node_binary_argv(name: str, argv: Sequence[str], project: Path, root: Path) -> tuple[str, ...]:
+    current = project.resolve()
+    repository = root.resolve()
+    while current.is_relative_to(repository):
+        if (current / ".pnp.cjs").is_file() or (current / ".pnp.loader.mjs").is_file():
+            return tuple(argv)
+        binary = current / "node_modules" / ".bin" / (f"{name}.cmd" if os.name == "nt" else name)
+        if binary.is_file():
+            try:
+                tail = tuple(argv[argv.index(name) + 1 :])
+            except ValueError as exc:
+                msg = f"analyzer command does not contain {name!r}"
+                raise ValueError(msg) from exc
+            if os.name == "nt":
+                return ("cmd.exe", "/d", "/s", "/c", str(binary), *tail)
+            return (str(binary), *tail)
+        if current == repository:
+            break
+        current = current.parent
+    msg = f"local {name} disappeared before execution"
+    raise OSError(msg)
+
+
+def _invoke_python_projects(
+    name: str,
+    files: Sequence[str],
+    *,
+    root: Path,
+    runner: ProcessRunner,
+    parser: ProtocolParser,
+) -> tuple[ToolReport, ...]:
+    projects = _group_python_projects(files, root)
+    if len(projects) > _MAX_PYTHON_PROJECTS:
+        issue = ExecutionIssue(
+            name,
+            "project-limit",
+            f"selected {len(projects)} Python projects; maximum is {_MAX_PYTHON_PROJECTS}",
+        )
+        return (ToolReport(name, Completion.FAILED, issues=(issue,), analyzer_id=AnalyzerId(name)),)
+    reports: list[ToolReport] = []
+    for project, scoped_files in projects:
+        argv = (_project_analyzer(project, "basedpyright"), "--outputjson")
+        project_id = project.relative_to(root).as_posix() or None
+        report = _invoke(
+            name,
+            argv,
+            cwd=project,
+            root=root,
+            runner=runner,
+            parser=parser,
+            invocation_id=project_id,
+            file_count=len(scoped_files),
+        )
+        selected = frozenset(_relative(Path(path), root) for path in scoped_files)
+        reports.append(
+            ToolReport(
+                report.name,
+                report.completion,
+                diagnostics=tuple(
+                    diagnostic for diagnostic in report.diagnostics if diagnostic.location.path in selected
+                ),
+                issues=report.issues,
+                analyzer_id=report.analyzer_id,
+                invocation_id=report.invocation_id,
+                version=report.version,
+                duration_ms=report.duration_ms,
+                file_count=report.file_count,
+                cache_status=report.cache_status,
+            )
+        )
+    return tuple(reports)
+
+
+def _invoke_ruff_projects(
+    files: Sequence[str],
+    *,
+    root: Path,
+    runner: ProcessRunner,
+) -> tuple[ToolReport, ...]:
+    reports: list[ToolReport] = []
+    for project, config, scoped_files in _group_ruff_projects(files, root):
+        project_id = None if project == root else project.relative_to(root).as_posix()
+        reports.append(
+            _invoke(
+                "ruff",
+                _ruff_argv(scoped_files, config=config),
+                cwd=project,
+                root=root,
+                runner=runner,
+                parser=parse_ruff,
+                invocation_id=project_id,
+                file_count=len(scoped_files),
+            )
+        )
+    return tuple(reports)
+
+
+def _project_analyzer(project: Path, name: str) -> str:
+    candidates = (
+        project / ".venv" / "bin" / name,
+        project / ".venv" / "Scripts" / f"{name}.exe",
+    )
+    return str(next((candidate for candidate in candidates if candidate.is_file()), name))
+
+
+def _group_python_projects(files: Sequence[str], root: Path) -> tuple[tuple[Path, tuple[str, ...]], ...]:
+    fallback = _adopted_python_project(root)
+    grouped: dict[Path, list[str]] = {}
+    for raw_file in files:
+        path = Path(raw_file).resolve()
+        project = _nearest_analyzer_project(path.parent, root, fallback=fallback)
+        grouped.setdefault(project, []).append(str(path))
+    return tuple(
+        (project, tuple(sorted(scoped_files)))
+        for project, scoped_files in sorted(grouped.items(), key=lambda item: str(item[0]))
+    )
+
+
+def _nearest_analyzer_project(start: Path, root: Path, *, fallback: Path | None = None) -> Path:
+    configured = _nearest_configured_python_project(start, root, names=("pyright", "basedpyright"))
+    if configured is not None:
+        return configured
+    current = start
+    while current.is_relative_to(root):
+        if any(
+            candidate.is_file()
+            for candidate in (
+                current / ".venv" / "bin" / "basedpyright",
+                current / ".venv" / "Scripts" / "basedpyright.exe",
+            )
+        ):
+            return current
+        if current == root:
+            break
+        current = current.parent
+    return fallback or _nearest_project(start, root, ("pyproject.toml",))
+
+
+def _group_ruff_projects(files: Sequence[str], root: Path) -> tuple[tuple[Path, Path | None, tuple[str, ...]], ...]:
+    fallback = _adopted_python_config(root)
+    grouped: dict[tuple[Path, Path | None], list[str]] = {}
+    for raw_file in files:
+        path = Path(raw_file).resolve()
+        config = _nearest_ruff_config(path.parent, root) or fallback
+        project = root if config is None else config.parent
+        grouped.setdefault((project, config), []).append(str(path))
+    return tuple(
+        (project, config, tuple(sorted(scoped_files)))
+        for (project, config), scoped_files in sorted(grouped.items(), key=lambda item: str(item[0][0]))
+    )
+
+
+def _nearest_ruff_config(start: Path, root: Path) -> Path | None:
+    current = start
+    while current.is_relative_to(root):
+        for name in (".ruff.toml", "ruff.toml"):
+            candidate = current / name
+            if candidate.is_file():
+                return candidate
+        pyproject = current / "pyproject.toml"
+        if pyproject.is_file() and _pyproject_has_tool(pyproject, ("ruff",)):
+            return pyproject
+        if current == root:
+            break
+        current = current.parent
+    return None
+
+
+def _adopted_python_config(root: Path) -> Path | None:
+    project = _adopted_python_project(root)
+    return None if project is None else _nearest_ruff_config(project, root)
+
+
+def _adopted_python_project(root: Path) -> Path | None:
+    try:
+        adopted = manifest.load(root)
+    except OSError, TypeError, ValueError:
+        return None
+    if adopted is None:
+        return None
+    project = (root / adopted.python_dest).resolve()
+    return project if project.is_dir() else None
+
+
+def _nearest_configured_python_project(start: Path, root: Path, *, names: Sequence[str]) -> Path | None:
+    current = start
+    while current.is_relative_to(root):
+        if (current / "pyrightconfig.json").is_file() or (current / "pyrightconfig.jsonc").is_file():
+            return current
+        pyproject = current / "pyproject.toml"
+        if pyproject.is_file() and _pyproject_has_tool(pyproject, names):
+            return current
+        if current == root:
+            break
+        current = current.parent
+    return None
+
+
+def _pyproject_has_tool(path: Path, names: Sequence[str]) -> bool:
+    try:
+        parsed: object = tomllib.loads(path.read_text(encoding="utf-8"))
+    except OSError, tomllib.TOMLDecodeError:
+        return False
+    document = manifest.as_table(parsed)
+    tool = manifest.as_table(document.get("tool"))
+    return any(isinstance(tool.get(name), dict) for name in names)
+
+
+def _nearest_project(start: Path, root: Path, markers: Sequence[str]) -> Path:
+    current = start
+    while current.is_relative_to(root):
+        if any((current / marker).is_file() for marker in markers):
+            return current
+        if current == root:
+            break
+        current = current.parent
+    return root
+
+
+def run_process(argv: Sequence[str], *, cwd: Path) -> ProcessOutput:
+    executable = _analyzer_executable(argv[0])
+    if executable is None:
+        msg = f"required analyzer executable is missing: {argv[0]}"
+        raise FileNotFoundError(msg)
+    process = subprocess.Popen(  # ruff: ignore[subprocess-without-shell-equals-true] -- fixed argv and shell stays disabled.
+        [executable, *argv[1:]],
+        cwd=cwd,
+        shell=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        start_new_session=os.name == "posix",
+        env=_analysis_environment(),
+    )
+    stdout = process.stdout
+    stderr = process.stderr
+    if stdout is None or stderr is None:  # pragma: no cover - PIPE guarantees streams.
+        process.kill()
+        msg = "analyzer process did not expose output pipes"
+        raise OSError(msg)
+    exceeded = threading.Event()
+    captures: list[bytes | None] = [None, None]
+    threads = (
+        threading.Thread(target=_capture_stream, args=(stdout, _MAX_STDOUT_BYTES, exceeded, captures, 0), daemon=True),
+        threading.Thread(target=_capture_stream, args=(stderr, _MAX_STDERR_BYTES, exceeded, captures, 1), daemon=True),
+    )
+    try:
+        _start_capture_threads(threads)
+        returncode = _wait_for_process(process, threads, exceeded, argv)
+    except BaseException:
+        if process.poll() is None:
+            _terminate_process(process)
+        try:
+            _ = process.wait(timeout=5)
+        except OSError, subprocess.SubprocessError:
+            process.kill()
+        for thread in threads:
+            if thread.ident is not None:
+                thread.join(timeout=5)
+        raise
+    if exceeded.is_set():
+        msg = "analyzer output exceeded the 16 MiB stdout or 64 KiB stderr limit"
+        raise OutputLimitError(msg)
+    stdout_bytes, stderr_bytes = captures
+    if stdout_bytes is None or stderr_bytes is None:  # pragma: no cover - drain threads always assign.
+        msg = "analyzer process output could not be captured"
+        raise OSError(msg)
+    return ProcessOutput(
+        returncode,
+        stdout_bytes.decode("utf-8", errors="replace"),
+        stderr_bytes.decode("utf-8", errors="replace"),
+    )
+
+
+def _analyzer_executable(name: str) -> str | None:
+    environment_bin = str(Path(sys.executable).parent)
+    return shutil.which(name, path=environment_bin) or shutil.which(name)
+
+
+def _analysis_environment() -> dict[str, str]:
+    return {
+        key: value
+        for key, value in os.environ.items()  # ruff: ignore[banned-api] -- deliberately reduce inherited environment.
+        if key in _SAFE_ENVIRONMENT_KEYS or key.startswith("LC_")
+    }
+
+
+def _start_capture_threads(threads: Sequence[threading.Thread]) -> None:
+    for thread in threads:
+        thread.start()
+
+
+def _wait_for_process(
+    process: subprocess.Popen[bytes],
+    threads: Sequence[threading.Thread],
+    exceeded: threading.Event,
+    argv: Sequence[str],
+) -> int:
+    deadline = time.monotonic() + _TIMEOUT.total_seconds()
+    while process.poll() is None and not exceeded.is_set():
+        if time.monotonic() >= deadline:
+            _terminate_process(process)
+            _ = process.wait(timeout=5)
+            _join_capture_threads(threads)
+            raise subprocess.TimeoutExpired(argv, _TIMEOUT.total_seconds())
+        time.sleep(0.01)
+    if exceeded.is_set():
+        _terminate_process(process)
+    returncode = process.wait(timeout=5 if exceeded.is_set() else None)
+    _join_capture_threads(threads)
+    return returncode
+
+
+def _capture_stream(
+    stream: BinaryIO,
+    limit: int,
+    exceeded: threading.Event,
+    captures: list[bytes | None],
+    index: int,
+) -> None:
+    data = bytearray()
+    try:
+        while chunk := stream.read(_READ_BYTES):
+            remaining = limit - len(data)
+            if remaining > 0:
+                data.extend(chunk[:remaining])
+            if len(chunk) > remaining:
+                exceeded.set()
+                break
+    finally:
+        stream.close()
+        captures[index] = bytes(data)
+
+
+def _terminate_process(process: subprocess.Popen[bytes]) -> None:
+    if os.name == "posix":
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            return
+    else:  # pragma: no cover - Windows CI covers the process-tree strategy.
+        try:
+            taskkill = shutil.which("taskkill")
+            if taskkill is None:
+                msg = "taskkill is unavailable"
+                raise FileNotFoundError(msg)
+            subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- resolved system binary, fixed argv.
+                (taskkill, "/PID", str(process.pid), "/T", "/F"),
+                check=False,
+                capture_output=True,
+                shell=False,
+                timeout=5,
+            )
+        except OSError, subprocess.SubprocessError:
+            process.kill()
+        if process.poll() is None:
+            process.kill()
+
+
+def _join_capture_threads(threads: Sequence[threading.Thread]) -> None:
+    for thread in threads:
+        thread.join(timeout=5)
+    if any(thread.is_alive() for thread in threads):
+        msg = "analyzer output streams did not close after process termination"
+        raise OSError(msg)
+
+
+def _invoke(
+    name: str,
+    argv: Sequence[str],
+    *,
+    cwd: Path,
+    root: Path,
+    runner: ProcessRunner,
+    parser: ProtocolParser,
+    invocation_id: str | None = None,
+    file_count: int,
+) -> ToolReport:
+    started = time.monotonic()
+    try:
+        report = _invoke_unchecked(name, argv, cwd=cwd, root=root, runner=runner, parser=parser)
+        return ToolReport(
+            report.name,
+            report.completion,
+            diagnostics=report.diagnostics,
+            issues=report.issues,
+            analyzer_id=AnalyzerId(name),
+            invocation_id=InvocationId(name if invocation_id is None else f"{name}:{invocation_id}"),
+            duration_ms=round((time.monotonic() - started) * 1_000),
+            file_count=file_count,
+        )
+    except (OSError, TypeError, ValueError, RecursionError, json.JSONDecodeError, subprocess.SubprocessError) as exc:
+        message = _redact_message(f"{type(exc).__name__}: {exc}", root)
+        issue = ExecutionIssue(name, "tool-failure", message)
+        return ToolReport(
+            name,
+            Completion.FAILED,
+            issues=(issue,),
+            analyzer_id=AnalyzerId(name),
+            invocation_id=InvocationId(name if invocation_id is None else f"{name}:{invocation_id}"),
+            duration_ms=round((time.monotonic() - started) * 1_000),
+            file_count=file_count,
+        )
+
+
+def _invoke_unchecked(
+    name: str,
+    argv: Sequence[str],
+    *,
+    cwd: Path,
+    root: Path,
+    runner: ProcessRunner,
+    parser: ProtocolParser,
+) -> ToolReport:
+    output = runner(argv, cwd=cwd)
+    if output.returncode not in {0, 1}:
+        message = _redact_message(output.stderr.strip() or f"{name} exited {output.returncode}", root)
+        issue = ExecutionIssue(name, "tool-failure", message, output.returncode)
+        return ToolReport(name, Completion.FAILED, issues=(issue,))
+    if not output.stdout.strip():
+        stderr = output.stderr.strip()
+        kind = "tool-failure" if stderr else "protocol-mismatch"
+        message = _redact_message(stderr or f"{name} returned empty structured output", root)
+        issue = ExecutionIssue(name, kind, message, output.returncode)
+        return ToolReport(name, Completion.FAILED, issues=(issue,))
+    try:
+        diagnostics = parser(output.stdout, root=root)
+    except json.JSONDecodeError as exc:
+        stderr = output.stderr.strip()
+        message = stderr or f"{name} returned invalid structured JSON at line {exc.lineno}, column {exc.colno}"
+        issue = ExecutionIssue(name, "protocol-mismatch", _redact_message(message, root), output.returncode)
+        return ToolReport(name, Completion.FAILED, issues=(issue,))
+    if output.returncode == 1 and not diagnostics:
+        message = _redact_message(output.stderr.strip() or f"{name} exited 1 but reported no diagnostics", root)
+        issue = ExecutionIssue(name, "protocol-mismatch", message, output.returncode)
+        return ToolReport(name, Completion.FAILED, issues=(issue,))
+    return ToolReport(name, Completion.COMPLETE, diagnostics=diagnostics)
+
+
+class ProtocolParser(Protocol):
+    def __call__(self, payload: str, *, root: Path) -> tuple[Diagnostic, ...]: ...
+
+
+def parse_ruff(payload: str, *, root: Path) -> tuple[Diagnostic, ...]:
+    values = _array(_loads(payload), "Ruff output")
+    documents: dict[Path, SourceDocument | None] = {}
+    diagnostics: list[Diagnostic] = []
+    for value in values:
+        item = _table(value, "Ruff diagnostic")
+        path = _path(item, "filename", root)
+        start = _one_based_position(_table(item.get("location"), "Ruff location"), path, documents)
+        end_value = item.get("end_location")
+        end = _one_based_position(_table(end_value, "Ruff end location"), path, documents)
+        code = _text(item, "code")
+        url_value = item.get("url")
+        help_url = url_value if isinstance(url_value, str) else None
+        diagnostics.append(
+            Diagnostic(
+                code,
+                _redact_message(_text(item, "message"), root),
+                Severity.ERROR,
+                "ruff",
+                Location(_relative(path, root), region=Region(start, end)),
+                rule_id=code,
+                help_url=help_url,
+            )
+        )
+    return tuple(diagnostics)
+
+
+def parse_basedpyright(payload: str, *, root: Path) -> tuple[Diagnostic, ...]:
+    report = _BasedPyrightReport.model_validate_json(payload)
+    documents: dict[Path, SourceDocument | None] = {}
+    diagnostics: list[Diagnostic] = []
+    for item in report.general_diagnostics:
+        path = _reported_path(item.file, root)
+        start = _basedpyright_position(item.range.start, path, documents)
+        end = _basedpyright_position(item.range.end, path, documents)
+        rule = item.rule or "basedpyright"
+        diagnostics.append(
+            Diagnostic(
+                rule,
+                _redact_message(item.message, root),
+                _severity_text(item.severity),
+                "basedpyright",
+                Location(_relative(path, root), region=Region(start, end)),
+                rule_id=rule,
+            )
+        )
+    return tuple(diagnostics)
+
+
+def parse_eslint(  # ruff: ignore[too-many-locals] -- protocol normalization keeps each ESLint field explicit.
+    payload: str, *, root: Path
+) -> tuple[Diagnostic, ...]:
+    values = _array(_loads(payload), "ESLint output")
+    documents: dict[Path, SourceDocument | None] = {}
+    diagnostics: list[Diagnostic] = []
+    for value in values:
+        result = _table(value, "ESLint file result")
+        path = _path(result, "filePath", root)
+        for raw_message in _array(result.get("messages"), "ESLint messages"):
+            item = _table(raw_message, "ESLint diagnostic")
+            if item.get("fatal") is True:
+                detail = _text(item, "message")
+                msg = f"ESLint fatal parser/configuration failure: {detail}"
+                raise ValueError(msg)
+            start = _eslint_start_position(item, path, documents)
+            end = (
+                None
+                if start is None
+                else _eslint_position(item, path, documents, line_key="endLine", column_key="endColumn")
+            )
+            rule_value = item.get("ruleId")
+            rule = rule_value if isinstance(rule_value, str) else "eslint/file"
+            relative_path = _relative(path, root)
+            if start is None:
+                location = Location(relative_path)
+            elif end is not None:
+                location = Location(relative_path, region=Region(start, end))
+            else:
+                location = Location(relative_path, position=start)
+            severity_value = item.get("severity")
+            if type(severity_value) is int and severity_value == _ESLINT_ERROR:
+                severity = Severity.ERROR
+            elif type(severity_value) is int and severity_value == 1:
+                severity = Severity.WARNING
+            else:
+                msg = f"unsupported ESLint severity: {severity_value!r}"
+                raise ValueError(msg)
+            diagnostics.append(
+                Diagnostic(
+                    rule,
+                    _redact_message(_text(item, "message"), root),
+                    severity,
+                    "eslint",
+                    location,
+                    rule_id=rule,
+                )
+            )
+    return tuple(diagnostics)
+
+
+def parse_react_doctor(payload: str, *, root: Path) -> tuple[Diagnostic, ...]:
+    report = _ReactDoctorReport.model_validate_json(payload)
+    expected_version = manifest.eslint_peers()["react-doctor"]
+    if report.version != expected_version:
+        msg = f"React Doctor reported version {report.version!r}; expected {expected_version!r}"
+        raise ValueError(msg)
+    if report.error is not None:
+        msg = f"React Doctor scan failed: {report.error.message}"
+        raise ValueError(msg)
+    if not report.ok:
+        msg = "React Doctor report did not complete successfully"
+        raise ValueError(msg)
+    if report.skipped_projects:
+        msg = f"React Doctor skipped {len(report.skipped_projects)} project(s) before analysis"
+        raise ValueError(msg)
+
+    documents: dict[Path, SourceDocument | None] = {}
+    diagnostics: list[Diagnostic] = []
+    for project in report.projects:
+        if not project.complete:
+            msg = f"React Doctor project did not complete: {project.directory!r}"
+            raise ValueError(msg)
+        directory = _contained_report_directory(project, root)
+        for item in project.diagnostics:
+            path = _react_doctor_path(item, directory, root)
+            location = _react_doctor_location(item, path, root, documents)
+            rule = f"{item.plugin}/{item.rule}"
+            diagnostics.append(
+                Diagnostic(
+                    rule,
+                    _redact_message(item.message, root),
+                    Severity.ERROR,
+                    "react-doctor",
+                    location,
+                    rule_id=rule,
+                    help_url=item.url,
+                )
+            )
+    return tuple(diagnostics)
+
+
+def _contained_report_directory(project: _ReactDoctorProject, root: Path) -> Path:
+    directory = Path(project.directory)
+    resolved = (directory if directory.is_absolute() else root / directory).resolve()
+    try:
+        resolved.relative_to(root.resolve())
+    except ValueError as exc:
+        msg = "React Doctor reported a project outside the repository root"
+        raise ValueError(msg) from exc
+    return resolved
+
+
+def _react_doctor_path(item: _ReactDoctorDiagnostic, directory: Path, root: Path) -> Path:
+    raw_path = Path(item.file_path)
+    resolved = (raw_path if raw_path.is_absolute() else directory / raw_path).resolve()
+    try:
+        resolved.relative_to(root.resolve())
+    except ValueError as exc:
+        msg = "React Doctor reported a path outside the repository root"
+        raise ValueError(msg) from exc
+    return resolved
+
+
+def _react_doctor_location(
+    item: _ReactDoctorDiagnostic,
+    path: Path,
+    root: Path,
+    documents: dict[Path, SourceDocument | None],
+) -> Location:
+    relative_path = _relative(path, root)
+    # React Doctor uses the protocol sentinel (0, 0) for project-level
+    # diagnostics that truthfully identify a file but no source position.
+    if item.line == 0 or item.column == 0:
+        return Location(relative_path)
+    start = _one_based_position(
+        {"row": item.line, "column": item.column},
+        path,
+        documents,
+    )
+    if item.end_line is not None and item.end_column is not None:
+        try:
+            end = _one_based_position({"row": item.end_line, "column": item.end_column}, path, documents)
+        except ValueError:
+            end = None
+        if end is not None and (end.line, end.character) >= (start.line, start.character):
+            return Location(relative_path, region=Region(start, end))
+    return Location(relative_path, position=start)
+
+
+def _ruff_argv(files: Sequence[str], *, config: Path | None = None) -> tuple[str, ...]:
+    config_args = () if config is None else ("--config", str(config))
+    return ("ruff", "check", "--output-format", "json", *config_args, "--", *files)
+
+
+def _eslint_json_argv(argv: Sequence[str]) -> tuple[str, ...]:
+    values = list(argv)
+    try:
+        index = values.index("eslint") + 1
+    except ValueError as exc:
+        msg = "ESLint command does not contain an eslint executable"
+        raise ValueError(msg) from exc
+    values[index:index] = ["--format", "json", "--no-warn-ignored", "--no-cache"]
+    return tuple(values)
+
+
+def _argv_file_count(argv: Sequence[str]) -> int:
+    if "--" not in argv:
+        return 0
+    # npm has both a package-manager delimiter and ESLint's file delimiter.
+    # The final delimiter is the analyzer boundary for every supported client.
+    index = max(position for position, value in enumerate(argv) if value == "--")
+    return len(argv) - index - 1
+
+
+def _loads(payload: str) -> object:
+    if not payload.strip():
+        msg = "analyzer returned empty structured output"
+        raise ValueError(msg)
+    return json.loads(payload)  # pyright: ignore[reportAny] -- narrowed immediately.
+
+
+def _prepare_inputs(
+    files: Sequence[str],
+    root: Path,
+    *,
+    policy: Policy | None = None,
+    grouped: GroupedPaths | None = None,
+) -> _PreparedInputs:
+    repository = root.resolve()
+    contained = tuple(_contained_path(item, repository) for item in files)
+    selected = contained if policy is None else policy.filter_paths(contained)
+    return _PreparedInputs(
+        repository, selected, grouped if grouped is not None else group_paths(selected, policy=policy)
+    )
+
+
+def _contained_path(value: str, root: Path) -> str:
+    path = Path(value)
+    resolved = (path if path.is_absolute() else root / path).resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        msg = "analysis path is outside the repository root"
+        raise ValueError(msg) from exc
+    return str(resolved)
+
+
+def _table(value: object, label: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        msg = f"{label} must be an object"
+        raise TypeError(msg)
+    table: dict[str, object] = {}
+    for key, item in value.items():  # pyright: ignore[reportUnknownVariableType] -- dynamic JSON narrowed here.
+        if not isinstance(key, str):
+            msg = f"{label} contains a non-string key"
+            raise TypeError(msg)
+        table[key] = item
+    return table
+
+
+def _array(value: object, label: str) -> list[object]:
+    if not isinstance(value, list):
+        msg = f"{label} must be an array"
+        raise TypeError(msg)
+    return list(value)  # pyright: ignore[reportUnknownArgumentType] -- elements stay opaque.
+
+
+def _text(table: dict[str, object], key: str) -> str:
+    value = table.get(key)
+    if not isinstance(value, str) or not value:
+        msg = f"{key} must be a non-empty string"
+        raise TypeError(msg)
+    return value
+
+
+def _integer(table: dict[str, object], key: str) -> int:
+    value = table.get(key)
+    if type(value) is not int:
+        msg = f"{key} must be an integer"
+        raise TypeError(msg)
+    return value
+
+
+def _path(table: dict[str, object], key: str, root: Path) -> Path:
+    return _reported_path(_text(table, key), root)
+
+
+def _reported_path(value: str, root: Path) -> Path:
+    path = Path(value)
+    resolved = (path if path.is_absolute() else root / path).resolve()
+    try:
+        resolved.relative_to(root.resolve())
+    except ValueError as exc:
+        msg = "analyzer reported a path outside the repository root"
+        raise ValueError(msg) from exc
+    return resolved
+
+
+def _document(path: Path, cache: dict[Path, SourceDocument | None]) -> SourceDocument:
+    resolved = path.resolve()
+    if resolved not in cache:
+        cache[resolved] = SourceDocument.read(resolved)
+    document = cache[resolved]
+    if document is None:
+        msg = "cannot read analyzer source"
+        raise OSError(msg)
+    return document
+
+
+def _one_based_position(value: dict[str, object], path: Path, cache: dict[Path, SourceDocument | None]) -> Position:
+    position = _document(path, cache).point(line=_integer(value, "row"), column=_integer(value, "column"))
+    if position is None:
+        msg = "analyzer position is outside source"
+        raise ValueError(msg)
+    return position
+
+
+def _basedpyright_position(
+    value: _BasedPyrightPosition, path: Path, cache: dict[Path, SourceDocument | None]
+) -> Position:
+    position = _document(path, cache).utf16_point(line=value.line, character=value.character)
+    if position is None:
+        msg = "analyzer position is outside source"
+        raise ValueError(msg)
+    return position
+
+
+def _eslint_position(
+    value: dict[str, object],
+    path: Path,
+    cache: dict[Path, SourceDocument | None],
+    *,
+    line_key: str,
+    column_key: str,
+) -> Position | None:
+    line = value.get(line_key)
+    column = value.get(column_key)
+    if type(line) is not int or type(column) is not int:
+        return None
+    try:
+        return _zero_based_position({"line": line - 1, "character": column - 1}, path, cache)
+    except ValueError:
+        return None
+
+
+def _eslint_start_position(
+    value: dict[str, object], path: Path, cache: dict[Path, SourceDocument | None]
+) -> Position | None:
+    if isinstance(value.get("line"), bool) or isinstance(value.get("column"), bool):
+        msg = "ESLint diagnostic has invalid boolean coordinates"
+        raise TypeError(msg)
+    if value.get("line") == 0:
+        return None
+    return _eslint_position(value, path, cache, line_key="line", column_key="column")
+
+
+def _zero_based_position(value: dict[str, object], path: Path, cache: dict[Path, SourceDocument | None]) -> Position:
+    position = _document(path, cache).utf16_point(line=_integer(value, "line"), character=_integer(value, "character"))
+    if position is None:
+        msg = "analyzer position is outside source"
+        raise ValueError(msg)
+    return position
+
+
+def _severity_text(value: str) -> Severity:
+    try:
+        severity = _ExternalSeverity(value)
+    except ValueError as exc:
+        msg = f"unsupported BasedPyright severity: {value!r}"
+        raise ValueError(msg) from exc
+    match severity:
+        case _ExternalSeverity.ERROR:
+            return Severity.ERROR
+        case _ExternalSeverity.WARNING:
+            return Severity.WARNING
+        case _ExternalSeverity.INFORMATION:
+            return Severity.INFO
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError as exc:
+        msg = "analyzer reported a path outside the repository root"
+        raise ValueError(msg) from exc
+
+
+def _redact_message(value: str, root: Path) -> str:
+    message = value.replace(str(root), ".")
+    message = re.sub(r"(?i)\b(token|secret|password|api[_-]?key)=\S+", r"\1=<redacted>", message)
+    message = re.sub(r"(?i)\b(authorization\s*:\s*bearer)\s+\S+", r"\1 <redacted>", message)
+    message = re.sub(
+        r"(?i)\b((?:aws|azure|gcp|github)?[_-]?(?:access[_-]?key|secret[_-]?access[_-]?key))\s+\S+",
+        r"\1 <redacted>",
+        message,
+    )
+    message = re.sub(r"(?<![\w:./])/(?:[^\s:]+/?)+", "<path>", message)
+    message = re.sub(r"\b[A-Za-z]:\\[^\s]+", "<path>", message)
+    return message[:1024]