errlens-cli 0.1.0__py3-none-any.whl

errlens/models.py

@@ -0,0 +1,120 @@
+"""JSON-friendly contracts; messages remain identifiers until rendering.
+
+Paths are strings so dataclasses.asdict results can be JSON-encoded directly.
+Environment metadata is explicitly supplied context, not an environment dump.
+"""
+
+from dataclasses import dataclass, field
+from typing import TypeAlias
+
+Parameter: TypeAlias = str | int | float | bool | None
+
+
+@dataclass
+class ExecutionContext:
+    """Executable plus arguments, working directory and capture provenance."""
+
+    command: list[str]
+    cwd: str
+    capture_source: str = "runner"
+    environment: dict[str, Parameter] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.command or not self.command[0]:
+            raise ValueError("command must contain a nonempty executable")
+        if not self.cwd or not self.capture_source:
+            raise ValueError("cwd and capture_source must not be empty")
+
+
+@dataclass
+class ExecutionResult:
+    """None means no exit status is available; negative POSIX signals are allowed.
+
+    output_complete describes the diagnostic copy (false when capture truncates),
+    not whether all bytes were forwarded. Forwarding failures raise RunnerError.
+    """
+
+    exit_code: int | None
+    interrupted: bool = False
+    output_complete: bool = True
+
+
+@dataclass
+class StackFrame:
+    """Location reported by Python; no claim that it belongs to user code."""
+
+    file_path: str
+    line_number: int | None = None
+    function: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.line_number is not None and self.line_number < 1:
+            raise ValueError("line_number must be positive or None")
+
+
+@dataclass
+class Diagnostic:
+    """Observed error facts, never a localized explanation or guessed cause."""
+
+    diagnostic_id: str
+    error_type: str
+    original_message: str
+    file_path: str | None = None
+    line_number: int | None = None
+    parameters: dict[str, Parameter] = field(default_factory=dict)
+    incomplete: bool = False
+    frames: list[StackFrame] = field(default_factory=list)
+    source: str | None = None
+    chain_relation: str | None = None
+    related_diagnostic_id: str | None = None
+    complex_structure: bool = False
+    execution_failed: bool | None = None
+
+    def __post_init__(self) -> None:
+        if not self.diagnostic_id or not self.error_type:
+            raise ValueError("diagnostic_id and error_type must not be empty")
+        if self.line_number is not None and self.line_number < 1:
+            raise ValueError("line_number must be positive or None")
+
+
+@dataclass
+class SuggestedCommand:
+    """Display-only argv from trusted rules, guarded by a localized condition."""
+
+    argv: list[str]
+    condition_id: str
+
+
+@dataclass
+class Explanation:
+    """Rule output. Actions, possible causes and conditions are message IDs.
+
+    message_ids maps semantic roles (such as 'problem') to translation keys.
+    actions lists suggested-action message IDs; conditions lists applicability
+    message IDs for the recommendations as a whole. commands holds separate
+    display-only argv with explicit applicability. No execution is implied.
+    """
+
+    rule_id: str
+    message_ids: dict[str, str]
+    parameters: dict[str, Parameter] = field(default_factory=dict)
+    actions: list[str] = field(default_factory=list)
+    conditions: list[str] = field(default_factory=list)
+    causes: list[str] = field(default_factory=list)
+    commands: list[SuggestedCommand] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.rule_id or not self.message_ids:
+            raise ValueError("rule_id and message_ids must not be empty")
+        if any(not role or not key for role, key in self.message_ids.items()):
+            raise ValueError("message roles and IDs must not be empty")
+
+
+@dataclass
+class ExplanationReport:
+    """One primary diagnostic with its actual linked predecessors."""
+
+    diagnostic: Diagnostic
+    explanation: Explanation
+    related: list[Diagnostic] = field(default_factory=list)
+    other_count: int = 0

errlens/posix_shell.py

@@ -0,0 +1,71 @@
+"""Opt-in Bash and Zsh configuration; never runs a shell while installing."""
+
+import os
+from pathlib import Path
+import shlex
+import uuid
+
+OWNER = "# ErrLens managed integration v1"
+
+
+def default_profile(shell: str) -> Path:
+    if os.name == "nt":
+        raise ValueError("Default Bash/Zsh profiles are supported on Linux and macOS only; use --profile for an isolated test.")
+    if shell == "zsh":
+        return Path(os.environ.get("ZDOTDIR") or Path.home()) / ".zshrc"
+    return Path.home() / ".bashrc"
+
+
+def script(shell: str) -> str:
+    resolver = "type -P" if shell == "bash" else "whence -p"
+    existing = "declare -F python >/dev/null" if shell == "bash" else "typeset -f python >/dev/null"
+    return OWNER + "\n" + f'''if {existing} || alias python >/dev/null 2>&1; then
+  printf '%s\\n' 'ErrLens: existing python function or alias preserved' >&2
+else
+  python() {{
+    local target launcher
+    target=$({resolver} python) || {{ printf '%s\\n' 'ErrLens: python not found' >&2; return 127; }}
+    if [ "${{ERRLENS_DISABLE:-}}" = 1 ]; then
+      command "$target" "$@"
+    elif launcher=$({resolver} errlens); then
+      command "$launcher" run -- "$target" "$@"
+    else
+      command "$target" "$@"
+    fi
+  }}
+fi
+'''
+
+
+def manage(action: str, shell: str, profile: Path) -> str:
+    profile = profile.expanduser().absolute()
+    integration = profile.parent / ".errlens" / (profile.name + "." + shell + ".sh")
+    marker = "# ErrLens " + shell + " v1"
+    line = "[ ! -f " + shlex.quote(str(integration)) + " ] || . " + shlex.quote(str(integration)) + " " + marker
+    addition = ("\n" + line + "\n").encode("utf-8")
+    original = profile.read_bytes() if profile.exists() else b""
+    original.decode("utf-8-sig")
+    installed = addition in original
+    if marker.encode() in original and not installed:
+        raise ValueError("ErrLens connection was edited; resolve it manually before changing integration.")
+    if action == "status":
+        return f"{'installed' if installed and integration.exists() else 'not installed'}: {profile}"
+    if integration.exists() and not integration.read_text(encoding="utf-8").startswith(OWNER + "\n"):
+        raise ValueError(f"Refusing to modify unowned integration file: {integration}")
+    if action == "install":
+        integration.parent.mkdir(parents=True, exist_ok=True)
+        if not integration.exists():
+            integration.write_text(script(shell), encoding="utf-8", newline="\n")
+        updated = original if installed else original + addition
+    elif action == "uninstall":
+        updated = original.replace(addition, b"", 1)
+    else:
+        raise ValueError("Unsupported action")
+    if updated != original:
+        profile.parent.mkdir(parents=True, exist_ok=True)
+        if profile.exists():
+            profile.with_name(profile.name + ".errlens-backup-" + uuid.uuid4().hex).write_bytes(original)
+        profile.write_bytes(updated)
+    if action == "uninstall" and integration.exists():
+        integration.unlink()
+    return f"{action}: {profile}; restart or source the profile."

errlens/powershell.py

@@ -0,0 +1,77 @@
+"""Explicit profile edits for the opt-in PowerShell python wrapper."""
+
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import uuid
+
+OWNER = "# ErrLens managed integration v1"
+
+
+def quote(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def default_profile() -> Path:
+    executable = shutil.which("pwsh")
+    if executable is None:
+        raise ValueError("PowerShell 7 (pwsh) was not found; specify --profile explicitly.")
+    result = subprocess.run([executable, "-NoProfile", "-NonInteractive", "-Command",
+                             "if ($PSVersionTable.PSVersion.Major -lt 7) { exit 1 }; $PROFILE.CurrentUserAllHosts"],
+                            capture_output=True, text=True, encoding="utf-8", timeout=15, check=True)
+    return Path(result.stdout.strip())
+
+
+def script() -> str:
+    return OWNER + "\n" + r'''
+if ($PSVersionTable.PSVersion.Major -lt 7) { Write-Warning 'ErrLens requires PowerShell 7'; return }
+$existing = Get-Command python -CommandType Alias,Function -ErrorAction SilentlyContinue
+if ($existing) { Write-Warning 'ErrLens: existing python alias/function preserved'; return }
+function global:python {
+    # ErrLens wrapper: resolve applications only, on every invocation (venv-aware).
+    $target = Get-Command python -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+    if (-not $target) { $global:LASTEXITCODE = 127; Write-Error 'ErrLens: python executable not found'; return }
+    $PSNativeCommandUseErrorActionPreference = $false
+    if ($PSVersionTable.PSVersion -ge [version]'7.3') { $PSNativeCommandArgumentPassing = 'Standard' }
+    if ($env:ERRLENS_DISABLE -eq '1') {
+        & $target.Source @args
+    } else {
+        & __RUNTIME__ -m errlens run -- $target.Source @args
+    }
+    $global:LASTEXITCODE = $LASTEXITCODE
+}
+'''.replace("__RUNTIME__", quote(sys.executable))
+
+
+def manage(action: str, profile: Path) -> str:
+    profile = profile.expanduser().absolute()
+    integration = profile.parent / "ErrLens" / (profile.name + ".python.ps1")
+    line = ("if (Test-Path -LiteralPath " + quote(str(integration)) + ") { . "
+            + quote(str(integration)) + " } # ErrLens v1")
+    addition = ("\n" + line + "\n").encode("utf-8")
+    original = profile.read_bytes() if profile.exists() else b""
+    original.decode("utf-8-sig")  # Refuse unsupported encodings rather than corrupting them.
+    installed = addition in original
+    if b"# ErrLens v1" in original and not installed:
+        raise ValueError("ErrLens profile line was edited; restore it from backup before changing integration.")
+    if action == "status":
+        return f"{'installed' if installed and integration.exists() else 'not installed'}: {profile}"
+    if integration.exists() and not integration.read_text(encoding="utf-8").startswith(OWNER + "\n"):
+        raise ValueError(f"Refusing to modify an unowned integration file: {integration}")
+    if action == "install":
+        integration.parent.mkdir(parents=True, exist_ok=True)
+        if not integration.exists():
+            integration.write_text(script(), encoding="utf-8", newline="\n")
+        updated = original if installed else original + addition
+    else:
+        updated = original.replace(addition, b"", 1)
+    if updated != original:
+        profile.parent.mkdir(parents=True, exist_ok=True)
+        if profile.exists():
+            backup = profile.with_name(profile.name + ".errlens-backup-" + uuid.uuid4().hex)
+            backup.write_bytes(original)
+        profile.write_bytes(updated)
+    if action == "uninstall" and integration.exists():
+        integration.unlink()
+    return f"{action}: {profile}. Restart PowerShell to apply."

errlens/pty_runner.py

@@ -0,0 +1,172 @@
+"""PTY dispatch and POSIX transport; platform-specific imports remain lazy."""
+
+import os
+import signal
+import subprocess
+import sys
+import threading
+import time
+from typing import BinaryIO
+
+from errlens.capture import TerminalCapture
+from errlens.models import ExecutionContext, ExecutionResult
+from errlens.runner import RunnerError
+
+
+def run(context: ExecutionContext, capture: TerminalCapture, stdout: BinaryIO,
+        *, input_fd: int = 0) -> ExecutionResult:
+    if sys.platform == "win32":
+        from errlens.conpty_runner import run as run_conpty
+        return run_conpty(context, capture, stdout, input_fd=input_fd)
+    import errno
+    import fcntl
+    import pty
+    import select
+    import termios
+    import tty
+
+    if threading.current_thread() is not threading.main_thread():
+        raise RunnerError("pty", "PTY mode must run on the main thread")
+    if not os.isatty(input_fd) or not os.isatty(stdout.fileno()):
+        raise RunnerError("pty", "PTY mode requires terminal stdin and stdout; use pipe for redirection")
+    saved = termios.tcgetattr(input_fd)
+    previous = {number: signal.getsignal(number) for number in (signal.SIGINT, signal.SIGWINCH)}
+    master = slave = error_read = error_write = -1
+    process: subprocess.Popen[bytes] | None = None
+    cancel = False
+    resized = True
+    completed = False
+
+    def on_interrupt(signum: int, frame: object) -> None:
+        nonlocal cancel
+        cancel = True
+
+    def on_resize(signum: int, frame: object) -> None:
+        nonlocal resized
+        resized = True
+
+    def send(number: int, *, initial: bool = False) -> None:
+        if process is None:
+            return
+        groups = {process.pid} if initial else set()
+        try:
+            groups.add(os.tcgetpgrp(master))
+        except OSError:
+            groups.add(process.pid)
+        for group in groups:
+            if group > 0 and group != os.getpgrp():
+                try:
+                    os.killpg(group, number)
+                except ProcessLookupError:
+                    pass
+
+    try:
+        master, slave = pty.openpty()
+        fcntl.ioctl(slave, termios.TIOCSWINSZ, fcntl.ioctl(input_fd, termios.TIOCGWINSZ, b"\0" * 8))
+        error_read, error_write = os.pipe()
+        process = subprocess.Popen(
+            [sys.executable, "-m", "errlens._pty_child", str(error_write), *context.command],
+            cwd=context.cwd, stdin=slave, stdout=slave, stderr=slave,
+            pass_fds=(error_write,), start_new_session=True, shell=False,
+        )
+        os.close(slave)
+        slave = -1
+        os.close(error_write)
+        error_write = -1
+        os.set_blocking(master, False)
+        signal.signal(signal.SIGINT, on_interrupt)
+        signal.signal(signal.SIGWINCH, on_resize)
+        tty.setraw(input_fd, termios.TCSANOW)
+        pending = bytearray()
+        eof = False
+        checking_launch = True
+        cancel_deadline: float | None = None
+        drain_deadline: float | None = None
+        eof_deadline: float | None = None
+        while True:
+            now = time.monotonic()
+            if resized:
+                fcntl.ioctl(master, termios.TIOCSWINSZ,
+                            fcntl.ioctl(input_fd, termios.TIOCGWINSZ, b"\0" * 8))
+                resized = False
+            if cancel and cancel_deadline is None:
+                send(signal.SIGINT)
+                cancel_deadline = now + 1
+            if cancel_deadline is not None and now >= cancel_deadline:
+                send(signal.SIGKILL, initial=True)
+            status = process.poll()
+            if eof_deadline is not None and status is None and now >= eof_deadline:
+                raise RunnerError("pty_eof", "Terminal closed while child remained alive")
+            if status is not None:
+                if eof:
+                    break
+                if drain_deadline is None:
+                    drain_deadline = now + 1
+                if now >= drain_deadline:
+                    raise RunnerError("drain", "PTY did not close after process exit")
+            reads = ([] if eof else [master]) + ([input_fd] if len(pending) < 65536 and status is None else [])
+            if checking_launch:
+                reads.append(error_read)
+            ready, writable, _ = select.select(reads, [master] if pending and not eof else [], [], 0.05)
+            if error_read in ready:
+                message = os.read(error_read, 4096)
+                checking_launch = False
+                if message:
+                    raise RunnerError("pty_launch", message.decode("utf-8", errors="replace"),
+                                      127 if message.startswith(b"2:") else 126)
+            if master in ready:
+                try:
+                    data = os.read(master, 65536)
+                except BlockingIOError:
+                    data = None
+                except OSError as exc:
+                    if exc.errno != errno.EIO:
+                        raise
+                    data = b""  # Linux slave hangup; macOS commonly returns EOF.
+                if data == b"":
+                    eof = True
+                    eof_deadline = now + 1
+                elif data:
+                    capture.combined.append(data)
+                    offset = 0
+                    while offset < len(data):
+                        written = stdout.write(data[offset:])
+                        if written is None or written <= 0:
+                            raise OSError("Output stream made no progress")
+                        offset += written
+                    stdout.flush()
+            if input_fd in ready:
+                data = os.read(input_fd, 4096)
+                if not data:
+                    raise RunnerError("pty_input", "Host terminal input closed")
+                pending.extend(data)
+            if master in writable and not eof:
+                try:
+                    written = os.write(master, pending)
+                    del pending[:written]
+                except BlockingIOError:
+                    pass
+        completed = True
+        return ExecutionResult(status, cancel or status == -signal.SIGINT, not capture.truncated)
+    except BrokenPipeError as exc:
+        raise RunnerError("broken_pipe", str(exc), 141) from exc
+    except OSError as exc:
+        raise RunnerError("pty", str(exc)) from exc
+    finally:
+        try:
+            if process is not None:
+                if process.poll() is None or not completed:
+                    send(signal.SIGKILL, initial=True)
+                try:
+                    process.wait(timeout=2)
+                except subprocess.TimeoutExpired as exc:
+                    raise RunnerError("cleanup", "PTY child did not exit after kill") from exc
+        finally:
+            try:
+                termios.tcsetattr(input_fd, termios.TCSANOW, saved)
+            finally:
+                for number, handler in previous.items():
+                    signal.signal(number, handler)
+                for fd in (master, slave, error_read, error_write):
+                    if fd >= 0:
+                        os.close(fd)

errlens/render.py

@@ -0,0 +1,96 @@
+"""Render ErrLens-owned text in memory; child bytes never pass through Rich."""
+
+import io
+import os
+import shlex
+import unicodedata
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from errlens.i18n import Translator
+from errlens.models import ExplanationReport, Parameter
+
+
+def safe_text(value: object, limit: int = 2048) -> str:
+    """Escape control/bidi characters, retaining literal Rich markup and Unicode."""
+    raw = str(value)
+    clipped = raw[:limit]
+    text = "".join(
+        (f"\\u{ord(character):04x}" if ord(character) > 255 else f"\\x{ord(character):02x}")
+        if unicodedata.category(character).startswith("C") else character
+        for character in clipped
+    )
+    return text + ("…" if len(raw) > limit else "")
+
+
+def format_command(argv: list[str], *, windows: bool) -> str:
+    """Quote display-only argv for POSIX shell or PowerShell (never cmd.exe)."""
+    if windows:
+        return "& " + " ".join("'" + part.replace("'", "''") + "'" for part in argv)
+    return shlex.join(argv)
+
+
+def render_report(
+    report: ExplanationReport, translator: Translator, *, terminal: bool,
+    width: int = 80, color: bool = True, windows: bool | None = None,
+) -> str:
+    """Stage the entire block before writing; no partial card on build failure."""
+    explanation, diagnostic = report.explanation, report.diagnostic
+    parameters: dict[str, Parameter] = {
+        key: safe_text(value) for key, value in explanation.parameters.items()
+    }
+
+    def translated(key: str) -> str:
+        return translator.translate(key, **parameters)
+
+    body = Text(overflow="fold")
+    body.append(translated(explanation.message_ids["title"]) + "\n", style="bold")
+    body.append(translated(explanation.message_ids["description"]) + "\n")
+    if "detail" in explanation.message_ids:
+        body.append(translated(explanation.message_ids["detail"]) + "\n")
+    if diagnostic.original_message:
+        body.append(translator.translate("render.original", message=safe_text(diagnostic.original_message)) + "\n")
+    if diagnostic.file_path is not None:
+        body.append(translator.translate("render.file", path=safe_text(diagnostic.file_path)) + "\n")
+    if diagnostic.line_number is not None:
+        body.append(translator.translate("render.line", line=diagnostic.line_number) + "\n")
+    if diagnostic.incomplete:
+        body.append(translator.translate("render.incomplete") + "\n", style="bold")
+    for cause in explanation.causes:
+        body.append(translator.translate("render.possible") + " " + translated(cause) + "\n")
+    body.append("\n" + translator.translate("render.actions") + "\n", style="bold")
+    for action in explanation.actions:
+        body.append("• " + translated(action) + "\n")
+    for condition in explanation.conditions:
+        body.append(translator.translate("render.condition") + " " + translated(condition) + "\n")
+    for command in explanation.commands:
+        shell = "PowerShell" if (os.name == "nt" if windows is None else windows) else "POSIX shell"
+        body.append("\n" + translator.translate("render.command", shell=shell) + "\n", style="bold")
+        body.append(safe_text(format_command(command.argv, windows=shell == "PowerShell"), limit=8192) + "\n")
+        body.append(translated(command.condition_id) + "\n")
+    if report.related:
+        body.append("\n" + translator.translate("render.related") + "\n", style="bold")
+        for predecessor in report.related[:5]:
+            body.append("• " + safe_text(predecessor.error_type) + ": "
+                        + safe_text(predecessor.original_message, limit=256) + "\n")
+        if len(report.related) > 5:
+            body.append(translator.translate("render.more", count=len(report.related) - 5) + "\n")
+        if diagnostic.chain_relation in {"context", "cause"}:
+            body.append(translator.translate("render.chain." + diagnostic.chain_relation) + "\n")
+    if report.other_count:
+        body.append(translator.translate("render.other", count=report.other_count) + "\n")
+    output = io.StringIO()
+    console = Console(file=output, force_terminal=terminal, force_jupyter=False,
+                      color_system="auto" if terminal and color else None,
+                      width=max(12, width), height=25, legacy_windows=False,
+                      highlight=False, markup=False)
+    title = Text(translator.translate("render.header"), style="bold")
+    console.print()
+    if terminal and width >= 30:
+        console.print(Panel(body, title=title, title_align="left", border_style="blue", padding=(0, 1)))
+    else:
+        console.print(title)
+        console.print(body)
+    return output.getvalue()

errlens/rules/__init__.py

@@ -0,0 +1 @@
+"""Rules will map diagnostic facts to locale-independent explanations."""

errlens/rules/python.py

@@ -0,0 +1,84 @@
+"""Locale-independent explanation rules. Commands are display-only fixed argv."""
+
+import os
+import re
+from types import MappingProxyType
+from typing import Mapping
+import unicodedata
+
+from errlens.models import Diagnostic, ExecutionContext, Explanation, SuggestedCommand
+
+RULE_IDS: Mapping[str, str] = MappingProxyType({
+    "ModuleNotFoundError": "python.module_not_found",
+    "ImportError": "python.import_error",
+    "SyntaxError": "python.syntax_error",
+    "IndentationError": "python.indentation_error",
+    "TabError": "python.tab_error",
+    "NameError": "python.name_error",
+    "TypeError": "python.type_error",
+    "AttributeError": "python.attribute_error",
+    "KeyError": "python.key_error",
+    "FileNotFoundError": "python.file_not_found",
+    "PermissionError": "python.permission_error",
+})
+
+
+def rule_id_for(error_type: str) -> str | None:
+    """Unknown/custom types have no rule; do not guess their inheritance."""
+    return RULE_IDS.get(error_type)
+
+
+# Exact imports only. Do not infer distribution names or strip module suffixes.
+_PACKAGES = MappingProxyType({"requests": "requests"})
+_PYTHON_EXECUTABLE = re.compile(r"(?:pythonw?|python[0-9]+(?:\.[0-9]+)*|pypy[0-9]*)", re.I)
+
+
+def _known_interpreter(context: ExecutionContext) -> str | None:
+    executable = context.command[0]
+    name = os.path.basename(executable)
+    if name.lower().endswith(".exe"):
+        name = name[:-4]
+    if len(executable) > 1024 or not os.path.isabs(executable) or not _PYTHON_EXECUTABLE.fullmatch(name):
+        return None
+    if any(unicodedata.category(character).startswith("C") for character in executable):
+        return None
+    # Avoid promising the same import environment with isolation/site flags.
+    if len(context.command) > 1 and context.command[1].startswith("-"):
+        if context.command[1] not in {"-c", "-m"}:
+            return None
+    return executable
+
+
+def explain(diagnostic: Diagnostic, context: ExecutionContext) -> Explanation:
+    """Explain known facts; unknown/incomplete types receive neutral notices."""
+    if diagnostic.incomplete:
+        rule = "python.incomplete"
+    elif diagnostic.complex_structure or diagnostic.error_type in {"ExceptionGroup", "BaseExceptionGroup"}:
+        rule = "python.exception_group"
+    else:
+        rule = rule_id_for(diagnostic.error_type) or "python.unknown"
+    explanation = Explanation(
+        rule, {"title": f"{rule}.title", "description": f"{rule}.description"},
+        parameters={**diagnostic.parameters, "error_type": diagnostic.error_type},
+        actions=[f"{rule}.action"], conditions=[f"{rule}.condition"],
+    )
+    # The possible-cause sentence is explicitly hypothetical, never a diagnosis.
+    if rule in RULE_IDS.values():
+        explanation.causes.append(f"{rule}.cause")
+    detail_fields = {
+        "ModuleNotFoundError": "module_name", "ImportError": "import_name",
+        "NameError": "name", "AttributeError": "attribute_name", "KeyError": "key_repr",
+        "FileNotFoundError": "file_path", "PermissionError": "file_path",
+    }
+    detail = detail_fields.get(diagnostic.error_type)
+    if detail and detail in diagnostic.parameters and not diagnostic.incomplete:
+        explanation.message_ids["detail"] = f"detail.{detail}"
+    module = diagnostic.parameters.get("module_name")
+    interpreter = _known_interpreter(context)
+    if (rule == "python.module_not_found" and isinstance(module, str)
+            and module in _PACKAGES and interpreter is not None):
+        explanation.commands.append(SuggestedCommand(
+            [interpreter, "-m", "pip", "install", _PACKAGES[module]],
+            "command.install_condition",
+        ))
+    return explanation